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