This is an automated email from the ASF dual-hosted git repository. tanjian pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/incubator-skywalking.git
The following commit(s) were added to refs/heads/master by this push: new bb80086 cn docs. (#2273) bb80086 is described below commit bb800863f2f9a4ba1fbf26b87e04f128039d1fac Author: Jared Tan <jian....@daocloud.io> AuthorDate: Fri Feb 22 09:32:01 2019 +0800 cn docs. (#2273) --- docs/en/concepts-and-designs/oal.md | 4 +- .../cn/concepts-and-designs/manual-sdk-cn.md | 20 ++- docs/others/cn/concepts-and-designs/oal-cn.md | 100 +++++++++++- .../concepts-and-designs/scope-definitions-cn.md | 167 +++++++++++++++++++++ docs/others/cn/setup/backend/backend-receivers.md | 2 + 5 files changed, 289 insertions(+), 4 deletions(-) diff --git a/docs/en/concepts-and-designs/oal.md b/docs/en/concepts-and-designs/oal.md index eb88a22..6e163bf 100644 --- a/docs/en/concepts-and-designs/oal.md +++ b/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() -``` \ No newline at end of file +``` diff --git a/docs/others/cn/concepts-and-designs/manual-sdk-cn.md b/docs/others/cn/concepts-and-designs/manual-sdk-cn.md index 7ce20bb..60d24f3 100644 --- a/docs/others/cn/concepts-and-designs/manual-sdk-cn.md +++ b/docs/others/cn/concepts-and-designs/manual-sdk-cn.md @@ -1,2 +1,20 @@ ## 手动埋点SDK -TODO \ No newline at end of file +我们目前并没有提供任何关于手动埋点的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),它与上面提到的有些不同。 diff --git a/docs/others/cn/concepts-and-designs/oal-cn.md b/docs/others/cn/concepts-and-designs/oal-cn.md index 4bfff76..6b39204 100644 --- a/docs/others/cn/concepts-and-designs/oal-cn.md +++ b/docs/others/cn/concepts-and-designs/oal-cn.md @@ -1,2 +1,100 @@ ## 观测分析语言 -TODO \ No newline at end of file +提供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() +``` diff --git a/docs/others/cn/concepts-and-designs/scope-definitions-cn.md b/docs/others/cn/concepts-and-designs/scope-definitions-cn.md new file mode 100644 index 0000000..89d87fc --- /dev/null +++ b/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| diff --git a/docs/others/cn/setup/backend/backend-receivers.md b/docs/others/cn/setup/backend/backend-receivers.md new file mode 100644 index 0000000..7fbb3a4 --- /dev/null +++ b/docs/others/cn/setup/backend/backend-receivers.md @@ -0,0 +1,2 @@ +# 选择接收器 +TODO