Adjust many documents.

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/How-to-communicate-with-the-collector-CN.md → docs/cn/Trace-Data-Protocol-CN.md

-# 探针与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,10 +294,11 @@ 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 {
@@ -305,17 +306,18 @@ message SpanObject {
     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

 ## 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"
 ```
\ No newline at end of file

docs/en/How-to-build.md

+# 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**
\ No newline at end of file

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

-# Skywalking 3 Cross Process Propagation Headers Protocol
+# Skywalking Cross Process Propagation Headers Protocol
 * Version 1.0
 
-This is the first open edition about `Skywalking 3 Cross Process Propagation Headers Protocol`. The skywalking is more likely an APM system, rather than normal distributed tracing system. The Headers is much more complex than them in order to improving analysis performance of collector. You can find many similar mechanism in other commercial APM system.(Some even much more complex than us)
+SkyWalking is more likely an APM system, rather than common distributed tracing system. 
+The Headers is much more complex than them in order to improving analysis performance of collector. 
+You can find many similar mechanism in other commercial APM system.(Some even much more complex than us)
 
 # Header Item
 * Header Name: `sw3`
 * Header Value: Split by `|`, the parts are following.
 
+_The header protocol comes from SkyWalking 3, back to 2017. So sw3 header name keeps now._ 
+
 ## Values
 * Trace Segment Id
 

travis/push_image.sh

-#!/bin/sh
-
-check_pull_is_tagged() {
-  if [ "${TRAVIS_TAG}" == "" ]; then
-    return 1
-  else
-    echo "This build was started by the tag ${TRAVIS_TAG}, push image"
-    return 0
-  fi
-}
-
-check_release_tag() {
-    tag="${TRAVIS_TAG}"
-    if [[ "$tag" =~ ^v[0-9.]*-[0-9]{4}$ ]]; then
-	    return 0;
-	else
-	    echo "The provided tag ${tag} doesn't match that."
-	    return 1;
-    fi
-}
-
-push_image() {
-  IMAGE_VERSION=`echo ${TRAVIS_TAG:1}`
-  docker login -u="$DOCKER_USERNAME" -p="$DOCKER_PASSWORD"
-  mvn clean package docker:build
-  docker push skywalking/skywalking-collector:latest
-  docker push skywalking/skywalking-collector:${IMAGE_VERSION}
-}
-
-
-if check_pull_is_tagged && check_release_tag; then
-    push_image
-    echo "Push is Done!"
-fi
\ No newline at end of file