In order to set up your very own Pinpoint instance, you need to run these components:
- HBase (for storage)
- Pinpoint Collector (deployed on a web container)
- Pinpoint Web (deployed on a web container)
- Pinpoint Agent (attached to a java application for profiling)
To try out a simple quickstart project, please refer to the quick-start guide.
- HBase (details)
- Set up HBase cluster - Apache HBase
- Create HBase Schemas - feed
/scripts/hbase-create.hbase
to hbase shell.
- Build Pinpoint (Only required if you're building from source)
- Clone Pinpoint -
git clone $PINPOINT_GIT_REPOSITORY
- Set JAVA_6_HOME environment variable to JDK 6 home directory.
- Set JAVA_7_HOME environment variable to JDK 7+ home directory.
- Run
mvn install -Dmaven.test.skip=true
in Pinpoint home directory.
- Clone Pinpoint -
- Pinpoint Collector (details)
- Deploy pinpoint-collector-$VERSION.war to a web container.
- Configure pinpoint-collector.properties, hbase.properties.
- Start container.
- Pinpoint Web (details)
- Deploy pinpoint-web-$VERSION.war to a web container.
- Configure pinpoint-web.properties, hbase.properties.
- Start container.
- Pinpoint Agent (details)
- Extract/move pinpoint-agent/ to a convenient location (
$AGENT_PATH
). - Set
-javaagent:$AGENT_PATH/pinpoint-bootstrap-$VERSION.jar
JVM argument to attach the agent to a java application. - Set
-Dpinpoint.agentId
and-Dpinpoint.applicationName
command-line arguments. - Launch java application with the options above.
- Extract/move pinpoint-agent/ to a convenient location (
Pinpoint uses HBase as its storage backend for the Collector and the Web.
To set up your own cluster, take a look at the HBase website for instructions. The HBase compatibility table is given below:
Pinpoint Version | HBase 0.94.x | HBase 0.98.x | HBase 1.0.x | HBase 1.1.x |
---|---|---|---|---|
1.0.x | yes | no | no | no |
1.1.x | no | not tested | yes | not tested |
1.5.x | no | not tested | yes | not tested |
Once you have HBase up and running, make sure the Collector and the Web are configured properly and are able to connect to HBase.
There are 2 scripts available to create tables for Pinpoint: hbase-create.hbase, and hbase-create-snappy.hbase. Use hbase-create-snappy.hbase for snappy compression (requires snappy), otherwise use hbase-create.hbase instead.
To run these scripts, feed them into the HBase shell like below:
$HBASE_HOME/bin/hbase shell hbase-create.hbase
See here for a complete list of scripts.
There are two options:
-
Download the build results from our latest release and skip the building. Recommended.
-
Build Pinpoint manually from the Git clone.
In order to do so, the following requirements must be met:
- JDK 6 installed
- JDK 7+ installed
- Maven 3.2.x+ installed
- JAVA_6_HOME environment variable set to JDK 6 home directory.
- JAVA_7_HOME environment variable set to JDK 7+ home directory.
JDK 7+ and JAVA_7_HOME environment variable are required to build profiler-optional. For more information about the optional package, please take a look here.
Additionally, the required Java version to run each Pinpoint component is given below:
Pinpoint Version Agent Collector Web 1.0.x 6+ 6+ 6+ 1.1.x 6+ 7+ 7+ 1.5.x 6+ 7+ 7+ Once the above requirements are met, simply run the command below :
mvn install -Dmaven.test.skip=true
The guide will refer to the full path of the pinpoint home directory as
$PINPOINT_PATH
.
Regardless of your method, you should end up with the files and directories mentioned in the following sections.
You should have the following war file that can be deployed to a web container.
pinpoint-collector-$VERSION.war
The path to this file should look like $PINPOINT_PATH/collector/target/pinpoint-collector-$VERSION.war if you built it manually.
Since Pinpoint Collector is packaged as a deployable war file, you may deploy them to a web container as you would any other web applications.
There are 2 configuration files available for Pinpoint Collector: pinpoint-collector.properties, and hbase.properties.
- pinpoint-collector.properties - contains configurations for the collector. Check the following values with the agent's configuration options :
collector.tcpListenPort
(agent's profiler.collector.tcp.port - default: 9994)collector.udpStatListenPort
(agent's profiler.collector.stat.port - default: 9995)collector.udpSpanListenPort
(agent's profiler.collector.span.port - default: 9996)
- hbase.properties - contains configurations to connect to HBase.
hbase.client.host
(default: localhost)hbase.client.port
(default: 2181)
These files are located under WEB-INF/classes/
inside the war file.
You may take a look at the default configuration files here: pinpoint-collector.properties, hbase.properties
You should have the following war file that can be deployed to a web container.
pinpoint-web-$VERSION.war
The path to this file should look like $PINPOINT_PATH/web/target/pinpoint-web-$VERSION.war if you built it manually.
Since Pinpoint Web is packaged as a deployable war file, you may deploy them to a web container as you would any other web applications.
Similar to the collector, Pinpoint Web has configuration files related to installation: pinpoint-web.properties, and hbase.properties.
Make sure you check the following configuration options :
- hbase.properties - contains configurations to connect to HBase.
hbase.client.host
(default: localhost)hbase.client.port
(default: 2181)
These files are located under WEB-INF/classes/
inside the war file.
You may take a look at the default configuration files here: pinpoint-web.properties, hbase.properties
If downloaded, unzip the Pinpint Agent file. You should have a pinpoint-agent directory with the layout below :
pinpoint-agent
|-- boot
| |-- pinpoint-bootstrap-core-$VERSION.jar
|-- lib
| |-- pinpoint-profiler-$VERSION.jar
| |-- pinpoint-profiler-optional-$VERSION.jar
| |-- pinpoint-rpc-$VERSION.jar
| |-- pinpoint-thrift-$VERSION.jar
| |-- ...
|-- pinpoint-bootstrap-$VERSION.jar
|-- pinpoint.config
The path to this directory should look like $PINPOINT_PATH/agent/target/pinpoint-agent if you built it manually.
You may move/extract the contents of pinpoint-agent directory to any location of your choice. The guide will refer to the full path of this directory as $AGENT_PATH
.
Pinpoint Agent runs as a java agent attached to an application to be profiled (such as Tomcat).
To wire up the agent, pass $AGENT_PATH/pinpoint-bootstrap-$VERSION.jar to the -javaagent JVM argument when running the application:
-javaagent:$AGENT_PATH/pinpoint-bootstrap-$VERSION.jar
Additionally, Pinpoint Agent requires 2 command-line arguments in order to identify itself in the distributed system:
-Dpinpoint.agentId
- uniquely identifies the application instance in which the agent is running on-Dpinpoint.applicationName
- groups a number of identical application instances as a single service
Note that pinpoint.agentId must be globally unique to identify an application instance, and all applications that share the same pinpoint.applicationName are treated as multiple instances of a single service.
Tomcat Example
Add -javaagent, -Dpinpoint.agentId, -Dpinpoint.applicationName to CATALINA_OPTS in the Tomcat startup script (catalina.sh).
CATALINA_OPTS="$CATALINA_OPTS -javaagent:$AGENT_PATH/pinpoint-bootstrap-$VERSION.jar" CATALINA_OPTS="$CATALINA_OPTS -Dpinpoint.agentId=$AGENT_ID" CATALINA_OPTS="$CATALINA_OPTS -Dpinpoint.applicationName=$APPLICATION_NAME"
Start up Tomcat to start profiling your web application.
There are various configuration options for Pinpoint Agent available in $AGENT_PATH/pinpoint.config.
Most of these options are self explanatory, but the most important configuration options you must check are collector ip address, and the TCP/UDP ports. These values are required for the agent to establish connection to the Collector and function correctly.
Set these values appropriately in pinpoint.config:
profiler.collector.ip
(default: 127.0.0.1)profiler.collector.tcp.port
(collector's collector.tcpListenPort - default: 9994)profiler.collector.stat.port
(collector's collector.udpStatListenPort - default: 9995)profiler.collector.span.port
(collector's collector.udpSpanListenPort - default: 9996)
You may take a look at the default pinpoint.config file here along with all the available configuration options.