Finish cn documents

d6a6fe10 · wu-sheng · b7293702 · d6a6fe10 · d6a6fe10 · d6a6fe10
13 changed file
--- a/docs/README_ZH.md
+++ b/docs/README_ZH.md
@@ -2,7 +2,7 @@
 [![EN doc](https://img.shields.io/badge/document-English-blue.svg)](README.md)

  * [项目简介](/README_ZH.md)
-  * [快速入门](cn/Quick-start-chn.md)
+  * [快速入门](cn/Quick-start-CN.md)
    * [部署单机collector](cn/Deploy-collector-in-standalone-mode-CN.md)
    * [部署集群collector](cn/Deploy-collector-in-cluster-mode-CN.md)
    * [部署探针Agent](cn/Deploy-skywalking-agent-CN.md)
@@ -12,24 +12,22 @@
  * APM相关介绍资料
    * [APM简介（百度百科）](http://baike.baidu.com/link?url=HizLjnUrwvXqPQ4fZH_MA81MA7R_sE-kpdEIfuUHf-yNHhPiEkA97_7FshVR6raiZL6pvbChTZSIgrC1lY6lhq.md)
    * [OpenTracing中文版](https://github.com/opentracing-contrib/opentracing-specification-zh.md)
-    * [JVM内存管理与GC](cn/Memory-Usage-and-GC-info.md)
  * Application Toolkit，应用程序工具包
-    * [概述](cn/sky-walking-application-toolkit-chn.md)
-    * [OpenTracing Tracer](cn/skywalking-opentracing-chn.md)
+    * [概述](cn/Application-toolkit-CN.md)
+    * [OpenTracing Tracer](cn/skywalking-opentracing-CN.md)
    * 日志组件
-      * [log4j组件](cn/sky-walking-application-toolkit-log4j-1.x-chn.md)
-      * [log4j2组件](cn/sky-walking-application-toolkit-log4j-2.x-chn.md)
-      * [logback组件](cn/sky-walking-application-toolkit-logback-1.x-chn.md)
-    * [Trace](cn/sky-walking-application-toolkit-trace-chn.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/Test-Cases-chn.md)
-    * [测试应用集群](cn/2.0-Demo-Application-Cluster-chn.md)
+    * [插件测试](https://github.com/SkywalkingTest/agent-integration-test-report)
+    * [Java 探针性能测试](https://skywalkingtest.github.io/Agent-Benchmarks/)
  * 开发指南
-    * [工程编译指南](cn/How-to-build.md)
-    * [插件开发指南](cn/Plugin-Development-Guide.md)
+    * [工程编译指南](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%3F.md)
+    * [探针与Collector间网络协议，v3.2+](cn/How-to-communicate-with-the-collector-CN.md)
  * FAQ
-    * [探针性能测试报告](https://skywalkingtest.github.io/Agent-Benchmarks/.md)
-    * [Trace查询有数据，但是没有拓扑图和JVM数据?](cn/Trace%E6%9F%A5%E8%AF%A2%E6%9C%89%E6%95%B0%E6%8D%AE%EF%BC%8C%E4%BD%86%E6%98%AF%E6%B2%A1%E6%9C%89%E6%8B%93%E6%89%91%E5%9B%BE%E5%92%8CJVM%E6%95%B0%E6%8D%AE.md)
-    * [加载探针，Console被GRPC日志刷屏](cn/加载探针，Console被GRPC日志刷屏.md)
\ No newline at end of file
+    * [Trace查询有数据，但是没有拓扑图和JVM数据?](cn/FAQ/Why-have-traces-no-others-CN.md)
+    * [加载探针，Console被GRPC日志刷屏](cn/FAQ/Too-many-gRPC-logs-CN.md)
\ No newline at end of file
--- a/docs/cn/Application-toolkit-CN.md
+++ b/docs/cn/Application-toolkit-CN.md
+# 什么是sky-walking应用程序工具包?
+Sky-walking应用程序工具包是一系列的类库，有skywalking团队提供。通过这些类库，你可以在你的应用程序内，访问sky-walking的一些内部信息.
+
+_**最为重要的是**_, 即使你移除skywalking的探针，或者不激活探针，这些类库也不会对应用程序有任何影响，也不会影响性能.
+
+工具包提供以下核心能力
+1. 将追踪信息和log组件集成，如log4j, log4j2 和 logback
+1. 兼容CNCF OpenTracing标准的手动埋点
+1. 使用Skywalking专有的标注和交互性API
+
+_**注意**: 所有的应用程序工具包都托管在bitray.com/jcenter. 同时请确保你使用的开发工具包和skywalking的agent探针版本一致._
\ No newline at end of file
--- a/docs/cn/Application-toolkit-log4j-1.x-CN.md
+++ b/docs/cn/Application-toolkit-log4j-1.x-CN.md
+* 使用 maven 和 gradle 依赖相应的工具包
+```xml
+   <dependency>
+      <groupId>org.skywalking</groupId>
+      <artifactId>apm-toolkit-log4j-1.x</artifactId>
+      <version>{project.release.version}</version>
+   </dependency>
+```
+&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.skywalking.apm-toolkit-log4j-1.x/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.skywalking.apm-toolkit-log4j-1.x/_latestVersion)
+
+* 配置layout
+```properties
+log4j.appender.CONSOLE.layout=org.skywalking.apm.toolkit.log.log4j.v1.x.TraceIdPatternLayout
+```
+
+* 在`layout.ConversionPattern`中设置 `%T`来展示traceid ( 在 2.0-2016版本中, 你应该设置为 %x, [为什么改变配置，请参考相关issue?](https://github.com/wu-sheng/sky-walking/issues/77) )
+```properties
+log4j.appender.CONSOLE.layout.ConversionPattern=%d [%T] %-5p %c{1}:%L - %m%n
+```
+
+* 当你使用`-javaagent`参数激活sky-walking的探针, 如果当前上下文中存在traceid，log4j将在输出**traceId**。如果探针没有被激活，将输出`TID: N/A`.
\ No newline at end of file
--- a/docs/cn/Application-toolkit-log4j-2.x-CN.md
+++ b/docs/cn/Application-toolkit-log4j-2.x-CN.md
+* 使用 maven 和 gradle 依赖相应的工具包
+```xml
+   <dependency>
+      <groupId>org.skywalking</groupId>
+      <artifactId>apm-toolkit-log4j-2.x</artifactId>
+      <version>{project.release.version}</version>
+   </dependency>
+```
+&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.skywalking.apm-toolkit-log4j-2.x/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.skywalking.apm-toolkit-log4j-2.x/_latestVersion)
+
+* 在log4j2.xml中的pattern 配置节，配置`[%traceId]`
+```xml
+   <Appenders>
+      <Console name="Console" target="SYSTEM_OUT">
+         <PatternLayout pattern="%d [%traceId] %-5p %c{1}:%L - %m%n"/>
+      </Console>
+   </Appenders>
+```
+* 当你使用`-javaagent`参数激活sky-walking的探针, 如果当前上下文中存在traceid，log4j2将在输出**traceId**。如果探针没有被激活，将输出`TID: N/A`.
\ No newline at end of file
--- a/docs/cn/Application-toolkit-logback-1.x-CN.md
+++ b/docs/cn/Application-toolkit-logback-1.x-CN.md
+* 使用 maven 和 gradle 依赖相应的工具包
+```xml
+   <dependency>
+      <groupId>org.skywalking</groupId>
+      <artifactId>apm-toolkit-logback-1.x</artifactId>
+      <version>{project.release.version}</version>
+   </dependency>
+```
+&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.skywalking.apm-toolkit-log4j-2.x/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.skywalking.apm-toolkit-log4j-2.x/_latestVersion)
+
+* 在logback.xml中的`Pattern`配制节中，设置`%tid`
+```xml
+    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
+            <layout class="org.skywalking.apm.toolkit.log.logback.v1.x.TraceIdPatternLogbackLayout">
+                <Pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%tid] [%thread] %-5level %logger{36} -%msg%n</Pattern>
+            </layout>
+        </encoder>
+    </appender>
+```
+
+* 当你使用`-javaagent`参数激活sky-walking的探针, 如果当前上下文中存在traceid，logback将在输出**traceId**。如果探针没有被激活，将输出`TID: N/A`.
\ No newline at end of file
--- a/docs/cn/Application-toolkit-trace-CN.md
+++ b/docs/cn/Application-toolkit-trace-CN.md
+* 使用 maven 和 gradle 依赖相应的工具包
+```xml
+   <dependency>
+      <groupId>org.skywalking</groupId>
+      <artifactId>apm-toolkit-trace</artifactId>
+      <version>${skywalking.version}</version>
+   </dependency>
+```
+&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.skywalking.apm-toolkit-trace/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.skywalking.apm-toolkit-trace/_latestVersion)
+
+* 随时使用 `TraceContext.traceId()` API，在应用程序的任何地方获取traceId.
+```java
+import org.skywalking.apm.toolkit.trace.TraceContext;
+...
+
+modelAndView.addObject("traceId", TraceContext.traceId());
+```
+_示例代码，仅供参考_
+
+* 对任何需要追踪的方法，使用@Trace标注，则此方法会被加入到追踪链中。
\ No newline at end of file
--- a/docs/cn/FAQ/Too-many-gRPC-logs-CN.md
+++ b/docs/cn/FAQ/Too-many-gRPC-logs-CN.md
+**现象**：
+1. 加载探针并启动应用
+2. Console中被GRPC日志刷屏
+
+**原因**：Skywalking采用了GRPC框架发送数据，GRPC框架读取log的配置文件进行日志输出。
+
+**解决方法**: 在log的配置文件中添加对`org.skywalking.apm.dependencies`包的过滤
--- a/docs/cn/FAQ/Why-have-traces-no-others-CN.md
+++ b/docs/cn/FAQ/Why-have-traces-no-others-CN.md
+现象：
+- Agent和Collector正常工作，没有异常日志
+- 已经对系统进行过访问，Trace查询有数据
+- UI除Trace查询页面外，其他页面无数据
+- **页面顶部时间轴和当前系统时间不一致**
+
+原因：
+被监控系统所在的操作系统，未设置为当前时区，导致统计数据汇集时间点偏差。
+
+解决方法：
+设置操作系统时间时区
\ No newline at end of file
--- a/docs/cn/How-to-build-CN.md
+++ b/docs/cn/How-to-build-CN.md
+## 工程编译指南
+本文档用于指导开发者，在本地开发环境中编译工程。
+
+### 前言
+因为工程结构和代码依赖会随版本变化，如果读者熟悉travis-ci,则可直接参考[.travis.yml](https://github.com/wu-sheng/sky-walking/blob/master/.travis.yml)
+
+### 编译步骤
+1. 准备环境，jdk8，Maven
+1. 执行`mvn clean package`
+
+### 在IntelliJ IDEA中编译工程
+上述步骤在命令行中，能够很好的编译工程，但导入到编译器中的工程依然会有一些报错，我们需要进行几步简单的操作。
+1. 在IntelliJ Terminal中，执行`mvn compile -Dmaven.test.skip=true`进行编译
+1. 设置gRPC的自动生成代码目录，为源码目录
+  - **apm-network/target/generated--sources/protobuf**目录下的`grpc-java`和`java`目录
+  - **apm-collector/apm-collector-stream/target/protobuf**目录下的`grpc-java`和`java`目录
+
+注：从3.2开始，网络通讯协议引入GRPC，所以增加上述的步骤
--- a/docs/cn/How-to-communicate-with-the-collector-CN.md
+++ b/docs/cn/How-to-communicate-with-the-collector-CN.md
+# 探针与Collector间通讯协议
+## 前言
+这篇文章主要介绍3.2版本的Collector对外提供的服务协议。一般情况下，使用者和开发者都无需了解此协议细节。但是在庞大的开源生态中，我们已经收到过多次有公司或个人的使用案例，使用自己的非Java探针（PHP,GO等）探针，接入我们的Collector进行数据分析和监控。
+
+## 协议类型
+Collector从3.2开始，对外同时提供gRPC和HTTP RESTFul两种类型的协议。从效率上，我们推荐使用gRPC
+
+# gRPC服务
+本章节，描述官方java探针使用的网络协议
+
+## Collector服务发现协议
+### 简介
+**Collector服务发现协议是探针启动时，第一个调用的服务。**通过服务，查找对应的gRPC服务地址与端口列表，并在由客户端选择其中任意一个作为服务端。此服务需周期性调用，确保探针本地的服务端口列表是准确有效的。
+
+### 协议类型
+HTTP GET
+
+### 协议内容
+- 请求
+GET操作：http://collectorIp:port/agentstream/grpc 。 其中`/agentstream/grpc`是默认值，如需修改，需要参考collector相关配置。
+
+- 返回
+JSON数组，数组的每个元素，为一个有效的gRPC服务地址。
+```json
+["ip address1:port1","ip address2:port2","ip address3:port3"]
+```
+
+## 应用注册服务
+### 简介
+应用注册服务，是将手动设计的applicationCode，以及ip:port沟通的服务地址，转换成数字的服务。此服务会在后续的传输过程中，有效降低网络带宽需求。
+
+### 协议类型
+gRPC服务
+
+### 协议内容
+https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/proto/ApplicationRegisterService.proto
+```proto
+syntax = "proto3";
+
+option java_multiple_files = true;
+option java_package = "org.skywalking.apm.network.proto";
+
+import "KeyWithIntegerValue.proto";
+
+//register service for ApplicationCode, this service is called when service starts.
+service ApplicationRegisterService {
+    rpc register (Application) returns (ApplicationMapping) {
+    }
+}
+
+message Application {
+    repeated string applicationCode = 1;
+}
+
+message ApplicationMapping {
+    repeated KeyWithIntegerValue application = 1;
+}
+```
+- 首次调用时，applicationCode为客户端设置的应用名（显示在拓扑图和应用列表上的名字）。之后随着追踪过程，会上报此应用相关的周边服务的`ip:port`地址列表
+- KeyWithIntegerValue 返回，key为上报的applicationCode和ip:port地址，value为对应的id。applicationCode对应的返回id,在后续协议中，被称为applicationId。
+- 此服务按需调用，本地无法找到ip:port对应的id时，可异步发起调用。
+- 获取applicationId的操作是必选。
+- 获取ip:port对应的id是可选，但是完成id设置，会有效提高collector处理效率，降低网络消耗。
+
+
+## 应用实例发现服务
+### 简介
+应用实例发现服务存在三个子服务，分别是实例注册服务，实例心跳服务，实例注册重连服务。这三个服务负责获取和保持应用实例在线的功能。
+
+### 协议类型
+gRPC服务
+
+### 实例注册服务
+https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/proto/DiscoveryService.proto#L11-L12
+```proto
+service InstanceDiscoveryService {
+    rpc register (ApplicationInstance) returns (ApplicationInstanceMapping) {
+    }
+}
+
+message ApplicationInstance {
+    int32 applicationId = 1;
+    string agentUUID = 2;
+    int64 registerTime = 3;
+    OSInfo osinfo = 4;
+}
+
+message OSInfo {
+    string osName = 1;
+    string hostname = 2;
+    int32 processNo = 3;
+    repeated string ipv4s = 4;
+}
+
+message ApplicationInstanceMapping {
+    int32 applicationId = 1;
+    int32 applicationInstanceId = 2;
+}
+```
+- agentUUID 由探针生成，需保持唯一性，推荐使用UUID算法。并在应用重启前保持不变
+- applicationId 由**应用注册服务**获取。
+- 服务端返回应用实例id，applicationInstanceId 。后续上报服务使用实例id标识。
+
+### 实例心跳服务
+https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/proto/DiscoveryService.proto#L14-L15
+```proto
+service InstanceDiscoveryService {
+    rpc heartbeat (ApplicationInstanceHeartbeat) returns (Downstream) {
+    }
+}
+
+message ApplicationInstanceHeartbeat {
+    int32 applicationInstanceId = 1;
+    int64 heartbeatTime = 2;
+}
+```
+- 心跳服务每分钟上报一次。
+- 如一分钟内有segment数据上报，则可不必上报心跳。
+
+### 实例注册重连服务
+https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/proto/DiscoveryService.proto#L17-L18
+```proto
+service InstanceDiscoveryService {
+    rpc registerRecover (ApplicationInstanceRecover) returns (Downstream) {
+    }
+}
+
+message ApplicationInstanceRecover {
+    int32 applicationId = 1;
+    int32 applicationInstanceId = 2;
+    int64 registerTime = 3;
+    OSInfo osinfo = 4;
+}
+```
+- 应用重连服务于**应用注册服务**类似，在gRPC发生重连，并再次连接成功后发送。需包含通过**应用注册服务**获取的applicationInstanceId。
+
+## 服务名注册发现服务
+### 简介
+服务名注册发现服务，是将应用内的服务名（operationName）替换为id的服务。
+
+### 协议类型
+gRPC服务
+
+### 协议内容
+https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/proto/DiscoveryService.proto#L53-L74
+```proto
+//discovery service for ServiceName by Network address or application code
+service ServiceNameDiscoveryService {
+    rpc discovery (ServiceNameCollection) returns (ServiceNameMappingCollection) {
+    }
+}
+
+message ServiceNameCollection {
+    repeated ServiceNameElement elements = 1;
+}
+
+message ServiceNameMappingCollection {
+    repeated ServiceNameMappingElement elements = 1;
+}
+
+message ServiceNameMappingElement {
+    int32 serviceId = 1;
+    ServiceNameElement element = 2;
+}
+
+message ServiceNameElement {
+    string serviceName = 1;
+    int32 applicationId = 2;
+}
+```
+- 可选服务，可有效降低网络消耗，推荐实现。注意，由于部分应用存在URI中夹带参数的情况，请注意限制探针内的缓存容量，防止内存溢出。
+- ServiceNameElement中，applicationId为当前applicationCode对应的id。serviceName一般为对应span的operationName
+
+## JVM指标上报服务
+### 简介
+上报当前实例的JVM信息，每秒上报一次。
+
+### 协议类型
+gRPC服务
+
+### 协议内容
+https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/proto/JVMMetricsService.proto
+```proto
+syntax = "proto3";
+
+option java_multiple_files = true;
+option java_package = "org.skywalking.apm.network.proto";
+
+import "Downstream.proto";
+
+service JVMMetricsService {
+    rpc collect (JVMMetrics) returns (Downstream) {
+    }
+}
+
+message JVMMetrics {
+    repeated JVMMetric metrics = 1;
+    int64 applicationInstanceId = 2;
+}
+
+message JVMMetric {
+    int64 time = 1;
+    CPU cpu = 2;
+    repeated Memory memory = 3;
+    repeated MemoryPool memoryPool = 4;
+    repeated GC gc = 5;
+}
+
+message CPU {
+    double usagePercent = 2;
+}
+
+message Memory {
+    bool isHeap = 1;
+    int64 init = 2;
+    int64 max = 3;
+    int64 used = 4;
+    int64 committed = 5;
+}
+
+message MemoryPool {
+    PoolType type = 1;
+    bool isHeap = 2;
+    int64 init = 3;
+    int64 max = 4;
+    int64 used = 5;
+    int64 commited = 6;
+}
+
+enum PoolType {
+    CODE_CACHE_USAGE = 0;
+    NEWGEN_USAGE = 1;
+    OLDGEN_USAGE = 2;
+    SURVIVOR_USAGE = 3;
+    PERMGEN_USAGE = 4;
+    METASPACE_USAGE = 5;
+}
+
+message GC {
+    GCPhrase phrase = 1;
+    int64 count = 2;
+    int64 time = 3;
+}
+
+enum GCPhrase {
+    NEW = 0;
+    OLD = 1;
+}
+```
+
+## TraceSegment上报服务
+### 简介
+上报调用链信息
+
+### 协议类型
+gRPC服务
+
+### 协议内容
+```proto
+syntax = "proto3";
+
+option java_multiple_files = true;
+option java_package = "org.skywalking.apm.network.proto";
+
+import "Downstream.proto";
+import "KeyWithStringValue.proto";
+
+service TraceSegmentService {
+    rpc collect (stream UpstreamSegment) returns (Downstream) {
+    }
+}
+
+message UpstreamSegment {
+    repeated UniqueId globalTraceIds = 1;
+    bytes segment = 2; // the byte array of TraceSegmentObject
+}
+
+message UniqueId {
+    repeated int64 idParts = 1;
+}
+
+message TraceSegmentObject {
+    UniqueId traceSegmentId = 1;
+    repeated TraceSegmentReference refs = 2;
+    repeated SpanObject spans = 3;
+    int32 applicationId = 4;
+    int32 applicationInstanceId = 5;
+}
+
+message TraceSegmentReference {
+    RefType refType = 1;
+    UniqueId parentTraceSegmentId = 2;
+    int32 parentSpanId = 3;
+    int32 parentApplicationInstanceId = 4;
+    string networkAddress = 5;
+    int32 networkAddressId = 6;
+    string entryServiceName = 7;
+    int32 entryServiceId = 8;
+    string parentServiceName = 9;
+    int32 parentServiceId = 10;
+}
+
+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;
+}
+
+enum RefType {
+    CrossProcess = 0;
+    CrossThread = 1;
+}
+
+enum SpanType {
+    Entry = 0;
+    Exit = 1;
+    Local = 2;
+}
+
+enum SpanLayer {
+    Database = 0;
+    RPCFramework = 1;
+    Http = 2;
+    MQ = 3;
+}
+
+message LogMessage {
+    int64 time = 1;
+    repeated KeyWithStringValue data = 2;
+}
+```
+- UniqueId为segment或者globalTraceId的数字表示。由3个long组成，1）applicationInstanceId，2）当前线程id，3）当前时间戳*10000 + seq(0-10000自循环)
+- Span的数据，请参考[插件开发规范](https://github.com/OpenSkywalking/skywalking/wiki/Plugin-Development-Guide)
+- 以下id和名称根据注册返回结果，优先上报id，无法获取id时，再上传name。参考之前的应用和服务注册章节。
+  - operationNameId/operationName 
+  - networkAddress/networkAddressId
+  - entryServiceName/entryServiceId
+  - parentServiceName/parentServiceId
+  - peerId/peer
+- componentId为默认支持的插件id，非官方支持，需传输名称或修改服务端源代码。[官方组件列表](https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/java/org/skywalking/apm/network/trace/component/ComponentsDefine.java)
--- a/docs/cn/Plugin-Development-Guide-CN.md
+++ b/docs/cn/Plugin-Development-Guide-CN.md
+## 插件开发指南
+本文档描述 [v3.2+](https://github.com/OpenTracing/skywalking/releases) 插件开发方法、使用的API，以及注意事项。3.2版本将在2017 CNUTCon之前发布。
+
+### 核心概念
+#### 一. Span
+Span是追踪系统中的通用概念（有时候被翻译成埋点），关于Span的定义，请参考[OpenTracing 中文版](https://github.com/opentracing-contrib/opentracing-specification-zh/blob/master/specification.md#opentracing数据模型)。
+sky-walking作为OpenTracing的支持者，在核心实现中，与标准有较高的相似度。
+
+我们将span分为三类：
+
+1.1 EntrySpan
+EntrySpan代表一个服务的提供方，即，服务端的入口点。它是每个Java对外服务的入口点。如：Web服务入口就是一个EntrySpan。
+
+1.2 LocalSpan
+LocalSpan代表一个普通的Span,代表任意一个本地逻辑块（或方法）
+
+1.3 ExitSpan
+ExitSpan也可以称为LeafSpan(sky-walking的早期版本中的称呼)，代表了一个远程服务的客户端调用。如：一次JDBC调用。
+
+#### 二. ContextCarrier
+分布式追踪要解决的一个重要问题，就是跨进程的问题，ContextCarrier的概念就是为了解决这种场景。
+
+当发生一次**A->B**的网络调用时：
+1. 需要在客户端生成(inject操作)ContextCarrier，并序列化成String
+1. 将这个String加入RPC调用的正文（或HEAD）中，传递到服务端
+1. 服务端收到后，转换为新的ContextCarrier
+1. 通过提取操作（extract操作）建立关联
+
+以HTTPComponent调用Tomcat为例：
+1. 客户端（HTTPComponent端）
+```java
+            span = ContextManager.createExitSpan("/span/operation/name", contextCarrier, "ip:port");
+            CarrierItem next = contextCarrier.items();
+            while (next.hasNext()) {
+                next = next.next();
+                //向HTTP或者其他RPC HEAD中设置上下文
+                heads.put(next.getHeadKey(), next.getHeadValue());
+            }
+```
+
+2. 服务端（Tomcat端）
+```java
+            ContextCarrier contextCarrier = new ContextCarrier();
+            CarrierItem next = contextCarrier.items();
+            while (next.hasNext()) {
+                next = next.next();
+                //从HTTP或者其他RPC HEAD中，根据指定的KEY，提取上下文
+                next.setHeadValue(heads.get(next.getHeadKey()));
+            }
+
+            span = ContextManager.createEntrySpan(“/span/operation/name”, contextCarrier);
+```
+
+#### 三. ContextSnapshot
+除了跨进程的RPC调用，另外一种追踪的常见场景是跨线程。跨线程和跨进程有很高的相似度，都是需要完成上下文的传递工作。所以ContextSnapshot具有和ContextCarrier十分类似的API风格。
+
+当发生一次**A->B**的跨线程调用时：
+1. 需要在A线程中通过ContextManager#capture操作生成ContextSnapshot对象实例
+1. 将这个ContextSnapshot对象传递到B线程中
+1. B线程通过ContextManager#continued操作完成上下文传递
+
+### 核心API
+#### 一. ContextManager
+ContextManager提供了追踪相关操作的主入口
+
+1. 创建EntrySpan
+```java
+public static AbstractSpan createEntrySpan(String operationName, ContextCarrier carrier)
+```
+通过服务名、跨进程传递的ContextCarrier，创建EntrySpan。
+
+2. 创建LocalSpan
+```java
+public static AbstractSpan createLocalSpan(String operationName)
+```
+根据服务名（或方法名），创建LocalSpan
+
+3. 创建ExitSpan
+```java
+public static AbstractSpan createExitSpan(String operationName, ContextCarrier carrier, String remotePeer)
+```
+根据服务名，跨进程传递的ContextCarrier（空容器）和远端服务地址（IP、主机名、域名 + 端口），创建ExitSpan
+
+#### 二. AbstractSpan
+AbstractSpan提供了Span内部，进行操作的各项API
+
+```java
+    /**
+     * Set the component id, which defines in {@link org.skywalking.apm.network.trace.component.ComponentsDefine}
+     *
+     * @param component
+     * @return the span for chaining.
+     */
+    AbstractSpan setComponent(Component component);
+
+    /**
+     * Only use this method in explicit instrumentation, like opentracing-skywalking-bridge.
+     * It it higher recommend don't use this for performance consideration.
+     *
+     * @param componentName
+     * @return the span for chaining.
+     */
+    AbstractSpan setComponent(String componentName);
+
+    AbstractSpan setLayer(SpanLayer layer);
+
+    /**
+     * Set a key:value tag on the Span.
+     *
+     * @return this Span instance, for chaining
+     */
+    AbstractSpan tag(String key, String value);
+
+    /**
+     * Record an exception event of the current walltime timestamp.
+     *
+     * @param t any subclass of {@link Throwable}, which occurs in this span.
+     * @return the Span, for chaining
+     */
+    AbstractSpan log(Throwable t);
+
+    AbstractSpan errorOccurred();
+
+    /**
+     * Record an event at a specific timestamp.
+     *
+     * @param timestamp The explicit timestamp for the log record.
+     * @param event the events
+     * @return the Span, for chaining
+     */
+    AbstractSpan log(long timestamp, Map<String, ?> event);
+
+    /**
+     * Sets the string name for the logical operation this span represents.
+     *
+     * @return this Span instance, for chaining
+     */
+    AbstractSpan setOperationName(String operationName);
+```
+Span的操作语义和OpenTracing类似。
+
+SpanLayer为我们的特有概念，如果是远程调用类的服务，请设置此属性，包括4个属性值
+1. DB
+1. RPC_FRAMEWORK，非HTTP类型的RPC框架，如：原生的DUBBO，MOTAN
+1. HTTP
+1. MQ
+
+### 开发插件
+#### 一. 简介
+因为所有的程序调用都是基于方法的，所以插件实际上就是基于方法的拦截，类似面向切面编程的AOP技术。sky-walking底层已经完成相关的技术封装，所以插件开发者只需要定位需要拦截的类、方法，然后结合上文中的追踪API，即可完成插件的开发。
+
+#### 二. 拦截类型
+根据Java方法，共有三种拦截类型
+1. 拦截构造函数
+1. 拦截实例方法
+1. 拦截静态方法
+
+我们将这三类拦截，分为两类，即：
+1. 实例方法增强插件，继承ClassInstanceMethodsEnhancePluginDefine
+1. 静态方法增强插件，继承ClassStaticMethodsEnhancePluginDefine
+
+当然，也可以同时支持实例和静态方法，直接继承ClassEnhancePluginDefine。但是，这种情况很少。
+
+#### 三. 实现自己的插件定义
+我们以继承ClassInstanceMethodsEnhancePluginDefine为例（ClassStaticMethodsEnhancePluginDefine十分类似，不再重复描述），描述定义插件的全过程
+
+1. 定义目标类名称
+```java
+protected abstract ClassMatch enhanceClass();
+```
+
+ClassMatch反应类的匹配方式，目前提供三种：
+
+* byName, 通过类名完整匹配
+* byClassAnnotationMatch, 通过类标注进行匹配
+* byMethodAnnotationMatch, 通过方法的标注来匹配类
+* byHierarchyMatch, 通过父类或者接口匹配
+
+注意实现：
+* 所有类、接口、标注名称，请使用字符串，不要使用`*.class.getName()`(用户环境可能会引起ClassLoader问题)。
+* by*AnnotationMatch不支持继承的标注
+* byHierarchyMatch，如果存在接口、抽象类、类间的多层继承关系，如果方法复写，则可能造成多层埋点。
+
+如：
+```java
+@Override
+protected ClassMatch enhanceClassName() {
+    return byName("org.apache.catalina.core.StandardEngineValve");		
+}		      
+
+```
+
+2. 定义构造函数拦截点
+```java
+protected InstanceMethodsInterceptPoint[] getInstanceMethodsInterceptPoints();
+
+public interface InstanceMethodsInterceptPoint {
+    /**
+     * class instance methods matcher.
+     *
+     * @return methods matcher
+     */
+    ElementMatcher<MethodDescription> getMethodsMatcher();
+
+    /**
+     * @return represents a class name, the class instance must instanceof InstanceMethodsAroundInterceptor.
+     */
+    String getMethodsInterceptor();
+
+    boolean isOverrideArgs();
+}
+```
+
+返回拦截方法的匹配器，以及对应的拦截类，同样由于潜在的ClassLoader问题，不要使用`*.class.getName()`。如何构建拦截器，请章节"四. 实现拦截器逻辑"。
+
+3. 定义skywalking-plugin.def文件
+```properties
+tomcat-7.x/8.x=org.skywalking.apm.plugin.tomcat78x.define.TomcatInstrumentation
+```
+
+* 插件名称，要求全局唯一，命名规范：目标组件+版本号
+* 插件定义类全名
+
+#### 四. 实现拦截器逻辑
+我们继续以实现实例方法拦截为例，拦截器需要实现org.skywalking.apm.agent.core.plugin.interceptor.enhance.InstanceMethodsAroundInterceptor。
+```java
+/**
+ * A interceptor, which intercept method's invocation. The target methods will be defined in {@link
+ * ClassEnhancePluginDefine}'s subclass, most likely in {@link ClassInstanceMethodsEnhancePluginDefine}
+ *
+ * @author wusheng
+ */
+public interface InstanceMethodsAroundInterceptor {
+    /**
+     * called before target method invocation.
+     *
+     * @param result change this result, if you want to truncate the method.
+     * @throws Throwable
+     */
+    void beforeMethod(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes,
+        MethodInterceptResult result) throws Throwable;
+
+    /**
+     * called after target method invocation. Even method's invocation triggers an exception.
+     *
+     * @param ret the method's original return value.
+     * @return the method's actual return value.
+     * @throws Throwable
+     */
+    Object afterMethod(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes,
+        Object ret) throws Throwable;
+
+    /**
+     * called when occur exception.
+     *
+     * @param t the exception occur.
+     */
+    void handleMethodException(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes,
+        Throwable t);
+}
+```
+
+可以在方法执行前、执行后、执行异常三个点，进行拦截，设置修改方法参数（执行前），并调用核心API，设置追踪逻辑。
+
+### 贡献插件到主仓库
+我们鼓励大家共同贡献支持各个类库的插件。
+
+大家需支持以下步骤执行：
+1. 在issue页面提出插件扩展需求，对应的版本。
+1. Fork wu-sheng/sky-walking到本地
+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) 成员完成插件审核，确定发布版本，并合并到主仓库。
\ No newline at end of file
--- a/docs/cn/Skywalking-3-Cross-Process-Propagation-Headers-Protocol-CN.md
+++ b/docs/cn/Skywalking-3-Cross-Process-Propagation-Headers-Protocol-CN.md
+# Skywalking 3 Cross Process Propagation Headers Protocol
+* Version 1.0
+
+这是Skywalking3跨进程传输头协议第一个公开版本。Skywalking是一个偏向APM的分布式追踪系统，所以，为了提供服务端处理性能。头信息会比其他的追踪系统要更复杂一些。你会发现，这个头信息，更像一个商业APM系统，并且，一些商业APM系统的头信息，比我们的要复杂的多。所以，如果你希望开发或者贡献其他语言探针、或者JAVA探针的其他市县模式，请耐心阅读，并理解此协议内容。
+
+
+# Header Item
+* Header Name: `sw3`
+* Header Value: 使用`|`分隔，包含以下内容
+
+## Values
+* Trace Segment Id
+
+Trace segment，即分布式调用链片段。这个ID为此调用链片段全局唯一ID。此ID由一次分布式调用链的一个线程执行过程独享（在Java模型中）。ID由三个Long型组成，如： `"1.2343.234234234`
+  1) 第一部分代表应用的实例ID(`application instance id`)，此ID通过注册接口由Collector分配。一般取值范围为整形，利于protobuf传输。
+  2) 第二部分为线程号，Java模型中，一般也是整形。
+  3) 第三部分又由两部分组成
+     1) 时间戳，单位毫秒
+     2) 线程内的自增序列。0到9999之间。
+
+如果你使用其他语言实现探针，你只需要保证你的ID由三个Long型构成，并全局唯一，不必完全遵守Java的ID生成规则。
+
+
+* Span Id
+
+一个整数，在trace segment内唯一，从0开始自增。
+
+* Parent Application Instance
+
+父级应用节点的应用实例ID。如：在一个RPC调用中，HEAD中是客户端的应用实例ID。
+
+* Entry Application Instance
+
+入口应用节点的应用实例ID。如：在一个分布式链路`A->B->C`中，此字段为`A`应用的实例ID。
+
+* Peer Host
+
+服务端的Peer Host或Peer Id。如：客户端使用`182.14.39.1:9080`服务端，则这个就是对应的Peer Host。
+
+_此值可以通过Collector服务获得对应的ID。如果非ID，则使用`#`开头，如果使用ID，则为整数类型。_
+
+* Entry Span Operation Name of First Trace Segment
+
+调用链入口节点的应用实例下,入口Span的operation name或id。
+
+_此值可以通过Collector服务获得对应的ID。如果非ID，则使用`#`开头，如果使用ID，则为整数类型。_
+
+* Entry Span Operation Name of Parent Trace Segment
+
+调用链父级节点的应用实例下,入口Span的operation name或id。
+
+_此值可以通过Collector服务获得对应的ID。如果非ID，则使用`#`开头，如果使用ID，则为整数类型。_
+
+* Distributed Trace Id
+
+分布式链路ID一般是整个调用链的全局唯一ID。如果针对批量消费情况，这个ID是批量中，第一个生产者的trace ID。此ID生成规则和`Trace Segment Id`一致，由三个Long型数字构成。
+
+### Sample value
+value值示例：
+1. `1.2343.234234234|1|1|1|#127.0.0.1:8080|#/portal/|#/testEntrySpan|1.2343.234234234`
+1. `1.2343.234234234|1|1|1|#127.0.0.1:8080|#/portal/|1038|1.2343.234234234`
\ No newline at end of file
--- a/docs/cn/skywalking-opentracing-CN.md
+++ b/docs/cn/skywalking-opentracing-CN.md
+* 使用 maven 和 gradle 依赖相应的工具包
+```xml
+   <dependency>
+      <groupId>org.skywalking</groupId>
+      <artifactId>apm-toolkit-opentracing</artifactId>
+      <version>{project.release.version}</version>
+   </dependency>
+```
+
+&nbsp;&nbsp;&nbsp;[ ![Download](https://api.bintray.com/packages/wu-sheng/skywalking/org.skywalking.apm-toolkit-opentracing/images/download.svg) ](https://bintray.com/wu-sheng/skywalking/org.skywalking.apm-toolkit-opentracing/_latestVersion)
+
+* 使用OpenTracing的标准API和桥接器，使用手动埋点
+```java
+Tracer tracer = new org.skywalking.apm.toolkit.opentracing.SkyWalkingTracer();
+Tracer.SpanBuilder spanBuilder = tracer.buildSpan("/yourApplication/yourService");
+
+```
\ No newline at end of file