You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2022/06/17 02:42:18 UTC
[apisix] branch master updated: docs: update Chinese opentelemetry docs (#7235)
This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 88171f4a4 docs: update Chinese opentelemetry docs (#7235)
88171f4a4 is described below
commit 88171f4a48ac4ecd81a3f425ac8aeaf9c63fb6a7
Author: feihan <97...@users.noreply.github.com>
AuthorDate: Fri Jun 17 10:42:11 2022 +0800
docs: update Chinese opentelemetry docs (#7235)
---
docs/en/latest/plugins/opentelemetry.md | 6 +-
docs/zh/latest/plugins/opentelemetry.md | 131 ++++++++++++++++----------------
2 files changed, 68 insertions(+), 69 deletions(-)
diff --git a/docs/en/latest/plugins/opentelemetry.md b/docs/en/latest/plugins/opentelemetry.md
index 19eacf5ca..f702ee04f 100644
--- a/docs/en/latest/plugins/opentelemetry.md
+++ b/docs/en/latest/plugins/opentelemetry.md
@@ -116,7 +116,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
"upstream": {
"type": "roundrobin",
"nodes": {
- "10.110.149.175:8089": 1
+ "127.0.0.1:1980": 1
}
}
}'
@@ -126,7 +126,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
To disable the `opentelemetry` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
-```console
+```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
@@ -138,7 +138,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
"upstream": {
"type": "roundrobin",
"nodes": {
- "10.110.149.175:8089": 1
+ "127.0.0.1:1980": 1
}
}
}'
diff --git a/docs/zh/latest/plugins/opentelemetry.md b/docs/zh/latest/plugins/opentelemetry.md
index aa6899df3..bcbe04ede 100644
--- a/docs/zh/latest/plugins/opentelemetry.md
+++ b/docs/zh/latest/plugins/opentelemetry.md
@@ -23,42 +23,80 @@ title: opentelemetry
## 描述
-[OpenTelemetry](https://opentelemetry.io/) 提供符合 [OpenTelemetry specification](https://opentelemetry.io/docs/reference/specification/) 协议规范的 Tracing 数据上报。
+`opentelemetry` 插件可用于根据 [OpenTelemetry specification](https://opentelemetry.io/docs/reference/specification/) 协议规范上报 Tracing 数据。
-只支持 `HTTP` 协议，且请求类型为 `application/x-protobuf` 的数据上报，相关协议标准：[OTLP/HTTP Request](https://opentelemetry.io/docs/reference/specification/protocol/otlp/#otlphttp-request).
+该插件仅支持二进制编码的 [OLTP over HTTP](https://opentelemetry.io/docs/reference/specification/protocol/otlp/#otlphttp)，即请求类型为 `application/x-protobuf` 的数据上报。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------ | ------ | ------ | -------- | ------------ | ----------------------------------------------------- |
-| sampler | object | 可选 | | | 采样配置
-| sampler.name | string | 可选 | always_off | ["always_on", "always_off", "trace_id_ratio", "parent_base"] | 采样算法，always_on：全采样；always_off：不采样；trace_id_ratio：基于 trace id 的百分比采样；parent_base：如果存在 tracing 上游，则使用上游的采样决定，否则使用配置的采样算法决策
-| sampler.options | object | 可选 | | {fraction = 0, root = {name = "always_off"}} | 采样算法参数
-| sampler.options.fraction | number | 可选 | 0 | [0, 1] | trace_id_ratio 采样算法的百分比
-| sampler.options.root | object | 可选 | {name = "always_off", options = {fraction = 0}} | | parent_base 采样算法在没有上游 tracing 时，会使用 root 采样算法做决策
-| sampler.options.root.name | string | 可选 | always_off | ["always_on", "always_off", "trace_id_ratio"] | 采样算法
-| sampler.options.root.options | object | 可选 | {fraction = 0} | | 采样算法参数
-| sampler.options.root.options.fraction | number | 可选 | 0 | [0, 1] | trace_id_ratio 采样算法的百分比
-| additional_attributes | array[string] | optional | | | 追加到 trace span 的额外属性（变量名为 key，变量值为 value）
-| additional_attributes[0] | string | required | | | APISIX or Nginx 变量，例如 `http_header` or `route_id`
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+| ------------------------------------- | ------------- | ------ | ----------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------- |
+| sampler | object | 否 | | | 采样策略。 |
+| sampler.name | string | 否 | always_off | ["always_on", "always_off", "trace_id_ratio", "parent_base"] | 采样策略。`always_on`：全采样；`always_off`：不采样；`trace_id_ratio`：基于 trace id 的百分比采样；`parent_base`：如果存在 tracing 上游，则使用上游的采样决定，否则使用配置的采样策略决策。 |
+| sampler.options | object | 否 | | {fraction = 0, root = {name = "always_off"}} | 采样策略参数。 |
+| sampler.options.fraction | number | 否 | 0 | [0, 1] | `trace_id_ratio` 采样策略的百分比。 |
+| sampler.options.root | object | 否 | {name = "always_off", options = {fraction = 0}} | | `parent_base` 采样策略在没有上游 tracing 时，会使用 root 采样策略做决策。 |
+| sampler.options.root.name | string | 否 | always_off | ["always_on", "always_off", "trace_id_ratio"] | root 采样策略。 |
+| sampler.options.root.options | object | 否 | {fraction = 0} | | root 采样策略参数。 |
+| sampler.options.root.options.fraction | number | 否 | 0 | [0, 1] | `trace_id_ratio` root 采样策略的百分比 |
+| additional_attributes | array[string] | 否 | | | 追加到 trace span 的额外属性（变量名为 `key`，变量值为 `value`）。 |
+| additional_attributes[0] | string | 是 | | | APISIX 或 NGINX 变量，例如：`http_header` 或者 `route_id`。 |
+
+## 如何设置数据上报
+
+你可以通过在 `conf/config.yaml` 中指定配置来设置数据上报：
+
+| 名称 | 类型 | 默认值 | 描述 |
+| ------------------------------------------ | ------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| trace_id_source | enum | random | trace ID 的来源。有效值为：`random` 或 `x-request-id`。当设置为 `x-request-id` 时，`x-request-id` 头的值将用作跟踪 ID。请确保当前请求 ID 是符合 TraceID 规范的：`[0-9a-f]{32}`。 |
+| resource | object | | 追加到 trace 的额外 [resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md)。 |
+| collector | object | {address = "127.0.0.1:4318", request_timeout = 3} | OpenTelemetry Collector 配置。 |
+| collector.address | string | 127.0.0.1:4318 | 数据采集服务的地址。 |
+| collector.request_timeout | integer | 3 | 数据采集服务上报请求超时时长，单位为秒。 |
+| collector.request_headers | object | | 数据采集服务上报请求附加的 HTTP 请求头。 |
+| batch_span_processor | object | | trace span 处理器参数配置。 |
+| batch_span_processor.drop_on_queue_full | boolean | true | 如果设置为 `true` 时，则在队列排满时删除 span。否则，强制处理批次。|
+| batch_span_processor.max_queue_size | integer | 2048 | 处理器缓存队列容量的最大值。 |
+| batch_span_processor.batch_timeout | number | 5 | 构造一批 span 超时时间，单位为秒。 |
+| batch_span_processor.max_export_batch_size | integer | 256 | 单个批次中要处理的 span 数量。 |
+| batch_span_processor.inactive_timeout | number | 2 | 两个处理批次之间的时间间隔，单位为秒。 |
+
+你可以参考以下示例进行配置：
+
+```yaml title="./conf/config.yaml"
+plugin_attr:
+ opentelemetry:
+ resource:
+ service.name: APISIX
+ tenant.id: business_id
+ collector:
+ address: 192.168.8.211:4318
+ request_timeout: 3
+ request_headers:
+ foo: bar
+ batch_span_processor:
+ drop_on_queue_full: false
+ max_queue_size: 6
+ batch_timeout: 2
+ inactive_timeout: 1
+ max_export_batch_size: 2
+```
## 如何启用
-首先，你需要在 `config.yaml` 里面启用 opentelemetry 插件：
+`opentelemetry` 插件默认为禁用状态，你需要在配置文件（`./conf/config.yaml`）中开启该插件：
-```yaml
-# 加到 config.yaml
+```yaml title="./conf/config.yaml"
plugins:
- ... # plugin you need
- opentelemetry
```
-然后重载 APISIX。
-
-下面是一个示例，在指定的 route 上开启了 opentelemetry 插件：
+开启成功后，可以通过如下命令在指定路由上启用 `opentelemetry` 插件：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uris": [
@@ -74,58 +112,19 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
"upstream": {
"type": "roundrobin",
"nodes": {
- "10.110.149.175:8089": 1
+ "127.0.0.1:1980": 1
}
}
}'
```
-## 如何设置数据上报
-
-我们可以通过指定 `conf/config.yaml` 中的配置来设置数据上报：
-
-| 名称 | 类型 | 默认值 | 描述 |
-| ------------ | ------ | -------- | ----------------------------------------------------- |
-| trace_id_source | enum | random | 合法的取值：`random` 或 `x-request-id`，允许使用当前请求 ID 代替随机 ID 作为新的 TraceID，必须确保当前请求 ID 是符合 TraceID 规范的：`[0-9a-f]{32}` |
-| resource | object | | 追加到 trace 的额外 [resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) |
-| collector | object | {address = "127.0.0.1:4318", request_timeout = 3} | 数据采集服务 |
-| collector.address | string | 127.0.0.1:4318 | 数据采集服务地址 |
-| collector.request_timeout | integer | 3 | 数据采集服务上报请求超时时长，单位秒 |
-| collector.request_headers | object | | 数据采集服务上报请求附加的 HTTP 请求头 |
-| batch_span_processor | object | | trace span 处理器参数配置 |
-| batch_span_processor.drop_on_queue_full | boolean | true | 当处理器缓存队列慢试，丢弃新到来的 span |
-| batch_span_processor.max_queue_size | integer | 2048 | 处理器缓存队列容量最大值 |
-| batch_span_processor.batch_timeout | number | 5 | 构造一批 span 超时时长，单位秒 |
-| batch_span_processor.max_export_batch_size | integer | 256 | 一批 span 的数量，每次上报的 span 数量 |
-| batch_span_processor.inactive_timeout | number | 2 | 每隔多长时间检查是否有一批 span 可以上报，单位秒 |
-
-配置示例：
-
-```yaml
-plugin_attr:
- opentelemetry:
- resource:
- service.name: APISIX
- tenant.id: business_id
- collector:
- address: 192.168.8.211:4318
- request_timeout: 3
- request_headers:
- foo: bar
- batch_span_processor:
- drop_on_queue_full: false
- max_queue_size: 6
- batch_timeout: 2
- inactive_timeout: 1
- max_export_batch_size: 2
-```
-
## 禁用插件
-当你想禁用一条路由/服务上的 opentelemetry 插件的时候，很简单，在插件的配置中把对应的 JSON 配置删除即可，无须重启服务，即刻生效：
+当你需要禁用 `opentelemetry` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
-```console
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uris": [
@@ -136,7 +135,7 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335
"upstream": {
"type": "roundrobin",
"nodes": {
- "10.110.149.175:8089": 1
+ "127.0.0.1:1980": 1
}
}
}'