From 975c04007c9da12367a81a1a9fa012b742c15e57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=90=B4=E6=99=9F=20Wu=20Sheng?= Date: Mon, 11 Jun 2018 16:23:35 +0800 Subject: [PATCH] Deploy document reformat (#1337) * Refactor English documents to guide end users. --- .../src/main/resources/application.yml | 20 +++-- docs/README.md | 14 ++-- docs/README_ZH.md | 8 +- docs/en/Deploy-backend-in-cluster-mode.md | 79 +++++++++++++------ docs/en/Deploy-backend-in-standalone-mode.md | 9 ++- docs/en/Deploy-skywalking-agent.md | 6 +- docs/en/Quick-start.md | 17 ++-- 7 files changed, 101 insertions(+), 52 deletions(-) diff --git a/apm-collector/apm-collector-boot/src/main/resources/application.yml b/apm-collector/apm-collector-boot/src/main/resources/application.yml index a5f995ded..985ddbbf3 100644 --- a/apm-collector/apm-collector-boot/src/main/resources/application.yml +++ b/apm-collector/apm-collector-boot/src/main/resources/application.yml @@ -20,6 +20,7 @@ # sessionTimeout: 100000 naming: jetty: + #OS real network IP(binding required), for agent to find collector cluster host: localhost port: 10800 contextPath: / @@ -28,20 +29,25 @@ cache: caffeine: remote: gRPC: + # OS real network IP(binding required), for collector nodes communicate with each other in cluster. collectorN --(gRPC) --> collectorM host: localhost port: 11800 agent_gRPC: gRPC: + #OS real network IP(binding required), for agent to uplink data(trace/metrics) to collector. agent--(gRPC)--> collector host: localhost port: 11800 - #Set these two setting to open ssl + # Set these two setting to open ssl #sslCertChainFile: $path #sslPrivateKeyFile: $path - #Set your own token to active auth + # Set your own token to active auth #authentication: xxxxxx agent_jetty: jetty: + # OS real network IP(binding required), for agent to uplink data(trace/metrics) to collector through HTTP. agent--(HTTP)--> collector + # SkyWalking native Java/.Net/node.js agents don't use this. + # Open this for other implementor. host: localhost port: 12800 contextPath: / @@ -57,6 +63,8 @@ analysis_segment_parser: bufferFileCleanWhenRestart: true ui: jetty: + # Stay in `localhost` if UI starts up in default mode. + # Change it to OS real network IP(binding required), if deploy collector in different machine. host: localhost port: 12800 contextPath: / @@ -80,8 +88,8 @@ storage: # userName: sa configuration: default: -# namespace: xxxxx -# alarm threshold + #namespace: xxxxx + # alarm threshold applicationApdexThreshold: 2000 serviceErrorRateThreshold: 10.00 serviceAverageResponseTimeThreshold: 2000 @@ -89,8 +97,8 @@ configuration: instanceAverageResponseTimeThreshold: 2000 applicationErrorRateThreshold: 10.00 applicationAverageResponseTimeThreshold: 2000 -# thermodynamic + # thermodynamic thermodynamicResponseTimeStep: 50 thermodynamicCountOfResponseTimeSteps: 40 -# max collection's size of worker cache collection, setting it smaller when collector OutOfMemory crashed. + # max collection's size of worker cache collection, setting it smaller when collector OutOfMemory crashed. workerCacheMaxSize: 10000 \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index df354ec8b..53e474e40 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,11 +3,13 @@ * Getting Started * [Quick start](en/Quick-start.md) + * [Install javaagent](en/Deploy-skywalking-agent.md) + * [Deploy backend in cluster mode](en/Deploy-backend-in-cluster-mode.md) * [Supported middlewares, frameworks and libraries](Supported-list.md) * [How to disable plugins?](en/How-to-disable-plugin.md) * [Optional plugins](en/Optional-plugins.md) * Advanced Features - * [Override settings through System.properties or System.env](en/Setting-override.md) + * [Override settings through System.properties](en/Setting-override.md) * [Direct uplink and disable naming discovery](en/Direct-uplink.md) * [Open TLS](en/TLS.md) * [Namespace Isolation](en/Namespace.md) @@ -15,16 +17,16 @@ * [Add your own component library settings in collector](en/Component-libraries-extend.md) * Incubating Features * [Abstract](en/Incubating/Abstract.md) - * [Support Custom Trace Ignore](../apm-sniffer/optional-plugins/trace-ignore-plugin/README.md) + * [Filter traces through custom services](../apm-sniffer/optional-plugins/trace-ignore-plugin/README.md) * Application Toolkit * [Overview](en/Applicaton-toolkit.md) - * [OpenTracing Tracer](en/Opentracing.md) - * Logging + * [Use SkyWalking OpenTracing compatible tracer](en/Opentracing.md) + * Integration with log frameworks * [log4j](en/Application-toolkit-log4j-1.x.md) * [log4j2](en/Application-toolkit-log4j-2.x.md) * [logback](en/Application-toolkit-logback-1.x.md) - * [Trace](en/Application-toolkit-trace.md) - * [Propagate Context across Thread](en/Application-toolkit-trace-cross-thread.md) + * [Trace by SkyWalking manual APIs](en/Application-toolkit-trace.md) + * [Trace across threads](en/Application-toolkit-trace-cross-thread.md) * Testing * [Plugin Test](https://github.com/SkywalkingTest/agent-integration-test-report) * [Java Agent Performance Test](https://skywalkingtest.github.io/Agent-Benchmarks/) diff --git a/docs/README_ZH.md b/docs/README_ZH.md index fed7243d7..de07d8a8e 100644 --- a/docs/README_ZH.md +++ b/docs/README_ZH.md @@ -18,13 +18,13 @@ * [OpenTracing中文版](https://github.com/opentracing-contrib/opentracing-specification-zh) * Application Toolkit，应用程序工具包 * [概述](cn/Application-toolkit-CN.md) - * [OpenTracing Tracer](cn/Opentracing-CN.md) - * 日志组件 + * [使用SkyWalking的OpenTracing的兼容API](cn/Opentracing-CN.md) + * 日志组件集成 * [log4j组件](cn/Application-toolkit-log4j-1.x-CN.md) * [log4j2组件](cn/Application-toolkit-log4j-2.x-CN.md) * [logback组件](cn/Application-toolkit-logback-1.x-CN.md) - * [Trace](cn/Application-toolkit-trace-CN.md) - * [调用链跨线程传递](cn/Application-toolkit-trace-cross-thread-CN.md) + * [使用SkyWalking手动追踪API](cn/Application-toolkit-trace-CN.md) + * [跨线程任务追踪](cn/Application-toolkit-trace-cross-thread-CN.md) * 测试用例 * [插件测试](https://github.com/SkywalkingTest/agent-integration-test-report) * [Java 探针性能测试](https://skywalkingtest.github.io/Agent-Benchmarks/README_zh.html) diff --git a/docs/en/Deploy-backend-in-cluster-mode.md b/docs/en/Deploy-backend-in-cluster-mode.md index 1d537c4d4..d8745b16f 100644 --- a/docs/en/Deploy-backend-in-cluster-mode.md +++ b/docs/en/Deploy-backend-in-cluster-mode.md @@ -1,32 +1,53 @@ -## Required of third party softwares +## Requirements - JDK 6+（instruments application can run in jdk6） - JDK8 ( SkyWalking collector and SkyWalking WebUI ) - Elasticsearch 5.x, cluster mode or not - Zookeeper 3.4.10 +- OS time(include time zone) of Applications under monitoring, collectors, UIs and your local machine are all correct and same. ## Download released version - Go to [released page](http://skywalking.apache.org/downloads/) -## Deploy Elasticsearch server +## Deploy Zookeeper +Zookeeper is used for collector coordination. Only required if you need more than one collector instances. + +Add Zookeeper cluster info in each collector `application.yml` +```yml +cluster: +# The Zookeeper cluster for collector cluster management. + zookeeper: + # multiple instances should be separated by comma. + hostPort: localhost:2181 + sessionTimeout: 100000 +``` + +## Deploy ElasticSearch server +ElasticSearch is using for storage all traces, metrics and alarms. + - Modify `elasticsearch.yml` - Set `cluster.name: CollectorDBCluster` - Set `node.name: anyname`, this name can be any, it based on Elasticsearch. - - Add the following configurations to + - Add the following configurations ``` # The ip used for listening network.host: 0.0.0.0 thread_pool.bulk.queue_size: 1000 ``` +See ElasticSearch Official documents to understand how to deploy cluster(Recommend). - Start Elasticsearch -### Deploy collector servers -1. Run `tar -xvf skywalking-dist.tar.gz` -2. Config collector in cluster mode. +### Set collector +There are five types of connection for SkyWalking cluster, related to collector settings. +1. Agent to collectors by using HTTP, named as `naming`. +1. Agent to collectors by using gRPC, named as `agent_gRPC`. +1. Collector to collector by using gRPC, named as `remote`. +1. UI to collector by using HTTP, named as `ui`. Don't need to change in most cases. +1. Optional connection: Agent to collector by using HTTP, named as `agent_jetty`. -Cluster mode depends on Zookeeper register and application discovery capabilities. So, you just need to adjust the IP config items in `config/application.yml`. Change IP and port configs of naming, remote, agent_gRPC, agent_jetty and ui, -replace them to the real ip or hostname which you want to use for cluster. + +The following segment of `application.yml` shows you the detail of each settings. - `config/application.yml` ``` @@ -37,20 +58,26 @@ cluster: sessionTimeout: 100000 naming: # Host and port used for agent config -jetty: - host: localhost + jetty: + # OS real network IP(binding required), for agent to find collector cluster. agent --(HTTP)--> collector + host: localhost port: 10800 contextPath: / remote: gRPC: - host: localhost + # OS real network IP(binding required), for collector node to communicate with each other in cluster. collectorN --(gRPC) --> collectorM + host: localhost port: 11800 agent_gRPC: gRPC: + # OS real network IP(binding required), for agent to uplink data(trace/metrics) to collector. agent--(gRPC)--> collector host: localhost port: 11800 agent_jetty: jetty: + # OS real network IP(binding required), for agent to uplink data(trace/metrics) to collector through HTTP. agent--(HTTP)--> collector + # SkyWalking native Java/.Net/node.js agents don't use this. + # Open this for other implementor. host: localhost port: 12800 contextPath: / @@ -65,6 +92,7 @@ analysis_segment_parser: bufferSegmentMaxFileSize: 500M ui: jetty: + # OS real network IP(binding required), for UI to query from collector. host: localhost port: 12800 contextPath: / @@ -77,7 +105,7 @@ storage: indexShardsNumber: 2 indexReplicasNumber: 0 highPerformanceMode: true - # Set a timeout on metric data. After the timeout has expired, the metric data will automatically be deleted. + # Set an expired for metric/trace data. After the timeout has expired, the metric/trace data will be deleted automatically. traceDataTTL: 90 # Unit is minute minuteMetricDataTTL: 45 # Unit is minute hourMetricDataTTL: 36 # Unit is hour @@ -85,8 +113,9 @@ storage: monthMetricDataTTL: 18 # Unit is month configuration: default: -# namespace: xxxxx -# alarm threshold + # namespace: xxxxx + + # alarm threshold applicationApdexThreshold: 2000 serviceErrorRateThreshold: 10.00 serviceAverageResponseTimeThreshold: 2000 @@ -94,23 +123,25 @@ configuration: instanceAverageResponseTimeThreshold: 2000 applicationErrorRateThreshold: 10.00 applicationAverageResponseTimeThreshold: 2000 -# thermodynamic + + # thermodynamic thermodynamicResponseTimeStep: 50 thermodynamicCountOfResponseTimeSteps: 40 ``` -3. Run `bin/collectorService.sh` +### Set UI -### Deploy UI servers - -1. Run `tar -xvf skywalking-dist.tar.gz` -2. Config UI in cluster mode. - -The config items of UI is saved in `bin/webappService.sh` (`bin\webappService.bat` for windows). +The config items of UI is saved in `bin/webappService.sh` (`bin\webappService.bat` for windows). +Change `collector.ribbon.listOfServers` by following the description, with matching `naming.jetty`. | Config | Description | |----------------------------------|------------------------------------------------------------------------------------------------------| -| `server.port` | Port to listen on | +| `server.port` | Port to listen on. Default: 8080 | | `collector.ribbon.listOfServers` | Address to access collector naming service.(Consist with `naming.jetty` in `config/application.yml`). Multiple collector addresses are split by ',' | -3. Run `bin/webappService.sh` + +### Start up collector node +1. Run `bin/startup.sh` to start collector and UI together. +2. (Run if don't use 1 to start up)Run `bin/collectorService.sh` when you only want to start up collector. +3. (Run if don't use 1 to start up)Run `bin/webappService.sh` when you only want to start up UI. + diff --git a/docs/en/Deploy-backend-in-standalone-mode.md b/docs/en/Deploy-backend-in-standalone-mode.md index 5256f1cf2..98fe83193 100644 --- a/docs/en/Deploy-backend-in-standalone-mode.md +++ b/docs/en/Deploy-backend-in-standalone-mode.md @@ -3,10 +3,12 @@ Default standalone mode collector means don't support cluster. It uses H2 as sto If you are using SkyWalking in a low throughputs monitoring scenario, and don't want to deploy cluster, at least, switch the storage implementation from H2 to Elasticsearch. -**H2 storage implementation is not provided in 5.0.0-alpha, so you must deploy ElasticSearch before try to start backend** +**H2 storage implementation is not provided in 5.0.0 for now, so you must deploy ElasticSearch before try to start backend. Welcome to contribute.** ## Requirements -* JDK 8+ +- JDK 6+（instruments application can run in jdk6） +- JDK8 ( SkyWalking collector and SkyWalking WebUI ) +- Elasticsearch 5.x, cluster mode or not ## Download * [Releases](http://skywalking.apache.org/downloads/) @@ -14,12 +16,13 @@ If you are using SkyWalking in a low throughputs monitoring scenario, and don't ## Quick start You can simply tar/unzip and startup if ports 8080, 10800, 11800, 12800 are free. +- Deploy ElasticSearch. - `tar -xvf skywalking-dist.tar.gz` in Linux, or unzip in windows. - run `bin/startup.sh` or `bin/startup.bat` You should keep the `config/application.yml` as default. -- NOTICE: **In 5.0.0-alpha, startup.sh will start two processes, collector and UI, and UI uses 127.0.0.1:10800 as default.** +- NOTICE: **In 5.0.0, startup.sh will start two processes, collector and UI, and UI uses 127.0.0.1:10800 as default.** ## Use Elastic Search instead of H2 as storage layer implementation Even in standalone mode, collector can run with Elastic Search as storage. If so, uncomment the `storage` section in `application.yml`, set the config right. The default configs fit for collector and Elasticsearch both running in same machine, and not cluster. diff --git a/docs/en/Deploy-skywalking-agent.md b/docs/en/Deploy-skywalking-agent.md index 8ddcb5ae3..5554be41d 100644 --- a/docs/en/Deploy-skywalking-agent.md +++ b/docs/en/Deploy-skywalking-agent.md @@ -1,7 +1,7 @@ ## Download skywalking agent release version - Go to [release page](http://skywalking.apache.org/downloads/) -## Deploy skywalking javaagent +## Install skywalking javaagent 1. Copy the agent package to anywhere you like. The logs, plugins and config are all included in the package. 2. Add -javaagent:/path/to/skywalking-agent/skywalking-agent.jar to VM argument. @@ -23,13 +23,13 @@ New agent package looks like this： skywalking-agent.jar ``` -- Start your application。 +- Start your application. # Advanced features - All plugins are in `/plugins` folder. The plugin jar is active when it is in there. Remove the plugin jar, it disabled. - The default logging output folder is `/logs`. -# Deploy agent in Tomcat FAQ +# Install javaagent FAQs - Linux Tomcat 7, Tomcat 8 Change the first line of `tomcat/bin/catalina.sh`. ```shell diff --git a/docs/en/Quick-start.md b/docs/en/Quick-start.md index d903af2c7..e259d36b1 100644 --- a/docs/en/Quick-start.md +++ b/docs/en/Quick-start.md @@ -1,7 +1,12 @@ # Quick start -1. Download `apache-skywalking-apm-incubating-x.y.z.tar.gz` or `apache-skywalking-apm-incubating-x.y.z.zip` -1. Deploy Backend - - [Standalone Mode](Deploy-backend-in-standalone-mode.md) - - [Cluster Mode](Deploy-backend-in-cluster-mode.md) -1. Deploy Java Agent，[doc](Deploy-skywalking-agent.md) -1. Reboot your applications, and open UI. \ No newline at end of file +Quick start is for end users to start up the SkyWalking quickly in local. + +1. Download releases from Apache official website. [Link](http://skywalking.apache.org/downloads/) +1. Deploy backend on local. See [collector in standalone mode doc](Deploy-backend-in-standalone-mode.md) +1. Install Java Agent. [Doc](Deploy-skywalking-agent.md) +1. Set your OS time(include time zone) correct. +1. Reboot your applications, and open UI. + +If you want to deploy SkyWalking in server or cloud as a cluster, please following these two documents: +1. [Install javaagent](Deploy-skywalking-agent.md) +1. [Deploy backend in cluster mode](Deploy-backend-in-cluster-mode.md) \ No newline at end of file