This is an automated email from the ASF dual-hosted git repository.
bzp2010 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 6244b743a docs: improve `opentelemetry` plugin docs (#11900)
6244b743a is described below
commit 6244b743a004beedf783c9232688466f22a83a26
Author: Yilia Lin <[email protected]>
AuthorDate: Fri Jan 17 09:49:17 2025 +0800
docs: improve `opentelemetry` plugin docs (#11900)
---
docs/en/latest/plugins/opentelemetry.md | 261 +++++++++++++++++--------------
docs/zh/latest/plugins/opentelemetry.md | 264 +++++++++++++++++---------------
2 files changed, 285 insertions(+), 240 deletions(-)
diff --git a/docs/en/latest/plugins/opentelemetry.md
b/docs/en/latest/plugins/opentelemetry.md
index 09a17a82d..c18f3e163 100644
--- a/docs/en/latest/plugins/opentelemetry.md
+++ b/docs/en/latest/plugins/opentelemetry.md
@@ -5,7 +5,8 @@ keywords:
- API Gateway
- Plugin
- OpenTelemetry
-description: This document contains information about the Apache opentelemetry
Plugin.
+description: The opentelemetry Plugin instruments APISIX and sends traces to
OpenTelemetry collector based on the OpenTelemetry specification, in
binary-encoded OLTP over HTTP.
+
---
<!--
#
@@ -26,160 +27,186 @@ description: This document contains information about the
Apache opentelemetry P
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/opentelemetry"; />
+</head>
+
## Description
-The `opentelemetry` Plugin can be used to report tracing data according to the
[OpenTelemetry
specification](https://opentelemetry.io/docs/reference/specification/).
+The `opentelemetry` Plugin can be used to report tracing data according to the
[OpenTelemetry
Specification](https://opentelemetry.io/docs/reference/specification/).
The Plugin only supports binary-encoded [OLTP over
HTTP](https://opentelemetry.io/docs/reference/specification/protocol/otlp/#otlphttp).
-## Attributes
-
-| Name | Type | Required | Default
| Valid values
| Description
|
-|---------------------------------------|---------------|----------|-------------------------------------------------|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| sampler | object | False |
|
| Sampling configuration.
|
-| sampler.name | string | False |
always_off | ["always_on", "always_off",
"trace_id_ratio", "parent_base"] | Sampling strategy. `always_on`: always
samples, `always_off`: never samples, `trace_id_ratio`: random sampling result
based on given sampling probability, `parent_base`: use parent decision if
given, else determined by the root sampler. |
-| sampler.options | object | False |
| {fraction = 0, root = {name =
"always_off"}} | Parameters for sampling strategy.
|
-| sampler.options.fraction | number | False | 0
| [0, 1]
| Sampling probability for `trace_id_ratio`.
|
-| sampler.options.root | object | False | {name =
"always_off", options = {fraction = 0}} |
| Root sampler for `parent_base` strategy.
|
-| sampler.options.root.name | string | False |
always_off | ["always_on", "always_off",
"trace_id_ratio"] | Root sampling strategy.
|
-| sampler.options.root.options | object | False | {fraction
= 0} |
| Root sampling strategy parameters.
|
-| sampler.options.root.options.fraction | number | False | 0
| [0, 1]
| Root sampling probability for `trace_id_ratio`.
|
-| additional_attributes | array[string] | False |
|
| Additional attributes appended to the trace span.
Support built-in NGINX or APISIX variables in values, such as `http_header` or
`route_id`.
|
-| additional_header_prefix_attributes | array[string] | False |
|
| Headers or header prefixes appended to the trace span's
attributes. For example, use `x-my-header"` or `x-my-headers-*` to include all
headers with the prefix `x-my-headers-`.
[...]
-
-### Configuring the collector
-
-You can set up the collector by configuring it in you configuration file
(`conf/config.yaml`):
-
-| Name | Type | Default
| Description
|
-|--------------------------------------------|---------|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| trace_id_source | enum | x-request-id
| Source of the trace ID. Valid values are `random`
or `x-request-id`. When set to `x-request-id`, the value of the `x-request-id`
header will be used as trace ID. Make sure that it matches the regex pattern
`[0-9a-f]{32}`. |
-| resource | object |
| Additional
[resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md)
appended to the trace.
|
-| collector | object | {address =
"127.0.0.1:4318", request_timeout = 3} | OpenTelemetry Collector configuration.
|
-| collector.address | string | 127.0.0.1:4318
| Collector address. If the collector serves on
https, use https://127.0.0.1:4318 as the address.
|
-| collector.request_timeout | integer | 3
| Report request timeout in seconds.
|
-| collector.request_headers | object |
| Report request HTTP headers.
|
-| batch_span_processor | object |
| Trace span processor.
|
-| batch_span_processor.drop_on_queue_full | boolean | false
| When set to `true`, drops the span when queue is
full. Otherwise, force process batches.
|
-| batch_span_processor.max_queue_size | integer | 1024
| Maximum queue size for buffering spans for
delayed processing.
|
-| batch_span_processor.batch_timeout | number | 2
| Maximum time in seconds for constructing a batch.
|
-| batch_span_processor.max_export_batch_size | integer | 16
| Maximum number of spans to process in a single
batch.
|
-| batch_span_processor.inactive_timeout | number | 1
| Time interval in seconds between processing
batches.
|
+## Static Configurations
-:::note
+By default, configurations of the Service name, tenant ID, collector, and
batch span processor are pre-configured in [default
configuration](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua).
-If you find a `bad argument #1 to '?' (invalid value)` error triggered by the
`hex2bytes` function in error log, it's essential to verify if your traceId
matches the specified regex pattern `[0-9a-f]{32}`, as required by
opentelemetry's [traceId
format](https://opentelemetry.io/docs/specs/otel/trace/api/#retrieving-the-traceid-and-spanid).
+To customize these values, add the corresponding configurations to
`config.yaml`. For example:
-For instance, a possible scenario occurs when the plugin attribute
`trace_id_source` is configured as `x-request-id`, and requests include an
x-request-id header generated by Envoy. Envoy typically uses a
[UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation)
to create this header by default. When the opentelemetry plugin adopts this
UUID as the traceId, the presence of hyphens in the UUID can cause issues.
Since the UUID f [...]
-
-:::
-
-You can configure these as shown below in your configuration file
(`conf/config.yaml`):
-
-```yaml title="conf/config.yaml"
+```yaml
plugin_attr:
opentelemetry:
- resource:
- service.name: APISIX
- tenant.id: business_id
+ trace_id_source: x-request-id # Specify the source of the trace ID,
`x-request-id` or `random`. When set to `x-request-id`,
+ # the value of the `x-request-id` header
will be used as the trace ID.
+ resource: # Additional resource to append to the
trace.
+ service.name: APISIX # Set the Service name for OpenTelemetry
traces.
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
+ address: 127.0.0.1:4318 # Set the address of the OpenTelemetry
collector to send traces to.
+ request_timeout: 3 # Set the timeout for requests to the
OpenTelemetry collector in seconds.
+ request_headers: # Set the headers to include in requests
to the OpenTelemetry collector.
+ Authorization: token # Set the authorization header to include
an access token.
+ batch_span_processor: # Trace span processor.
+ drop_on_queue_full: false # Drop spans when the export queue is full.
+ max_queue_size: 1024 # Set the maximum size of the span export
queue.
+ batch_timeout: 2 # Set the timeout for span batches to wait
in the export queue before
+ # being sent.
+ inactive_timeout: 1 # Set the timeout for spans to wait in the
export queue before being sent,
+ # if the queue is not full.
+ max_export_batch_size: 16 # Set the maximum number of spans to
include in each batch sent to the OpenTelemetry collector.
+ set_ngx_var: false # Export opentelemetry variables to nginx
variables.
```
-## Variables
+Reload APISIX for changes to take effect.
-The following nginx variables are set by OpenTelemetry:
+## Attributes
-- `opentelemetry_context_traceparent` - [W3C trace
context](https://www.w3.org/TR/trace-context/#trace-context-http-headers-format),
e.g.: `00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01`
-- `opentelemetry_trace_id` - Trace Id of the current span
-- `opentelemetry_span_id` - Span Id of the current span
+| Name | Type | Required | Default
| Valid Values | Description |
+|---------------------------------------|---------------|----------|--------------|--------------|-------------|
+| sampler | object | False | -
| - | Sampling configuration. |
+| sampler.name | string | False |
`always_off` | ["always_on", "always_off", "trace_id_ratio", "parent_base"] |
Sampling strategy.<br>To always sample, use `always_on`.<br>To never sample,
use `always_off`.<br>To randomly sample based on a given ratio, use
`trace_id_ratio`.<br>To use the sampling decision of the span's parent, use
`parent_base`. If there is no parent, use the root sampler. |
+| sampler.options | object | False | -
| - | Parameters for sampling strategy. |
+| sampler.options.fraction | number | False | 0
| [0, 1] | Sampling ratio when the sampling strategy is
`trace_id_ratio`. |
+| sampler.options.root | object | False | -
| - | Root sampler when the sampling strategy is `parent_base`
strategy. |
+| sampler.options.root.name | string | False | -
| ["always_on", "always_off", "trace_id_ratio"] | Root sampling strategy. |
+| sampler.options.root.options | object | False | -
| - | Root sampling strategy parameters. |
+| sampler.options.root.options.fraction | number | False | 0
| [0, 1] | Root sampling ratio when the sampling strategy is
`trace_id_ratio`. |
+| additional_attributes | array[string] | False | -
| - | Additional attributes appended to the trace span. Support
[built-in variables](https://apisix.apache.org/docs/apisix/apisix-variable/) in
values. |
+| additional_header_prefix_attributes | array[string] | False | -
| - | Headers or header prefixes appended to the trace span's
attributes. For example, use `x-my-header"` or `x-my-headers-*` to include all
headers with the prefix `x-my-headers-`. |
-How to use variables? you have to add it to your configuration file
(`conf/config.yaml`):
+## Examples
-```yaml title="conf/config.yaml"
-http:
- enable_access_log: true
- access_log: "/dev/stdout"
- access_log_format: '{"time":
"$time_iso8601","opentelemetry_context_traceparent":
"$opentelemetry_context_traceparent","opentelemetry_trace_id":
"$opentelemetry_trace_id","opentelemetry_span_id":
"$opentelemetry_span_id","remote_addr": "$remote_addr","uri": "$uri"}'
- access_log_format_escape: json
-plugins:
- - opentelemetry
-plugin_attr:
- opentelemetry:
- set_ngx_var: true
-```
+The examples below demonstrate how you can work with the `opentelemetry`
Plugin for different scenarios.
-## Enable Plugin
+### Enable `opentelemetry` Plugin
-To enable the Plugin, you have to add it to your configuration file
(`conf/config.yaml`):
+By default, the `opentelemetry` Plugin is disabled in APISIX. To enable, add
the Plugin to your configuration file as such:
-```yaml title="conf/config.yaml"
+```yaml title="config.yaml"
plugins:
- ...
- opentelemetry
```
-Now, you can enable the Plugin on a specific Route:
+Reload APISIX for changes to take effect.
+
+See [static configurations](#static-configurations) for other available
options you can configure in `config.yaml`.
-:::note
-You can fetch the `admin_key` from `config.yaml` and save to an environment
variable with the following command:
+### Send Traces to OpenTelemetry
-```bash
-admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed
's/"//g')
+The following example demonstrates how to trace requests to a Route and send
traces to OpenTelemetry.
+
+Start an OpenTelemetry collector instance in Docker:
+
+```shell
+docker run -d --name otel-collector -p 4318:4318
otel/opentelemetry-collector-contrib
```
-:::
+Create a Route with `opentelemetry` Plugin:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key"
-X PUT -d '
-{
- "methods": ["GET"],
- "uris": [
- "/uid/*"
- ],
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "otel-tracing-route",
+ "uri": "/anything",
"plugins": {
- "opentelemetry": {
- "sampler": {
- "name": "always_on"
- }
+ "opentelemetry": {
+ "sampler": {
+ "name": "always_on"
}
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org": 1
+ }
}
-}'
+ }'
```
-## Delete Plugin
-
-To remove 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.
+Send a request to the Route:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key"
-X PUT -d '
-{
- "methods": ["GET"],
- "uris": [
- "/uid/*"
- ],
- "plugins": {
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- }
-}'
+curl "http://127.0.0.1:9080/anything";
+```
+
+You should receive an `HTTP/1.1 200 OK` response.
+
+In OpenTelemetry collector's log, you should see information similar to the
following:
+
+```text
+2024-02-18T17:14:03.825Z info ResourceSpans #0
+Resource SchemaURL:
+Resource attributes:
+ -> telemetry.sdk.language: Str(lua)
+ -> telemetry.sdk.name: Str(opentelemetry-lua)
+ -> telemetry.sdk.version: Str(0.1.1)
+ -> hostname: Str(e34673e24631)
+ -> service.name: Str(APISIX)
+ScopeSpans #0
+ScopeSpans SchemaURL:
+InstrumentationScope opentelemetry-lua
+Span #0
+ Trace ID : fbd0a38d4ea4a128ff1a688197bc58b0
+ Parent ID :
+ ID : af3dc7642104748a
+ Name : GET /anything
+ Kind : Server
+ Start time : 2024-02-18 17:14:03.763244032 +0000 UTC
+ End time : 2024-02-18 17:14:03.920229888 +0000 UTC
+ Status code : Unset
+ Status message :
+Attributes:
+ -> net.host.name: Str(127.0.0.1)
+ -> http.method: Str(GET)
+ -> http.scheme: Str(http)
+ -> http.target: Str(/anything)
+ -> http.user_agent: Str(curl/7.64.1)
+ -> apisix.route_id: Str(otel-tracing-route)
+ -> apisix.route_name: Empty()
+ -> http.route: Str(/anything)
+ -> http.status_code: Int(200)
+{"kind": "exporter", "data_type": "traces", "name": "debug"}
+```
+
+To visualize these traces, you can export your telemetry to backend Services,
such as Zipkin and Prometheus. See
[exporters](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter)
for more details.
+
+### Using Trace Variables in Logging
+
+The following example demonstrates how to configure the `opentelemetry` Plugin
to set the following built-in variables, which can be used in logger Plugins or
access logs:
+
+- `opentelemetry_context_traceparent`: [trace
parent](https://www.w3.org/TR/trace-context/#trace-context-http-headers-format)
ID
+- `opentelemetry_trace_id`: trace ID of the current span
+- `opentelemetry_span_id`: span ID of the current span
+
+Update the configuration file as below. You should customize the access log
format to use the `opentelemetry` Plugin variables, and set `opentelemetry`
variables in the `set_ngx_var` field.
+
+```yaml title="conf/config.yaml"
+nginx_config:
+ http:
+ enable_access_log: true
+ access_log_format: '{"time":
"$time_iso8601","opentelemetry_context_traceparent":
"$opentelemetry_context_traceparent","opentelemetry_trace_id":
"$opentelemetry_trace_id","opentelemetry_span_id":
"$opentelemetry_span_id","remote_addr": "$remote_addr"}'
+ access_log_format_escape: json
+plugin_attr:
+ opentelemetry:
+ set_ngx_var: true
+```
+
+Reload APISIX for configuration changes to take effect.
+
+You should see access log entries similar to the following when you generate
requests:
+
+```text
+{"time": "18/Feb/2024:15:09:00 +0000","opentelemetry_context_traceparent":
"00-fbd0a38d4ea4a128ff1a688197bc58b0-8f4b9d9970a02629-01","opentelemetry_trace_id":
"fbd0a38d4ea4a128ff1a688197bc58b0","opentelemetry_span_id":
"af3dc7642104748a","remote_addr": "172.10.0.1"}
```
diff --git a/docs/zh/latest/plugins/opentelemetry.md
b/docs/zh/latest/plugins/opentelemetry.md
index f6e322dbe..52b9fdc17 100644
--- a/docs/zh/latest/plugins/opentelemetry.md
+++ b/docs/zh/latest/plugins/opentelemetry.md
@@ -5,7 +5,7 @@ keywords:
- API 网关
- Plugin
- OpenTelemetry
-description: 本文介绍了关于 Apache APISIX `opentelemetry` 插件的基本信息及使用方法。
+description: opentelemetry 插件可用于根据 OpenTelemetry 协议规范上报 Traces 数据，该插件仅支持二进制编码的
OLTP over HTTP。
---
<!--
@@ -27,163 +27,181 @@ description: 本文介绍了关于 Apache APISIX `opentelemetry` 插件的基本
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/opentelemetry"; />
+</head>
+
## 描述
-`opentelemetry` 插件可用于根据 [OpenTelemetry
specification](https://opentelemetry.io/docs/reference/specification/) 协议规范上报
Tracing 数据。
+`opentelemetry` 插件可用于根据 [OpenTelemetry
Specification](https://opentelemetry.io/docs/reference/specification/) 协议规范上报
Traces 数据。该插件仅支持二进制编码的 OLTP over HTTP，即请求类型为 `application/x-protobuf` 的数据上报。
-该插件仅支持二进制编码的 [OLTP over
HTTP](https://opentelemetry.io/docs/reference/specification/protocol/otlp/#otlphttp)，即请求类型为
`application/x-protobuf` 的数据上报。
+## 静态配置
-## 属性
+默认情况下，服务名称、租户 ID、collector 和 batch span processor
的配置已预配置在[默认配置](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua)中。
+
+要自定义这些值，请将相应的配置添加到 `config.yaml` 中。例如：
-| 名称 | 类型 | 必选项 | 默认值
| 有效值
| 描述 |
-| ------------------------------------- | ------------- | ------ |
----------------------------------------------- |
------------------------------------------------------------ |
----------------------------------------------------- |
-| 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 的额外属性，支持内置 NGINX 或 APISIX
变量，例如：`http_header` 或者 `route_id`。 |
-| additional_header_prefix_attributes | array[string] | False |
|
| 附加到跟踪范围属性的标头或标头前缀。例如，使用 `x-my-header"` 或
`x-my-headers-*` 来包含带有前缀 `x-my-headers-` 的所有标头。
|
-
-## 如何设置数据上报
-
-你可以通过在 `conf/config.yaml` 中指定配置来设置数据上报：
-
-| 名称 | 类型 | 默认值
| 描述
|
-| ------------------------------------------ | ------- |
------------------------------------------------- |
-------------------------------------------------------------------------------------------------------------------------------------------------
|
-| trace_id_source | enum | x-request-id
| 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
| 数据采集服务的地址。如果数据采集服务使用的是 HTTPS 协议，可以将 address 设置为
https://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 | false
| 如果设置为 `true` 时，则在队列排满时删除 span。否则，强制处理批次。|
-| batch_span_processor.max_queue_size | integer | 1024
| 处理器缓存队列容量的最大值。 |
-| batch_span_processor.batch_timeout | number | 2
| 构造一批 span 超时时间，单位为秒。 |
-| batch_span_processor.max_export_batch_size | integer | 16
| 单个批次中要处理的 span 数量。 |
-| batch_span_processor.inactive_timeout | number | 1
| 两个处理批次之间的时间间隔，单位为秒。 |
-
-:::note
-
-如果你在 error log 中发现由 hex2bytes 函数引发的 `bad argument #1 to '?' (invalid value)`
错误，务必确认你的 traceId 是否满足 opentelemetry 的 [traceId
格式](https://opentelemetry.io/docs/specs/otel/trace/api/#retrieving-the-traceid-and-spanid)
所需的正则规范`[0-9a-f]{32}`。
-
-例如，当插件属性 `trace_id_source` 配置为 `x-request-id` 时，如果请求包含由 Envoy 生成的 x-request-id
请求头，可能会发生上述情况。Envoy 默认使用
[UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation)
生成该请求头。当 opentelemetry 插件将此 UUID 作为 traceId 时，UUID 中的 `-` 可能会引起问题。由于带有 `-` 的
UUID 格式与 traceId 格式不符，因此尝试将跟踪推送到收集器时会导致错误。
-
-:::
-
-你可以参考以下示例进行配置：
-
-```yaml title="./conf/config.yaml"
+```yaml
plugin_attr:
opentelemetry:
- resource:
- service.name: APISIX
- tenant.id: business_id
+ trace_id_source: x-request-id # 指定追踪 ID 的来源，`x-request-id` 或
`random`。当设置为 `x-request-id` 时，
+ # `x-request-id` 头的值将用作追踪 ID。
+ resource: # 追加到追踪的额外资源。
+ service.name: APISIX # 为 OpenTelemetry 追踪设置服务名称。
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
+ address: 127.0.0.1:4318 # 设置要发送追踪的 OpenTelemetry 收集器的地址。
+ request_timeout: 3 # 设置请求 OpenTelemetry 收集器的超时时间（秒）。
+ request_headers: # 设置请求 OpenTelemetry 收集器时要包含的头信息。
+ Authorization: token # 设置授权头以包含访问令牌。
+ batch_span_processor: # 追踪跨度处理器。
+ drop_on_queue_full: false # 当导出队列满时丢弃跨度。
+ max_queue_size: 1024 # 设置跨度导出队列的最大大小。
+ batch_timeout: 2 # 设置跨度批次在导出队列中等待的超时时间，
+ # 然后发送。
+ inactive_timeout: 1 # 设置跨度在导出队列中等待的超时时间，如果队列不满，则发送。
+ max_export_batch_size: 16 # 设置每个批次发送到 OpenTelemetry 收集器的跨度的最大数量。
+ set_ngx_var: false # 将 opentelemetry 变量导出到 nginx 变量。
```
-## 如何使用变量
+重新加载 APISIX 以使更改生效。
-以下`nginx`变量是由`opentelemetry` 设置的。
+## 属性
-- `opentelemetry_context_traceparent` - [W3C trace
context](https://www.w3.org/TR/trace-context/#trace-context-http-headers-format),
例如：`00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01`
-- `opentelemetry_trace_id` - 当前 span 的 trace_id
-- `opentelemetry_span_id` - 当前 span 的 span_id
+| 名称 | 类型 | 必选项 | 默认值 |
有效值 | 描述 |
+|---------------------------------------|---------------|----------|--------------|--------------|-------------|
+| sampler | object | 否 | -
| - | 采样策略。 |
+| sampler.name | string | 否 |
`always_off` | ["always_on", "always_off", "trace_id_ratio", "parent_base"] |
采样策略。<br>`always_on`：全采样；`always_off`：不采样；`trace_id_ratio`：基于 trace id
的百分比采样；`parent_base`：如果存在 tracing 上游，则使用上游的采样决定，否则使用配置的采样策略决策。|
+| sampler.options | object | 否 | -
| - | 采样策略参数。 |
+| sampler.options.fraction | number | 否 | 0
| [0, 1] | `trace_id_ratio`：采样策略的百分比。 |
+| sampler.options.root | object | 否 | -
| - | `parent_base`：采样策略在没有上游 tracing 时，会使用 root 采样策略做决策。|
+| sampler.options.root.name | string | 否 | -
| ["always_on", "always_off", "trace_id_ratio"] | root 采样策略。 |
+| sampler.options.root.options | object | 否 | -
| - | root 采样策略参数。 |
+| sampler.options.root.options.fraction | number | 否 | 0
| [0, 1] | `trace_id_ratio` root 采样策略的百分比|
+| additional_attributes | array[string] | 否 | -
| - | 追加到 trace span 的额外属性，支持内置 NGINX 或 [APISIX
变量](https://apisix.apache.org/docs/apisix/apisix-variable/)。|
+| additional_header_prefix_attributes | array[string] | 否 | -
| - | 附加到跟踪范围属性的标头或标头前缀。例如，使用 `x-my-header"` 或 `x-my-headers-*`
来包含带有前缀 `x-my-headers-` 的所有标头。 |
-如何使用？你需要在配置文件（`./conf/config.yaml`）设置如下：
+## 示例
-```yaml title="./conf/config.yaml"
-http:
- enable_access_log: true
- access_log: "/dev/stdout"
- access_log_format: '{"time":
"$time_iso8601","opentelemetry_context_traceparent":
"$opentelemetry_context_traceparent","opentelemetry_trace_id":
"$opentelemetry_trace_id","opentelemetry_span_id":
"$opentelemetry_span_id","remote_addr": "$remote_addr","uri": "$uri"}'
- access_log_format_escape: json
-plugins:
- - opentelemetry
-plugin_attr:
- opentelemetry:
- set_ngx_var: true
-```
+以下示例展示了如何在不同场景下使用 `opentelemetry` 插件。
-## 如何启用
+### 启用 opentelemetry 插件
-`opentelemetry` 插件默认为禁用状态，你需要在配置文件（`./conf/config.yaml`）中开启该插件：
+默认情况下，APISIX 中的 `opentelemetry` 插件是禁用的。要启用它，请将插件添加到配置文件中，如下所示：
-```yaml title="./conf/config.yaml"
+```yaml title="config.yaml"
plugins:
- - ... # plugin you need
+ - ...
- opentelemetry
```
-开启成功后，可以通过如下命令在指定路由上启用 `opentelemetry` 插件：
+重新加载 APISIX 以使更改生效。
+
+有关 `config.yaml` 中可以配置的其他选项，请参阅[静态配置](#静态配置)。
-:::note
+### 将 Traces 上报到 OpenTelemetry
-您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
+以下示例展示了如何追踪对路由的请求并将 traces 发送到 OpenTelemetry。
-```bash
-admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed
's/"//g')
+在 Docker 启动一个 OpenTelemetry collector 实例：
+
+```shell
+docker run -d --name otel-collector -p 4318:4318
otel/opentelemetry-collector-contrib
```
-:::
+创建一个开启了 `opentelemetry` 插件的路由：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "methods": ["GET"],
- "uris": [
- "/uid/*"
- ],
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "otel-tracing-route",
+ "uri": "/anything",
"plugins": {
- "opentelemetry": {
- "sampler": {
- "name": "always_on"
- }
+ "opentelemetry": {
+ "sampler": {
+ "name": "always_on"
}
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org": 1
+ }
}
-}'
+ }'
```
-## 删除插件
-
-当你需要禁用 `opentelemetry` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+向路由发送请求：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "methods": ["GET"],
- "uris": [
- "/uid/*"
- ],
- "plugins": {
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- }
-}'
+curl "http://127.0.0.1:9080/anything";
+```
+
+你应该收到一个 `HTTP/1.1 200 OK` 响应。
+
+在 OpenTelemetry collector 的日志中，你应该看到类似以下的信息：
+
+```text
+2024-02-18T17:14:03.825Z info ResourceSpans #0
+Resource SchemaURL:
+Resource attributes:
+ -> telemetry.sdk.language: Str(lua)
+ -> telemetry.sdk.name: Str(opentelemetry-lua)
+ -> telemetry.sdk.version: Str(0.1.1)
+ -> hostname: Str(e34673e24631)
+ -> service.name: Str(APISIX)
+ScopeSpans #0
+ScopeSpans SchemaURL:
+InstrumentationScope opentelemetry-lua
+Span #0
+ Trace ID : fbd0a38d4ea4a128ff1a688197bc58b0
+ Parent ID :
+ ID : af3dc7642104748a
+ Name : GET /anything
+ Kind : Server
+ Start time : 2024-02-18 17:14:03.763244032 +0000 UTC
+ End time : 2024-02-18 17:14:03.920229888 +0000 UTC
+ Status code : Unset
+ Status message :
+Attributes:
+ -> net.host.name: Str(127.0.0.1)
+ -> http.method: Str(GET)
+ -> http.scheme: Str(http)
+ -> http.target: Str(/anything)
+ -> http.user_agent: Str(curl/7.64.1)
+ -> apisix.route_id: Str(otel-tracing-route)
+ -> apisix.route_name: Empty()
+ -> http.route: Str(/anything)
+ -> http.status_code: Int(200)
+{"kind": "exporter", "data_type": "traces", "name": "debug"}
+```
+
+要可视化这些追踪，你可以将 traces 导出到后端服务，例如 Zipkin 和
Prometheus。有关更多详细信息，请参阅[exporters](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter)。
+
+### 在日志中使用 trace 变量
+
+以下示例展示了如何配置 `opentelemetry` 插件以设置以下内置变量，这些变量可以在日志插件或访问日志中使用：
+
+- `opentelemetry_context_traceparent`: [W3C trace
context](https://www.w3.org/TR/trace-context/#trace-context-http-headers-format)
+- `opentelemetry_trace_id`: 当前 span 的 trace_id
+- `opentelemetry_span_id`: 当前 span 的 span_id
+
+如下更新配置文件。你应该自定义访问日志格式以使用 `opentelemetry` 插件变量，并在 `set_ngx_var` 字段中设置
`opentelemetry` 变量。
+
+```yaml title="conf/config.yaml"
+nginx_config:
+ http:
+ enable_access_log: true
+ access_log_format: '{"time":
"$time_iso8601","opentelemetry_context_traceparent":
"$opentelemetry_context_traceparent","opentelemetry_trace_id":
"$opentelemetry_trace_id","opentelemetry_span_id":
"$opentelemetry_span_id","remote_addr": "$remote_addr"}'
+ access_log_format_escape: json
+plugin_attr:
+ opentelemetry:
+ set_ngx_var: true
+```
+
+重新加载 APISIX 以使配置更改生效。
+
+```text
+{"time": "18/Feb/2024:15:09:00 +0000","opentelemetry_context_traceparent":
"00-fbd0a38d4ea4a128ff1a688197bc58b0-8f4b9d9970a02629-01","opentelemetry_trace_id":
"fbd0a38d4ea4a128ff1a688197bc58b0","opentelemetry_span_id":
"af3dc7642104748a","remote_addr": "172.10.0.1"}
```
