Skip to content

Commit 55eeb6b

Browse files
flearcflearc
authored
docs: correct the default collector config apisix actually used for opentelemetry plugin (#11247)
1 parent b88cf9d commit 55eeb6b

File tree

2 files changed

+28
-12
lines changed

2 files changed

+28
-12
lines changed

‎docs/en/latest/plugins/opentelemetry.md

+14-6
Original file line numberDiff line numberDiff line change
@@ -53,18 +53,26 @@ You can set up the collector by configuring it in you configuration file (`conf/
5353

5454
| Name | Type | Default | Description |
5555
|--------------------------------------------|---------|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
56-
| 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}`. |
56+
| 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}`. |
5757
| resource | object | | Additional [resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) appended to the trace. |
5858
| collector | object | {address = "127.0.0.1:4318", request_timeout = 3} | OpenTelemetry Collector configuration. |
5959
| 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. |
6060
| collector.request_timeout | integer | 3 | Report request timeout in seconds. |
6161
| collector.request_headers | object | | Report request HTTP headers. |
6262
| batch_span_processor | object | | Trace span processor. |
63-
| batch_span_processor.drop_on_queue_full | boolean | true | When set to `true`, drops the span when queue is full. Otherwise, force process batches. |
64-
| batch_span_processor.max_queue_size | integer | 2048 | Maximum queue size for buffering spans for delayed processing. |
65-
| batch_span_processor.batch_timeout | number | 5 | Maximum time in seconds for constructing a batch. |
66-
| batch_span_processor.max_export_batch_size | integer | 256 | Maximum number of spans to process in a single batch. |
67-
| batch_span_processor.inactive_timeout | number | 2 | Time interval in seconds between processing batches. |
63+
| batch_span_processor.drop_on_queue_full | boolean | false | When set to `true`, drops the span when queue is full. Otherwise, force process batches. |
64+
| batch_span_processor.max_queue_size | integer | 1024 | Maximum queue size for buffering spans for delayed processing. |
65+
| batch_span_processor.batch_timeout | number | 2 | Maximum time in seconds for constructing a batch. |
66+
| batch_span_processor.max_export_batch_size | integer | 16 | Maximum number of spans to process in a single batch. |
67+
| batch_span_processor.inactive_timeout | number | 1 | Time interval in seconds between processing batches. |
68+
69+
:::note
70+
71+
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).
72+
73+
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 format with hyphens does not comply with the expected traceId format, it results in errors when attempting to push traces to the collector.
74+
75+
:::
6876

6977
You can configure these as shown below:
7078

‎docs/zh/latest/plugins/opentelemetry.md

+14-6
Original file line numberDiff line numberDiff line change
@@ -54,18 +54,26 @@ description: 本文介绍了关于 Apache APISIX `opentelemetry` 插件的基本
5454

5555
| 名称 | 类型 | 默认值 | 描述 |
5656
| ------------------------------------------ | ------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
57-
| trace_id_source | enum | random | trace ID 的来源。有效值为：`random` 或 `x-request-id`。当设置为 `x-request-id` 时，`x-request-id` 头的值将用作跟踪 ID。请确保当前请求 ID 是符合 TraceID 规范的：`[0-9a-f]{32}`。 |
57+
| 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}`。 |
5858
| resource | object | | 追加到 trace 的额外 [resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md)。 |
5959
| collector | object | {address = "127.0.0.1:4318", request_timeout = 3} | OpenTelemetry Collector 配置。 |
6060
| collector.address | string | 127.0.0.1:4318 | 数据采集服务的地址。如果数据采集服务使用的是 HTTPS 协议，可以将 address 设置为 https://127.0.0.1:4318。 |
6161
| collector.request_timeout | integer | 3 | 数据采集服务上报请求超时时长，单位为秒。 |
6262
| collector.request_headers | object | | 数据采集服务上报请求附加的 HTTP 请求头。 |
6363
| batch_span_processor | object | | trace span 处理器参数配置。 |
64-
| batch_span_processor.drop_on_queue_full | boolean | true | 如果设置为 `true` 时，则在队列排满时删除 span。否则，强制处理批次。|
65-
| batch_span_processor.max_queue_size | integer | 2048 | 处理器缓存队列容量的最大值。 |
66-
| batch_span_processor.batch_timeout | number | 5 | 构造一批 span 超时时间，单位为秒。 |
67-
| batch_span_processor.max_export_batch_size | integer | 256 | 单个批次中要处理的 span 数量。 |
68-
| batch_span_processor.inactive_timeout | number | 2 | 两个处理批次之间的时间间隔，单位为秒。 |
64+
| batch_span_processor.drop_on_queue_full | boolean | false | 如果设置为 `true` 时，则在队列排满时删除 span。否则，强制处理批次。|
65+
| batch_span_processor.max_queue_size | integer | 1024 | 处理器缓存队列容量的最大值。 |
66+
| batch_span_processor.batch_timeout | number | 2 | 构造一批 span 超时时间，单位为秒。 |
67+
| batch_span_processor.max_export_batch_size | integer | 16 | 单个批次中要处理的 span 数量。 |
68+
| batch_span_processor.inactive_timeout | number | 1 | 两个处理批次之间的时间间隔，单位为秒。 |
69+
70+
:::note
71+
72+
如果你在 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}`。
73+
74+
例如，当插件属性 `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 格式不符，因此尝试将跟踪推送到收集器时会导致错误。
75+
76+
:::
6977

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

0 commit comments

Comments
 (0)