diff --git a/docs/en/latest/plugins/opentelemetry.md b/docs/en/latest/plugins/opentelemetry.md index eeaaf7253f67..9a0ed137350a 100644 --- a/docs/en/latest/plugins/opentelemetry.md +++ b/docs/en/latest/plugins/opentelemetry.md @@ -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 + +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). + +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. + +::: You can configure these as shown below: diff --git a/docs/zh/latest/admin-api.md b/docs/zh/latest/admin-api.md index 1d2e17c3a73e..6564988968da 100644 --- a/docs/zh/latest/admin-api.md +++ b/docs/zh/latest/admin-api.md @@ -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, @@ -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 描述 diff --git a/docs/zh/latest/plugins/opentelemetry.md b/docs/zh/latest/plugins/opentelemetry.md index 94dd63a3d44a..f6e322dbe77d 100644 --- a/docs/zh/latest/plugins/opentelemetry.md +++ b/docs/zh/latest/plugins/opentelemetry.md @@ -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 + +如果你在 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 格式不符，因此尝试将跟踪推送到收集器时会导致错误。 + +::: 你可以参考以下示例进行配置：