You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by na...@apache.org on 2024/05/30 04:30:35 UTC
(apisix) branch master updated: docs: correct the default collector config apisix actually used for opentelemetry plugin (#11247)
This is an automated email from the ASF dual-hosted git repository.
navendu 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 55eeb6b19 docs: correct the default collector config apisix actually used for opentelemetry plugin (#11247)
55eeb6b19 is described below
commit 55eeb6b194d6f12c384214ec7147416abe8a7d86
Author: fl <13...@users.noreply.github.com>
AuthorDate: Thu May 30 12:30:30 2024 +0800
docs: correct the default collector config apisix actually used for opentelemetry plugin (#11247)
---
docs/en/latest/plugins/opentelemetry.md | 20 ++++++++++++++------
docs/zh/latest/plugins/opentelemetry.md | 20 ++++++++++++++------
2 files changed, 28 insertions(+), 12 deletions(-)
diff --git a/docs/en/latest/plugins/opentelemetry.md b/docs/en/latest/plugins/opentelemetry.md
index eeaaf7253..9a0ed1373 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 f [...]
+
+:::
You can configure these as shown below:
diff --git a/docs/zh/latest/plugins/opentelemetry.md b/docs/zh/latest/plugins/opentelemetry.md
index 94dd63a3d..f6e322dbe 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 格式不符,因此尝试将跟踪推送到收集器时会导致错误。
+
+:::
你可以参考以下示例进行配置: