Merge pull request apache#712 from apache/adjust-document

Adjust document

docs/README.md

@@ -18,6 +18,8 @@
     * [Plugin Test](https://github.com/SkywalkingTest/agent-integration-test-report)
     * [Java Agent Performance Test](https://skywalkingtest.github.io/Agent-Benchmarks/)
   * Development Guides
-    * [Skywalking 3 Cross Process Propagation Headers Protocol, v1.0](en/Skywalking-3-Cross-Process-Propagation-Headers-Protocol.md)
+    * [How to build project](en/How-to-build.md)
+    * Protocol
+      * [Cross Process Propagation Headers Protocol, v1.0](en/Skywalking-Cross-Process-Propagation-Headers-Protocol-v1.md)
   * FAQ
 

docs/README_ZH.md

@@ -22,8 +22,9 @@
   * 开发指南
     * [工程编译指南](cn/How-to-build-CN.md)
     * [插件开发指南](cn/Plugin-Development-Guide-CN.md)
-    * [跨进程追踪上下文传递协议](cn/Skywalking-3-Cross-Process-Propagation-Headers-Protocol-CN.md)
-    * [探针与Collector间网络协议，v3.2+](cn/How-to-communicate-with-the-collector-CN.md)
+    * 交互协议
+        * [Cross Process Propagation Headers Protocol, v1.0 | 跨进程追踪上下文传递协议](cn/Skywalking-Cross-Process-Propagation-Headers-Protocol-CN-v1.md)
+        * [SkyWalking Trace Data Protocol 探针与Collector间网络协议](cn/Trace-Data-Protocol-CN.md)
   * FAQ
     * [Trace查询有数据，但是没有拓扑图和JVM数据?](cn/FAQ/Why-have-traces-no-others-CN.md)
     * [加载探针，Console被GRPC日志刷屏](cn/FAQ/Too-many-gRPC-logs-CN.md)

docs/cn/Application-toolkit-log4j-1.x-CN.md

@@ -6,7 +6,6 @@
       <version>{project.release.version}</version>
    </dependency>
 ```
-&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-log4j-1.x/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-log4j-1.x/_latestVersion)
 
 * 配置layout
 ```properties

docs/cn/Application-toolkit-log4j-2.x-CN.md

@@ -6,7 +6,6 @@
       <version>{project.release.version}</version>
    </dependency>
 ```
-&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-log4j-2.x/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-log4j-2.x/_latestVersion)
 
 * 在log4j2.xml中的pattern 配置节，配置`[%traceId]`
 ```xml

docs/cn/Application-toolkit-logback-1.x-CN.md

@@ -6,7 +6,6 @@
       <version>{project.release.version}</version>
    </dependency>
 ```
-&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-log4j-2.x/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-log4j-2.x/_latestVersion)
 
 * 在logback.xml中的`Pattern`配制节中，设置`%tid`
 ```xml

docs/cn/Application-toolkit-trace-CN.md

@@ -6,7 +6,6 @@
       <version>${skywalking.version}</version>
    </dependency>
 ```
-&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-trace/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-trace/_latestVersion)
 
 * 随时使用 `TraceContext.traceId()` API，在应用程序的任何地方获取traceId.
 ```java

docs/cn/How-to-build-CN.md

@@ -15,4 +15,3 @@
   - **apm-network/target/generated--sources/protobuf**目录下的`grpc-java`和`java`目录
   - **apm-collector/apm-collector-remote/apm-remote-grpc-provider/target/protobuf**目录下的`grpc-java`和`java`目录
 
-注：从3.2开始，网络通讯协议引入GRPC，所以增加上述的步骤

docs/cn/Plugin-Development-Guide-CN.md

@@ -4,7 +4,8 @@
 ### 核心概念
 #### 一. Span
 Span是追踪系统中的通用概念（有时候被翻译成埋点），关于Span的定义，请参考[OpenTracing 中文版](https://github.com/opentracing-contrib/opentracing-specification-zh/blob/master/specification.md#opentracing数据模型)。
-sky-walking作为OpenTracing的支持者，在核心实现中，与标准有较高的相似度。
+
+SkyWalking作为OpenTracing的支持者，在核心实现中，与标准有较高的相似度。当然，作为实际产品的需要，我们一会扩展相关概念。
 
 我们将span分为三类：
 
@@ -15,10 +16,10 @@ EntrySpan代表一个服务的提供方，即，服务端的入口点。它是
 LocalSpan代表一个普通的Span,代表任意一个本地逻辑块（或方法）
 
 1.3 ExitSpan
-ExitSpan也可以称为LeafSpan(sky-walking的早期版本中的称呼)，代表了一个远程服务的客户端调用。如：一次JDBC调用。
+ExitSpan也可以称为LeafSpan(SkyWalking的早期版本中的称呼)，代表了一个远程服务的客户端调用。如：一次JDBC调用。
 
 #### 二. ContextCarrier
-分布式追踪要解决的一个重要问题，就是跨进程的问题，ContextCarrier的概念就是为了解决这种场景。
+分布式追踪要解决的一个重要问题，就是跨进程调用链连接的问题，ContextCarrier的概念就是为了解决这种场景。
 
 当发生一次**A->B**的网络调用时：
 1. 需要在客户端生成(inject操作)ContextCarrier，并序列化成String
@@ -52,7 +53,8 @@ ExitSpan也可以称为LeafSpan(sky-walking的早期版本中的称呼)，代表
 ```
 
 #### 三. ContextSnapshot
-除了跨进程的RPC调用，另外一种追踪的常见场景是跨线程。跨线程和跨进程有很高的相似度，都是需要完成上下文的传递工作。所以ContextSnapshot具有和ContextCarrier十分类似的API风格。
+除了跨进程的RPC调用，另外一种追踪的常见场景是跨线程保持链路连接。跨线程和跨进程有很高的相似度，都是需要完成上下文的传递工作。
+所以ContextSnapshot具有和ContextCarrier十分类似的API风格。
 
 当发生一次**A->B**的跨线程调用时：
 1. 需要在A线程中通过ContextManager#capture操作生成ContextSnapshot对象实例
@@ -147,7 +149,7 @@ SpanLayer为我们的特有概念，如果是远程调用类的服务，请设
 
 ### 开发插件
 #### 一. 简介
-因为所有的程序调用都是基于方法的，所以插件实际上就是基于方法的拦截，类似面向切面编程的AOP技术。sky-walking底层已经完成相关的技术封装，所以插件开发者只需要定位需要拦截的类、方法，然后结合上文中的追踪API，即可完成插件的开发。
+因为所有的程序调用都是基于方法的，所以插件实际上就是基于方法的拦截，类似面向切面编程的AOP技术。SkyWalking底层已经完成相关的技术封装，所以插件开发者只需要定位需要拦截的类、方法，然后结合上文中的追踪API，即可完成插件的开发。
 
 #### 二. 拦截类型
 根据Java方法，共有三种拦截类型
@@ -267,10 +269,10 @@ public interface InstanceMethodsAroundInterceptor {
 
 大家需支持以下步骤执行：
 1. 在issue页面提出插件扩展需求，对应的版本。
-1. Fork wu-sheng/sky-walking到本地
+1. Fork apache/incubator-skywalking到本地
 1. 在apm-sniffer/apm-sdk-plugin下新建自己的插件模块，模块名为：支持类库名称+版本号
 1. 按照规范开发插件
 1. 完善注释和测试用例
 1. 在本地打包进行集成测试
-1. 提交Pull Request到 wu-sheng/sky-walking，提供插件追踪的截图（拓扑和Trace明细），可独立运行的被追踪程序、docker镜像或docker-compose。
-1. sky-walking PMC( Project Management Committee) 成员完成插件审核，确定发布版本，并合并到主仓库。
+1. 提交Pull Request到 apache/incubator-skywalking，根据评审团队要求，提供相关自动化测试用例
+1. SkyWalking Committer成员完成插件审核，确定发布版本，并合并到主仓库。

docs/cn/Skywalking-3-Cross-Process-Propagation-Headers-Protocol-CN.md → docs/cn/Skywalking-Cross-Process-Propagation-Headers-Protocol-CN-v1.md

@@ -1,13 +1,15 @@
-# Skywalking 3 Cross Process Propagation Headers Protocol
+# Skywalking Cross Process Propagation Headers Protocol
 * Version 1.0
 
-这是Skywalking3跨进程传输头协议第一个公开版本。Skywalking是一个偏向APM的分布式追踪系统，所以，为了提供服务端处理性能。头信息会比其他的追踪系统要更复杂一些。你会发现，这个头信息，更像一个商业APM系统，并且，一些商业APM系统的头信息，比我们的要复杂的多。所以，如果你希望开发或者贡献其他语言探针、或者JAVA探针的其他市县模式，请耐心阅读，并理解此协议内容。
-
+Skywalking是一个偏向APM的分布式追踪系统，所以，为了提供服务端处理性能。头信息会比其他的追踪系统要更复杂一些。
+你会发现，这个头信息，更像一个商业APM系统，并且，一些商业APM系统的头信息，比我们的要复杂的多。
 
 # Header Item
 * Header Name: `sw3`
 * Header Value: 使用`|`分隔，包含以下内容
 
+_消息头使用sw3，因为此协议始于SkyWalking 3.x版本。_
+
 ## Values
 * Trace Segment Id
 

docs/cn/How-to-communicate-with-the-collector-CN.md → docs/cn/Trace-Data-Protocol-CN.md

@@ -1,12 +1,11 @@
-# 探针与Collector间通讯协议
+# Trace Data Protocol 中文
+Trace Data Protocol协议，也就是探针与Collector间通讯协议
+
 ## 前言
-这篇文章主要介绍3.2版本的Collector对外提供的服务协议。一般情况下，使用者和开发者都无需了解此协议细节。但是在庞大的开源生态中，我们已经收到过多次有公司或个人的使用案例，使用自己的非Java探针（PHP,GO等）探针，接入我们的Collector进行数据分析和监控。
+此协议包含了Agent上行/下行数据的格式，可用于定制开发，或者探针的多语言扩展
 
 ## 协议类型
-Collector从3.2开始，对外同时提供gRPC和HTTP RESTFul两种类型的协议。从效率上，我们推荐使用gRPC
-
-# gRPC服务
-本章节，描述官方java探针使用的网络协议
+对外同时提供gRPC和HTTP RESTFul两种类型的协议。从效率上，我们推荐使用gRPC
 
 ## Collector服务发现协议
 ### 简介
@@ -17,7 +16,7 @@ HTTP GET
 
 ### 协议内容
 - 请求
-GET操作：http://collectorIp:port/agentstream/grpc 。 其中`/agentstream/grpc`是默认值，如需修改，需要参考collector相关配置。
+GET操作：http://collectorIp:port/agent/grpc 。 其中`/agent/grpc`是默认值，如需修改，需要参考collector相关配置。
 
 - 返回
 JSON数组，数组的每个元素，为一个有效的gRPC服务地址。
@@ -33,7 +32,7 @@ JSON数组，数组的每个元素，为一个有效的gRPC服务地址。
 gRPC服务
 
 ### 协议内容
-https://github.com/apache/incubator-skywalking/blob/master/apm-network/src/main/proto/ApplicationRegisterService.proto
+[gRPC service define](../..apm-protocol/apm-network/src/main/proto/ApplicationRegisterService.proto)
 ```proto
 syntax = "proto3";
 
@@ -44,22 +43,22 @@ import "KeyWithIntegerValue.proto";
 
 //register service for ApplicationCode, this service is called when service starts.
 service ApplicationRegisterService {
-    rpc register (Application) returns (ApplicationMapping) {
+    rpc batchRegister (Applications) returns (ApplicationMappings) {
     }
 }
 
-message Application {
-    repeated string applicationCode = 1;
+message Applications {
+    repeated string applicationCodes = 1;
 }
 
-message ApplicationMapping {
-    repeated KeyWithIntegerValue application = 1;
+message ApplicationMappings {
+    repeated KeyWithIntegerValue applications = 1;
 }
 ```
 - 首次调用时，applicationCode为客户端设置的应用名（显示在拓扑图和应用列表上的名字）。之后随着追踪过程，会上报此应用相关的周边服务的`ip:port`地址列表
 - KeyWithIntegerValue 返回，key为上报的applicationCode和ip:port地址，value为对应的id。applicationCode对应的返回id,在后续协议中，被称为applicationId。
 - 此服务按需调用，本地无法找到ip:port对应的id时，可异步发起调用。
-- 获取applicationId的操作是必选。
+- 获取applicationId的操作是必选。后续追踪数据依赖此id
 - 获取ip:port对应的id是可选，但是完成id设置，会有效提高collector处理效率，降低网络消耗。
 
 
@@ -71,7 +70,7 @@ message ApplicationMapping {
 gRPC服务
 
 ### 实例注册服务
-https://github.com/apache/incubator-skywalking/blob/master/apm-network/src/main/proto/DiscoveryService.proto#L11-L12
+[gRPC service define](../../apm-protocol/apm-network/src/main/proto/DiscoveryService.proto#L11-L12)
 ```proto
 service InstanceDiscoveryService {
     rpc register (ApplicationInstance) returns (ApplicationInstanceMapping) {
@@ -102,7 +101,7 @@ message ApplicationInstanceMapping {
 - 服务端返回应用实例id，applicationInstanceId 。后续上报服务使用实例id标识。
 
 ### 实例心跳服务
-https://github.com/apache/incubator-skywalking/blob/master/apm-network/src/main/proto/DiscoveryService.proto#L14-L15
+[gRPC service define](../../apm-protocol/apm-network/src/main/proto/DiscoveryService.proto#L14-L15)
 ```proto
 service InstanceDiscoveryService {
     rpc heartbeat (ApplicationInstanceHeartbeat) returns (Downstream) {
@@ -142,7 +141,7 @@ message ApplicationInstanceRecover {
 gRPC服务
 
 ### 协议内容
-https://github.com/apache/incubator-skywalking/blob/master/apm-network/src/main/proto/DiscoveryService.proto#L53-L74
+[gRPC service define](../../apm-protocol/apm-network/src/main/proto/DiscoveryService.proto#L53-L74)
 ```proto
 //discovery service for ServiceName by Network address or application code
 service ServiceNameDiscoveryService {
@@ -179,7 +178,7 @@ message ServiceNameElement {
 gRPC服务
 
 ### 协议内容
-https://github.com/apache/incubator-skywalking/blob/master/apm-network/src/main/proto/JVMMetricsService.proto
+[gRPC service define](../../apm-protocol/apm-network/src/main/proto/JVMMetricsService.proto)
 ```proto
 syntax = "proto3";
 
@@ -256,6 +255,7 @@ enum GCPhrase {
 gRPC服务
 
 ### 协议内容
+[gRPC service define](../../apm-protocol/apm-network/src/main/proto/TraceSegmentService.proto)
 ```proto
 syntax = "proto3";
 
@@ -281,10 +281,10 @@ message UniqueId {
 
 message TraceSegmentObject {
     UniqueId traceSegmentId = 1;
-    repeated TraceSegmentReference refs = 2;
-    repeated SpanObject spans = 3;
-    int32 applicationId = 4;
-    int32 applicationInstanceId = 5;
+    repeated SpanObject spans = 2;
+    int32 applicationId = 3;
+    int32 applicationInstanceId = 4;
+    bool isSizeLimited = 5;
 }
 
 message TraceSegmentReference {
@@ -294,28 +294,30 @@ message TraceSegmentReference {
     int32 parentApplicationInstanceId = 4;
     string networkAddress = 5;
     int32 networkAddressId = 6;
-    string entryServiceName = 7;
-    int32 entryServiceId = 8;
-    string parentServiceName = 9;
-    int32 parentServiceId = 10;
+    int32 entryApplicationInstanceId = 7;
+    string entryServiceName = 8;
+    int32 entryServiceId = 9;
+    string parentServiceName = 10;
+    int32 parentServiceId = 11;
 }
 
 message SpanObject {
     int32 spanId = 1;
     int32 parentSpanId = 2;
     int64 startTime = 3;
     int64 endTime = 4;
-    int32 operationNameId = 5;
-    string operationName = 6;
-    int32 peerId = 7;
-    string peer = 8;
-    SpanType spanType = 9;
-    SpanLayer spanLayer = 10;
-    int32 componentId = 11;
-    string component = 12;
-    bool isError = 13;
-    repeated KeyWithStringValue tags = 14;
-    repeated LogMessage logs = 15;
+    repeated TraceSegmentReference refs = 5;
+    int32 operationNameId = 6;
+    string operationName = 7;
+    int32 peerId = 8;
+    string peer = 9;
+    SpanType spanType = 10;
+    SpanLayer spanLayer = 11;
+    int32 componentId = 12;
+    string component = 13;
+    bool isError = 14;
+    repeated KeyWithStringValue tags = 15;
+    repeated LogMessage logs = 16;
 }
 
 enum RefType {
@@ -330,10 +332,12 @@ enum SpanType {
 }
 
 enum SpanLayer {
-    Database = 0;
-    RPCFramework = 1;
-    Http = 2;
-    MQ = 3;
+    Unknown = 0;
+    Database = 1;
+    RPCFramework = 2;
+    Http = 3;
+    MQ = 4;
+    Cache = 5;
 }
 
 message LogMessage {
@@ -342,11 +346,11 @@ message LogMessage {
 }
 ```
 - UniqueId为segment或者globalTraceId的数字表示。由3个long组成，1）applicationInstanceId，2）当前线程id，3）当前时间戳*10000 + seq(0-10000自循环)
-- Span的数据，请参考[插件开发规范](https://github.com/apache/incubator-skywalking/wiki/Plugin-Development-Guide)
+- Span的数据，请参考[插件开发规范](Plugin-Development-Guide-CN.md)
 - 以下id和名称根据注册返回结果，优先上报id，无法获取id时，再上传name。参考之前的应用和服务注册章节。
   - operationNameId/operationName 
   - networkAddress/networkAddressId
   - entryServiceName/entryServiceId
   - parentServiceName/parentServiceId
   - peerId/peer
-- componentId为默认支持的插件id，非官方支持，需传输名称或修改服务端源代码。[官方组件列表](../../apm-network/src/main/java/org/apache/skywalking/apm/network/trace/component/ComponentsDefine.java)
+- componentId为默认支持的插件id，非官方支持，需传输名称或修改服务端源代码。[官方组件列表](../../apm-protocol/apm-network/src/main/java/org/apache/skywalking/apm/network/trace/component/ComponentsDefine.java)

docs/en/Application-toolkit-log4j-1.x.md

@@ -6,7 +6,6 @@
       <version>{project.release.version}</version>
    </dependency>
 ```
-&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-log4j-1.x/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.apache.skywalking.apmg-toolkit-log4j-1.x/_latestVersion)
 
 * Config a layout
 ```properties

docs/en/Application-toolkit-log4j-2.x.md

@@ -6,7 +6,6 @@
       <version>{project.release.version}</version>
    </dependency>
 ```
-&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-log4j-2.x/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-log4j-2.x/_latestVersion)
 
 * Config the `[%traceId]` pattern in your log4j2.xml
 ```xml

docs/en/Application-toolkit-logback-1.x.md

@@ -6,7 +6,6 @@
       <version>{project.release.version}</version>
    </dependency>
 ```
-&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-logback-1.x/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-logback-1.x/_latestVersion)
 
 * set `%tid` in `Pattern` section of logback.xml
 ```xml

docs/en/Application-toolkit-trace.md

@@ -6,7 +6,6 @@
       <version>${skywalking.version}</version>
    </dependency>
 ```
-&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-trace/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.apache.skywalking.apm-toolkit-trace/_latestVersion)
 
 * Use `TraceContext.traceId()` API to obtain traceId.
 ```java

docs/en/Deploy-skywalking-agent.md

@@ -1,5 +1,5 @@
 ## Download skywalking agent release version
-- Go to [release page](https://github.com/wu-sheng/sky-walking/releases)
+- Go to [release page](https://github.com/apache/incubator-skywalking/releases)
 
 ## Deploy skywalking javaagent
 1. Copy the agent package to anywhere you like. The logs, plugins and config are all included in the package.
@@ -42,5 +42,5 @@ CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/skywalking-agent/skywalking-ag
 - Tomcat 8
 Change the first line of `tomcat/bin/catalina.sh`.
 ```shell
-set "CATALINA_OPTS=... -javaagent:E:\apache-tomcat-8.5.20\skywalking-agent\skywalking-agent.jar -Dconfig=\skywalking\config\dir"
+set "CATALINA_OPTS=-javaagent:E:\apache-tomcat-8.5.20\skywalking-agent\skywalking-agent.jar -Dconfig=\skywalking\config\dir"
 ```

docs/en/How-to-build.md

@@ -0,0 +1,14 @@
+# How to build project
+This document helps people to compile and build the project in your maven and IDE.
+
+## Build in maven
+1. Prepare JDK8 and maven3
+1. Run `mvn clean package`
+1. All packages are in `/packages`, which includes `skywalking-agent` folder, and two collector files(.tar.gz for Linux and .zip for Windows)
+
+## Setup your IntelliJ IDEA
+1. Import the project as a maven project
+1. Run `mvn compile -Dmaven.test.skip=true` to compile project and generate source codes. Because we use gRPC and protobuf.
+1. Set **Generated Source Codes** folders.
+    * `grpc-java` and `java` folders in **apm-network/target/generated--sources/protobuf**
+    * `grpc-java` and `java` folders in **apm-collector/apm-collector-remote/apm-remote-grpc-provider/target/protobuf**