Deploy document reformat (#1337)

* Refactor English documents to guide end users.

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
+    #namespace: xxxxx
-# alarm threshold
+    # 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

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)
+    * [Use SkyWalking OpenTracing compatible tracer](en/Opentracing.md)
-    * Logging
+    * 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)
+    * [Trace by SkyWalking manual APIs](en/Application-toolkit-trace.md)
-    * [Propagate Context across Thread](en/Application-toolkit-trace-cross-thread.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/)

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)
+    * [使用SkyWalking手动追踪API](cn/Application-toolkit-trace-CN.md)
-    * [调用链跨线程传递](cn/Application-toolkit-trace-cross-thread-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)

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
+### Set collector
-1. Run `tar -xvf skywalking-dist.tar.gz`
+There are five types of connection for SkyWalking cluster, related to collector settings.
-2. Config collector in cluster mode.
+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:
+  jetty:
-    host: localhost
+    # 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
+    # namespace: xxxxx
-# alarm threshold
+    
+    # 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
+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`. 
-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).
 
 | 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.
+

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.

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

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`
+Quick start is for end users to start up the SkyWalking quickly in local.
-1. Deploy Backend
+
-   - [Standalone Mode](Deploy-backend-in-standalone-mode.md)
+1. Download releases from Apache official website. [Link](http://skywalking.apache.org/downloads/)
-   - [Cluster Mode](Deploy-backend-in-cluster-mode.md)
+1. Deploy backend on local. See [collector in standalone mode doc](Deploy-backend-in-standalone-mode.md)
-1. Deploy Java Agent，[doc](Deploy-skywalking-agent.md)
+1. Install Java Agent. [Doc](Deploy-skywalking-agent.md)
-1. Reboot your applications, and open UI.
+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)