Deploy document reformat (#1337)

* Refactor English documents to guide end users.
2018-06-11 16:23:35 +08:00 · 2018-06-11 16:23:35 +08:00 · 975c04007c
parent 1b83b34401
commit 975c04007c
7 changed files with 101 additions and 52 deletions
--- 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
--- 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/)
--- 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)
--- 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.
+
--- 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.
--- 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
--- 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.
+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)