Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: correct the default collector config apisix actually used for opentelemetry plugin #11247

Merged
merged 11 commits into from
May 30, 2024
Merged

docs: correct the default collector config apisix actually used for opentelemetry plugin #11247

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
f6be948
fix the default value for otel batch_span_processor
flea0ld May 10, 2024
4071cd9
change doc description for opentelemetry's trace_id_source config
flea0ld May 10, 2024
48b3ef4
add a note for otel docs
flea0ld May 11, 2024
45927f9
add missing link
flea0ld May 11, 2024
d858469
description optimize
flea0ld May 13, 2024
749e33d
fix chinese copyrighting ci
flea0ld May 13, 2024
83181fc
add note description for trace_id_source
flea0ld May 13, 2024
6dee63a
Revert "fix the default value for otel batch_span_processor"
flea0ld May 16, 2024
040dba5
update otel doc with correct collector default config
flea0ld May 16, 2024
523168d
add more details for otel note
flea0ld May 28, 2024
ce149cc
update otel note
flea0ld May 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
20 changes: 14 additions & 6 deletions docs/en/latest/plugins/opentelemetry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,18 +53,26 @@ You can set up the collector by configuring it in you configuration file (`conf/

| Name | Type | Default | Description |
|--------------------------------------------|---------|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| trace_id_source | enum | random | 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 is matches the regex pattern `[0-9a-f]{32}`. |
| 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 | true | When set to `true`, drops the span when queue is full. Otherwise, force process batches. |
| batch_span_processor.max_queue_size | integer | 2048 | Maximum queue size for buffering spans for delayed processing. |
| batch_span_processor.batch_timeout | number | 5 | Maximum time in seconds for constructing a batch. |
| batch_span_processor.max_export_batch_size | integer | 256 | Maximum number of spans to process in a single batch. |
| batch_span_processor.inactive_timeout | number | 2 | Time interval in seconds between processing batches. |
| 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. |

:::note

When the `trace_id_source` is set to `x-request-id` and requests carry an `x-request-id` header generated by Envoy, there may be issues pushing traces to the collector.
kayx23 marked this conversation as resolved.
Show resolved Hide resolved

This occurs because Envoy generates its `x-request-id` header using [UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation) by default, which does not match the specified regex pattern `[0-9a-f]{32}` required by opentelemetry's [traceId form](https://opentelemetry.io/docs/specs/otel/trace/api/#retrieving-the-traceid-and-spanid).

:::

You can configure these as shown below:

Expand Down
4 changes: 2 additions & 2 deletions docs/zh/latest/admin-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -358,7 +358,7 @@ Route 对象 JSON 配置示例：
"desc": "hello world",
"remote_addrs": ["127.0.0.1"], # 一组客户端请求 IP 地址
"vars": [["http_user", "==", "ios"]], # 由一个或多个 [var, operator, val] 元素组成的列表
"upstream_id": "1", # upstream 对象在 etcd 中的 id ，建议使用此值
"upstream_id": "1", # upstream 对象在 etcd 中的 id，建议使用此值
"upstream": {}, # upstream 信息对象，建议尽量不要使用
"timeout": { # 为 route 设置 upstream 的连接、发送消息、接收消息的超时时间。
"connect": 3,
Expand Down Expand Up @@ -652,7 +652,7 @@ Service 对象 JSON 配置示例：
{
"id": "1", # id
"plugins": {}, # 指定 service 绑定的插件
"upstream_id": "1", # upstream 对象在 etcd 中的 id ，建议使用此值
"upstream_id": "1", # upstream 对象在 etcd 中的 id，建议使用此值
"upstream": {}, # upstream 信息对象，不建议使用
"name": "test svc", # service 名称
"desc": "hello world", # service 描述
Expand Down
20 changes: 14 additions & 6 deletions docs/zh/latest/plugins/opentelemetry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,18 +54,26 @@ description: 本文介绍了关于 Apache APISIX `opentelemetry` 插件的基本

| 名称 | 类型 | 默认值 | 描述 |
| ------------------------------------------ | ------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| trace_id_source | enum | random | trace ID 的来源。有效值为：`random` 或 `x-request-id`。当设置为 `x-request-id` 时，`x-request-id` 头的值将用作跟踪 ID。请确保当前请求 ID 是符合 TraceID 规范的：`[0-9a-f]{32}`。 |
| 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 | 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 | 两个处理批次之间的时间间隔，单位为秒。 |
| 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

当`trace_id_source`设置为`x-request-id`且请求携带由 Envoy 默认生成的`x-request-id`标头时，将链路数据推送到采集器时可能会出现问题。
flea0ld marked this conversation as resolved.
Show resolved Hide resolved

这是因为 Envoy 默认使用 [UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation) 生成其 `x-request-id` 标头，这与 opentelemetry 的 [traceId 格式](https://opentelemetry.io/docs/specs/otel/trace/api/#retrieving-the-traceid-and-spanid)所需的正则表达式模式 `[0-9a-f]{32}` 不匹配。

:::

你可以参考以下示例进行配置：

Expand Down