Skip to content

Commit

Permalink
docs: correct the default collector config apisix actually used for o…
Browse files Browse the repository at this point in the history 
…pentelemetry plugin (apache#11247)
  • Loading branch information
@flearc
flearc authored May 30, 2024
1 parent b88cf9d commit 55eeb6b
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 12 deletions.
20 changes: 14 additions & 6 deletions docs/en/latest/plugins/opentelemetry.md
View file
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

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:

Expand Down
20 changes: 14 additions & 6 deletions docs/zh/latest/plugins/opentelemetry.md
View file
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

如果你在 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 格式不符，因此尝试将跟踪推送到收集器时会导致错误。

:::

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

Expand Down

0 comments on commit 55eeb6b

Please sign in to comment.