cn docs. (apache#2273)

docs/en/concepts-and-designs/oal.md

@@ -5,7 +5,7 @@ OAL focuses on metric in Service, Service Instance and Endpoint. Because of that
 learn and use.
 
 Considering performance, reading and debugging, OAL is defined as a compile language. 
-The OAL scrips will be compiled to normal Java codes in package stage.
+The OAL scripts will be compiled to normal Java codes in package stage.
 
 ## Grammar
 Scripts should be named as `*.oal`
@@ -93,4 +93,4 @@ Endpoint_500 = from(Endpoint.*).filter(responseCode like "5%").percent()
 
 // Caculate the sum of calls for each service.
 EndpointCalls = from(Endpoint.*).sum()
-```
+```

docs/others/cn/concepts-and-designs/manual-sdk-cn.md

@@ -1,2 +1,20 @@
 ## 手动埋点SDK
-TODO
+我们目前并没有提供任何关于手动埋点的SDK。
+
+欢迎考虑贡献以下语言的探针：
+- Go
+- Python
+- C++
+
+## 什么是SkyWalking的格式和传输协议？
+可以在[协议文档](../protocols/README.md)中查看细节.
+
+## SkyWalking可以对以上的语言提供OpenCensus的出口？
+在我写这份文件的时候是不支持的。因为OC(OpenCensus)并不提供上下文可扩展机制的支持，也没有提供在操纵span的时候提供任何的hook机制。
+SkyWalking依靠这些去传播更多的东西而不是trace id和span id。
+
+我们已经在讨论中了，你可以查看https://github.com/census-instrumentation/opencensus-specs/issues/70。
+在OC正式提供这一点后, 我们才可以提供。
+
+## 那Zipkin埋点SDK可以吗？
+可以在后端文档中查看[Zipkin接收器](../setup/backend/backend-receivers.md)，它与上面提到的有些不同。

docs/others/cn/concepts-and-designs/oal-cn.md

@@ -1,2 +1,100 @@
 ## 观测分析语言
-TODO
+提供OAL(可观测性分析语言)来分析流模式下传入的数据。
+
+OAL主要关注服务， 服务实例和端点的度量、指标信息。正因为如此, OAL很容易学习和使用。
+
+考虑到性能、读取和调试, OAL被定义为一种编译语言。
+OAL脚本将在打包阶段编译为普通的java代码。
+
+## 语法
+脚本必须以`*.oal`命名结尾。
+
+```
+
+METRIC_NAME = from(SCOPE.(* | [FIELD][,FIELD ...]))
+[.filter(FIELD OP [INT | STRING])]
+.FUNCTION([PARAM][, PARAM ...])
+```
+
+## 作用域（Scope）
+主要的 **SCOPE** 包含 are `All`, `Service`, `ServiceInstance`, `Endpoint`, `ServiceRelation`, `ServiceInstanceRelation`, `EndpointRelation`.
+其中有一些二级作用域，隶属于一级作用域。
+
+你可以在[Scope定义](scope-definitions-cn.md)中查看到所有的作用域（Scope）和字段（Fields）。
+
+## 过滤器
+通过使用字段名称和表达式的过滤器来生成字段值的条件。
+
+表达式支持通过`and`，`or`和 `(...)`进行链接。
+操作运算符支持`=`, `!=`, `>`, `<`, `in (v1, v2, ...`, `like "%..."`。在语法不支持或错误的情况下进行触发器编译
+或代码生成的时候，基于字段类型的类型检测会报错。
+
+## 聚合函数
+SkyWalking OAP core提供了一些默认的函数，你也可以实现更多的聚合函数。
+
+提供的函数
+- `longAvg`.来源数据的平均值。输入的字段必须是long类型的。
+> instance_jvm_memory_max = from(ServiceInstanceJVMMemory.max).longAvg();
+
+此例中, 输入数据是每个ServiceInstanceJVMMemory的请求, 计算基于字段`max`的平均值。
+
+- `doubleAvg`.来源数据的平均值。输入的字段必须是double类型的。
+> instance_jvm_cpu = from(ServiceInstanceJVMCPU.usePercent).doubleAvg();
+
+此例中, 输入是每个ServiceInstanceJVMCPU的请求，计算基于字段`usePercent`的平均值。
+
+- `percent`. 统计来源数据中符合条件的百分比。
+> endpoint_percent = from(Endpoint.*).percent(status == true);
+
+此例中, 所有输入都是每个端点的请求，匹配条件是`endpoint.status == true`。
+
+- `sum`.统计来源数据中的总和。
+> Service_Calls_Sum = from(Service.*).sum();
+
+此例中，代表着统计每个服务的调用次数。
+
+- `p99`, `p95`, `p90`, `p75`, `p50`. 参考[p99 in WIKI](https://en.wikipedia.org/wiki/Percentile)
+> All_p99 = from(All.latency).p99(10);
+
+此例中，统计来源数据的百分之九十九的情况。
+
+- `thermodynamic`.参考[Headmap in WIKI](https://en.wikipedia.org/wiki/Heat_map))
+> All_heatmap = from(All.latency).thermodynamic(100, 20);
+
+此例中，统计所有来源数据的热力图。
+
+## 指标、度量名称
+存储实现器、警报和查询模块的指标名称。类型推断由skywalking core支持。
+
+## 分组
+所有指标数据将Scope.ID和最小量级的时间桶分组。
+
+- 在`Endpoint` scope中, Scope.ID = Endpoint id (基于服务及其端点的唯一id)
+
+## 更多例子
+```
+// Caculate p99 of both Endpoint1 and Endpoint2
+Endpoint_p99 = from(Endpoint.latency).filter(name in ("Endpoint1", "Endpoint2")).summary(0.99)
+
+// Caculate p99 of Endpoint name started with `serv`
+serv_Endpoint_p99 = from(Endpoint.latency).filter(name like ("serv%")).summary(0.99)
+
+// Caculate the avg response time of each Endpoint
+Endpoint_avg = from(Endpoint.latency).avg()
+
+// Caculate the histogram of each Endpoint by 50 ms steps.
+// Always thermodynamic diagram in UI matches this metric. 
+Endpoint_histogram = from(Endpoint.latency).histogram(50)
+
+// Caculate the percent of response status is true, for each service.
+Endpoint_success = from(Endpoint.*).filter(status = "true").percent()
+
+// Caculate the percent of response code in [200, 299], for each service.
+Endpoint_200 = from(Endpoint.*).filter(responseCode like "2%").percent()
+
+// Caculate the percent of response code in [500, 599], for each service.
+Endpoint_500 = from(Endpoint.*).filter(responseCode like "5%").percent()
+
+// Caculate the sum of calls for each service.
+EndpointCalls = from(Endpoint.*).sum()
+```

docs/others/cn/concepts-and-designs/scope-definitions-cn.md

@@ -0,0 +1,167 @@
+# 作用域（Scopes）和 字段（Fields）
+通过使用聚合函数, 请求将按时间分组, 并且在每个作用域中都有**Group Key(s)**。
+
+
+### `All`作用域
+
+| Name | Remarks | Group Key | Type | 
+|---|---|---|---|
+| endpoint  | 表示每次请求的端点。  |   | string |
+| latency  | 表示每次请求的延时。 |   |  int(in ms)  |
+| status  | 表示每次请求是成功或失败。  |   | bool(true for success)  |
+| responseCode | 如果是HTTP请求，表示响应的状态码。比如：200, 404, 302| | int |
+
+### `Service`作用域
+
+计算服务的每个请求中的度量数据。
+
+| Name | Remarks | Group Key | Type | 
+|---|---|---|---|
+| id | 表示服务的唯一ID | yes | int |
+| name | 表示服务的名称 | | string |
+| serviceInstanceName | 表示引用的服务实例id的名称 | | string |
+| endpointName | 表示端点的名称, 比如HTTP URI的全路径  | | string |
+| latency | 表示每次请求的延时 | | int |
+| status | 表示每次请求成功或失败 | | bool(true for success)  |
+| responseCode | 如果是HTTP请求，表示响应的状态码。比如：200, 404, 302 | | int|
+| type | 表示请求的类型，比如: Database, HTTP, RPC, gRPC. | | enum |
+
+### `ServiceInstance`作用域
+
+计算服务实例的每个请求中的度量数据。
+
+| Name | Remarks | Group Key | Type | 
+|---|---|---|---|
+| id | 表示服务实例的唯一ID，通常是一个数 | yes | int |
+| name |  表示服务实例的名称. 比如`ip:port@Service Name`.  **注意**: 目前原生的探针使用 `processId@Service name` 作为实例名称, 当您要在聚合中设置筛选器时, 这是无效的。 | | string|
+| serviceName | 表示服务名 | | string |
+| endpointName | 表示端点的名称, 比如HTTP URI的全路径. | | string|
+| latency | 表示每次请求的延时. | | int |
+| status | 表示每次请求成功或失败. | | bool(true for success) |
+| responseCode | 如果是HTTP请求，表示响应的状态码。 | | int |
+| type | 表示请求的类型，比如: Database, HTTP, RPC, gRPC. | | enum |
+
+#### `ServiceInstance`的二级作用域 
+
+如果服务实例是 jvm 并由 javaagent 收集, 则计算度量数据。
+
+1. `ServiceInstanceJVMCPU`作用域
+
+| Name | Remarks | Group Key | Type | 
+|---|---|---|---|
+| id | 表示服务实例的唯一ID，通常是一个数 | yes | int |
+| name |  表示服务实例的名称. 比如`ip:port@Service Name`.  **注意**: 目前原生的探针使用 `processId@Service name` 作为实例名称, 当您要在聚合中设置筛选器时, 这是无效的。 | | string|
+| serviceName | 表示服务名 | | string |
+| usePercent | 表示消耗cpu时间的百分比值 | | double|
+
+2. `ServiceInstanceJVMMemory` 作用域
+
+| Name | Remarks | Group Key | Type | 
+|---|---|---|---|
+| id | 表示服务实例的唯一ID，通常是一个数. | yes | int |
+| name |  表示服务实例的名称. 比如`ip:port@Service Name`.  **注意**: 目前原生的探针使用 `processId@Service name` 作为实例名称, 当您要在聚合中设置筛选器时, 这是无效的。 | | string|
+| serviceName | 表示服务名. | | string |
+| heapStatus | 表示此值的内存度量值是堆或非堆 | | bool |
+| init | 参考JVM文档 | | long |
+| max | 参考JVM文档 | | long |
+| used | 参考JVM文档 | | long |
+| committed | 参考JVM文档 | | long |
+
+3. `ServiceInstanceJVMMemoryPool`作用域
+
+| Name | Remarks | Group Key | Type | 
+|---|---|---|---|
+| id | 表示服务实例的唯一ID，通常是一个数. | yes | int |
+| name |  表示服务实例的名称. 比如`ip:port@Service Name`.  **注意**: 目前原生的探针使用 `processId@Service name` 作为实例名称, 当您要在聚合中设置筛选器时, 这是无效的。 | | string|
+| serviceName | 表示服务名. | | string |
+| poolType | 基于不同版本的JVM包括CODE_CACHE_USAGE, NEWGEN_USAGE, OLDGEN_USAGE, SURVIVOR_USAGE, PERMGEN_USAGE, METASPACE_USAGE | | enum |
+| init | 参考JVM文档 | | long |
+| max | 参考JVM文档 | | long |
+| used | 参考JVM文档 | | long |
+| committed | 参考JVM文档 | | long |
+
+4. `ServiceInstanceJVMGC`作用域
+
+| Name | Remarks | Group Key | Type | 
+|---|---|---|---|
+| id | 表示服务实例的唯一ID，通常是一个数. | yes | int |
+| name |  表示服务实例的名称. 比如`ip:port@Service Name`.  **注意**: 目前原生的探针使用 `processId@Service name` 作为实例名称, 当您要在聚合中设置筛选器时, 这是无效的。 | | string|
+| serviceName | 表示服务名. | | string |
+| phrase | 包括NEW和OLD | | Enum |
+| time | GC消耗时间 | | long |
+| count | GC操作的次数 | | long |
+
+### `Endpoint`作用域
+
+计算服务中端点的每个请求的度量数据。
+
+| Name | Remarks | Group Key | Type | 
+|---|---|---|---|
+| id | 表示端点的唯一ID，通常是一个数. | yes | int |
+| name | 表示端点的名称, 比如HTTP URI的全路径. | | string |
+| serviceName | 表示服务名. | | string |
+| serviceInstanceName | 表示引用的服务实例id的名称 | | string |
+| latency | 表示每次请求的延时. | | int |
+| status | 表示每次请求成功或失败. | | bool(true for success) |
+| responseCode | 如果是HTTP请求，表示响应的状态码。 | | int |
+| type | 表示请求的类型，比如: Database, HTTP, RPC, gRPC. | | enum |
+
+### `ServiceRelation`作用域
+
+计算每个请求中，一个服务和另一个服务之间的度量数据。
+
+| Name | Remarks | Group Key | Type | 
+|---|---|---|---|
+| sourceServiceId | 表示来源服务的id. | yes | int |
+| sourceServiceName | 表示来源服务的名称 | | string |
+| sourceServiceInstanceName | 表示来源服务实例的名称 | | string |
+| destServiceId | 表示目的服务的id | yes | string |
+| destServiceName | 表示目的服务的名称. | | string |
+| destServiceInstanceName | 表示目的服务实例的名称.| | string|
+| endpoint | 表示在此次调用中使用的端点. | | string
+| componentId | 表示在此次调用中使用的组件的ID. | yes | string
+| latency | 表示每次请求的延时. | | int |
+| status | 表示每次请求成功或失败. | | bool(true for success) |
+| responseCode | 如果是HTTP请求，表示响应的状态码。| | int |
+| type | 表示请求的类型，比如: Database, HTTP, RPC, gRPC. | | enum |
+| detectPoint | 表示检测到的关系所在位置。比如: 客户端、服务器或者代理。 | yes | enum|
+
+### `ServiceInstanceRelation`作用域
+
+计算每个请求中，一个服务实例和另一个服务实例之间的指标数据
+
+| Name | Remarks | Group Key | Type | 
+|---|---|---|---|
+| sourceServiceInstanceId | 表示来源服务实例的id. | yes | int|
+| sourceServiceName | 表示来源服务的名称. | | string |
+| sourceServiceInstanceName | 表示来源服务实例的名称. | | string |
+| destServiceName | 表示目的服务名称. | | |
+| destServiceInstanceId | 表示目的服务实例的id. | yes | int| 
+| destServiceInstanceName | 表示目的服务实例的名称. | | string |
+| endpoint | 表示在此次调用中使用的端点. | | string
+| componentId | 表示在此次调用中使用的组件的ID. | yes | string
+| latency | 表示每次请求的延时. | | int |
+| status | 表示每次请求成功或失败. | | bool(true for success) |
+| responseCode | 如果是HTTP请求，表示响应的状态码。| | int |
+| type | 表示请求的类型，比如: Database, HTTP, RPC, gRPC. | | enum |
+| detectPoint | 表示检测到的关系所在位置。比如: 客户端、服务器或者代理。 | yes | enum|
+
+### `EndpointRelation`作用域
+
+计算一个端点和另一个端点之间依赖关系的指标数据。
+这种关系很难检测, 同样取决于传播上一端点的追踪库。
+因此, `EndpointRelation`作用域聚合仅在由SkyWalking原生追踪下的服务中生效,
+包括自动埋点探针(如java、.net)、OpenCensus SkyWalking exporter的实现或其他依据SkyWalking规范传播的追踪上下文。
+
+| Name | Remarks | Group Key | Type | 
+|---|---|---|---|
+| endpointId | 表示依赖中为父节点的端点的id | yes | int |
+| endpoint | 表示依赖中为父节点的端点| | string| 
+| childEndpointId | 表示在第一行中依赖中作为子节点的端点id | yes | int| 
+| childEndpoint| 表示在第二行中依赖中作为子节点的端点 | | string |
+| rpcLatency | 表示端点到子端点中rpc的耗时。除去父端点本身的耗时。
+| componentId | 表示在此次调用中使用的组件的ID. | yes | string
+| status | 表示每次请求成功或失败. | | bool(true for success) |
+| responseCode | 如果是HTTP请求，表示响应的状态码。| | int |
+| type | 表示请求的类型，比如: Database, HTTP, RPC, gRPC. | | enum |
+| detectPoint | 表示检测到的关系所在位置。比如: 客户端、服务器或者代理。 | yes | enum|

docs/others/cn/setup/backend/backend-receivers.md

@@ -0,0 +1,2 @@
+# 选择接收器
+TODO