From debd8ea35be24ea71e93249862826cd67b095358 Mon Sep 17 00:00:00 2001 From: koo-taejin Date: Fri, 15 Apr 2016 10:23:15 +0900 Subject: [PATCH] Update installation.md #1689 fixed url ( https://github.com/naver/pinpoint/blob/master/scripts -> https://github.com/naver/pinpoint/tree/master/hbase/scripts) --- doc/installation.md | 426 ++++++++++++++++++++++---------------------- 1 file changed, 213 insertions(+), 213 deletions(-) diff --git a/doc/installation.md b/doc/installation.md index e6feef79c..a6011b4da 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -1,220 +1,220 @@ -# Installation -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](../quickstart/README.md). - -## Quick Overview -1. HBase ([details](#hbase)) - 1. Set up HBase cluster - [Apache HBase](http://hbase.apache.org) - 2. Create HBase Schemas - feed `/scripts/hbase-create.hbase` to hbase shell. -2. Build Pinpoint (Only required if you're building from source) - 1. Clone Pinpoint - `git clone $PINPOINT_GIT_REPOSITORY` - 2. Set JAVA_6_HOME environment variable to JDK 6 home directory. - 2. Set JAVA_7_HOME environment variable to JDK 7+ home directory. - 3. Run `mvn install -Dmaven.test.skip=true` in Pinpoint home directory. -3. Pinpoint Collector ([details](#pinpoint-collector)) - 1. Deploy *pinpoint-collector-$VERSION.war* to a web container. - 2. Configure *pinpoint-collector.properties*, *hbase.properties*. - 3. Start container. -4. Pinpoint Web ([details](#pinpoint-web)) - 1. Deploy *pinpoint-web-$VERSION.war* to a web container. - 2. Configure *pinpoint-web.properties*, *hbase.properties*. - 3. Start container. -5. Pinpoint Agent ([details](#pinpoint-agent)) - 1. Extract/move *pinpoint-agent/* to a convenient location (`$AGENT_PATH`). - 2. Set `-javaagent:$AGENT_PATH/pinpoint-bootstrap-$VERSION.jar` JVM argument to attach the agent to a java application. - 3. Set `-Dpinpoint.agentId` and `-Dpinpoint.applicationName` command-line arguments. - 4. Launch java application with the options above. - -## HBase -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](http://hbase.apache.org) 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. - -### Creating Schemas -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](http://code.google.com/p/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](../scripts/ "Pinpoint HBase scripts") for a complete list of scripts. - -## Building Pinpoint - -There are two options: - -1. Download the build results from our [**latest release**](https://github.com/naver/pinpoint/releases/latest) and skip the building. **Recommended.** - -2. 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](../profiler-optional/README.md). - - 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. - -## Pinpoint Collector -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. - -### Installation -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. - -### Configuration -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) +# Installation +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](../quickstart/README.md). + +## Quick Overview +1. HBase ([details](#hbase)) + 1. Set up HBase cluster - [Apache HBase](http://hbase.apache.org) + 2. Create HBase Schemas - feed `/scripts/hbase-create.hbase` to hbase shell. +2. Build Pinpoint (Only required if you're building from source) + 1. Clone Pinpoint - `git clone $PINPOINT_GIT_REPOSITORY` + 2. Set JAVA_6_HOME environment variable to JDK 6 home directory. + 2. Set JAVA_7_HOME environment variable to JDK 7+ home directory. + 3. Run `mvn install -Dmaven.test.skip=true` in Pinpoint home directory. +3. Pinpoint Collector ([details](#pinpoint-collector)) + 1. Deploy *pinpoint-collector-$VERSION.war* to a web container. + 2. Configure *pinpoint-collector.properties*, *hbase.properties*. + 3. Start container. +4. Pinpoint Web ([details](#pinpoint-web)) + 1. Deploy *pinpoint-web-$VERSION.war* to a web container. + 2. Configure *pinpoint-web.properties*, *hbase.properties*. + 3. Start container. +5. Pinpoint Agent ([details](#pinpoint-agent)) + 1. Extract/move *pinpoint-agent/* to a convenient location (`$AGENT_PATH`). + 2. Set `-javaagent:$AGENT_PATH/pinpoint-bootstrap-$VERSION.jar` JVM argument to attach the agent to a java application. + 3. Set `-Dpinpoint.agentId` and `-Dpinpoint.applicationName` command-line arguments. + 4. Launch java application with the options above. + +## HBase +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](http://hbase.apache.org) 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. + +### Creating Schemas +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](http://code.google.com/p/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](../hbase/scripts/ "Pinpoint HBase scripts") for a complete list of scripts. + +## Building Pinpoint + +There are two options: + +1. Download the build results from our [**latest release**](https://github.com/naver/pinpoint/releases/latest) and skip the building. **Recommended.** + +2. 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](../profiler-optional/README.md). + + 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. + +## Pinpoint Collector +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. + +### Installation +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. + +### Configuration +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](../collector/src/main/resources/pinpoint-collector.properties), [hbase.properties](../collector/src/main/resources/hbase.properties) - -## Pinpoint Web -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. - -### Installation -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. - -### Configuration -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](../web/src/main/resources/pinpoint-web.properties), [hbase.properties](../web/src/main/resources/hbase.properties) - -## Pinpoint Agent -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`. - -### Installation -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. - -### Configuration - -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](../agent/src/main/resources/pinpoint.config "pinpoint.config") along with all the available configuration options. - -## Miscellaneous - -### Routing web requests to agents - -Starting from 1.5.0, Pinpoint can send requests from the web to agents directly via the collector (and vice-versa). To make this possible, we use Zookeeper to co-ordinate the communication channels established between agents and collectors, and those between collectors and web instances. With this addition, real-time communication (for things like active thread count monitoring) is now possible. - -We typially use the Zookeeper instance provided by the HBase backend so no additional Zookeeper configuration is required. Related configuration options are shown below. - +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](../collector/src/main/resources/pinpoint-collector.properties), [hbase.properties](../collector/src/main/resources/hbase.properties) + +## Pinpoint Web +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. + +### Installation +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. + +### Configuration +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](../web/src/main/resources/pinpoint-web.properties), [hbase.properties](../web/src/main/resources/hbase.properties) + +## Pinpoint Agent +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`. + +### Installation +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. + +### Configuration + +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](../agent/src/main/resources/pinpoint.config "pinpoint.config") along with all the available configuration options. + +## Miscellaneous + +### Routing web requests to agents + +Starting from 1.5.0, Pinpoint can send requests from the web to agents directly via the collector (and vice-versa). To make this possible, we use Zookeeper to co-ordinate the communication channels established between agents and collectors, and those between collectors and web instances. With this addition, real-time communication (for things like active thread count monitoring) is now possible. + +We typially use the Zookeeper instance provided by the HBase backend so no additional Zookeeper configuration is required. Related configuration options are shown below. + * **Collector** - *pinpoint-collector.properties* * `cluster.enable` * `cluster.zookeeper.address` * `cluster.zookeeper.sessiontimeout` * `cluster.listen.ip` - * `cluster.listen.port` -* **Web** - *pinpoint-web.properties* - * `cluster.enable` - * `cluster.web.tcp.port` - * `cluster.zookeeper.address` - * `cluster.zookeeper.sessiontimeout` - * `cluster.zookeeper.retry.interval` - * `cluster.connect.address` + * `cluster.listen.port` +* **Web** - *pinpoint-web.properties* + * `cluster.enable` + * `cluster.web.tcp.port` + * `cluster.zookeeper.address` + * `cluster.zookeeper.sessiontimeout` + * `cluster.zookeeper.retry.interval` + * `cluster.connect.address`