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 格式不符,因此尝试将跟踪推送到收集器时会导致错误。
+
+:::
 
 你可以参考以下示例进行配置: