From f6be948720f03a26913b2b0f62d4bec05aa1db22 Mon Sep 17 00:00:00 2001 From: flea Date: Fri, 10 May 2024 16:14:11 +0800 Subject: [PATCH 01/11] fix the default value for otel batch_span_processor --- conf/config-default.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/conf/config-default.yaml b/conf/config-default.yaml index 953fb1f098a3..3a146708ea05 100755 --- a/conf/config-default.yaml +++ b/conf/config-default.yaml @@ -571,13 +571,13 @@ plugin_attr: # Plugin attributes request_headers: # Set the headers to include in requests to the OpenTelemetry collector. Authorization: token # Set the authorization header to include an access token. batch_span_processor: - drop_on_queue_full: false # Drop spans when the export queue is full. - max_queue_size: 1024 # Set the maximum size of the span export queue. - batch_timeout: 2 # Set the timeout for span batches to wait in the export queue before + drop_on_queue_full: true # Drop spans when the export queue is full. + max_queue_size: 2048 # Set the maximum size of the span export queue. + batch_timeout: 5 # Set the timeout for span batches to wait in the export queue before # being sent. - inactive_timeout: 1 # Set the timeout for spans to wait in the export queue before being sent, + inactive_timeout: 2 # Set the timeout for spans to wait in the export queue before being sent, # if the queue is not full. - max_export_batch_size: 16 # Set the maximum number of spans to include in each batch sent to the + max_export_batch_size: 256 # Set the maximum number of spans to include in each batch sent to the # OpenTelemetry collector. set_ngx_var: false # Export opentelemetry variables to NGINX variables. prometheus: # Plugin: prometheus From 4071cd950189fe2f585f256329db4920f2aec5ce Mon Sep 17 00:00:00 2001 From: flea Date: Fri, 10 May 2024 16:23:25 +0800 Subject: [PATCH 02/11] change doc description for opentelemetry's trace_id_source config --- docs/en/latest/plugins/opentelemetry.md | 2 +- docs/zh/latest/plugins/opentelemetry.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/latest/plugins/opentelemetry.md b/docs/en/latest/plugins/opentelemetry.md index eeaaf7253f67..c074ea98c2f0 100644 --- a/docs/en/latest/plugins/opentelemetry.md +++ b/docs/en/latest/plugins/opentelemetry.md @@ -53,7 +53,7 @@ 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 is 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. | diff --git a/docs/zh/latest/plugins/opentelemetry.md b/docs/zh/latest/plugins/opentelemetry.md index 94dd63a3d44a..e3c3775fcd7e 100644 --- a/docs/zh/latest/plugins/opentelemetry.md +++ b/docs/zh/latest/plugins/opentelemetry.md @@ -54,7 +54,7 @@ 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。 | From 48b3ef454a9dd825192566fbdcd8fc6fdeef06bb Mon Sep 17 00:00:00 2001 From: flea Date: Sat, 11 May 2024 17:55:42 +0800 Subject: [PATCH 03/11] add a note for otel docs --- docs/en/latest/plugins/opentelemetry.md | 8 ++++++++ docs/zh/latest/plugins/opentelemetry.md | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/docs/en/latest/plugins/opentelemetry.md b/docs/en/latest/plugins/opentelemetry.md index c074ea98c2f0..0c90dcddf7ca 100644 --- a/docs/en/latest/plugins/opentelemetry.md +++ b/docs/en/latest/plugins/opentelemetry.md @@ -66,6 +66,14 @@ You can set up the collector by configuring it in you configuration file (`conf/ | 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. | +:::note + +When the `trace_id_source` is set to `x-request-id` and requests carry an `x-request-id` header generated by Envoy, there may be issues pushing traces to the collector. + +This occurs because Envoy generates its `x-request-id` header using [UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation) by default, which does not match the specified regex pattern `[0-9a-f]{32}`. + +::: + You can configure these as shown below: ```yaml title="conf/config.yaml" diff --git a/docs/zh/latest/plugins/opentelemetry.md b/docs/zh/latest/plugins/opentelemetry.md index e3c3775fcd7e..2fcfe5a23dc6 100644 --- a/docs/zh/latest/plugins/opentelemetry.md +++ b/docs/zh/latest/plugins/opentelemetry.md @@ -67,6 +67,14 @@ description: 本文介绍了关于 Apache APISIX `opentelemetry` 插件的基本 | batch_span_processor.max_export_batch_size | integer | 256 | 单个批次中要处理的 span 数量。 | | batch_span_processor.inactive_timeout | number | 2 | 两个处理批次之间的时间间隔，单位为秒。 | +:::note + +当`trace_id_source`设置为`x-request-id`且请求携带由 Envoy 默认生成的`x-request-id`标头时，将链路数据推送到采集器时可能会出现问题。 + +这是因为 Envoy 默认使用 UUID 生成其 `x-request-id` 标头，不符合指定的正则表达式模式 `[0-9a-f]{32}` 标准。 + +::: + 你可以参考以下示例进行配置： ```yaml title="./conf/config.yaml" From 45927f9a5a5dce31ea559bcfb43ec8cb7b796ab1 Mon Sep 17 00:00:00 2001 From: flea Date: Sat, 11 May 2024 17:59:09 +0800 Subject: [PATCH 04/11] add missing link --- docs/zh/latest/plugins/opentelemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zh/latest/plugins/opentelemetry.md b/docs/zh/latest/plugins/opentelemetry.md index 2fcfe5a23dc6..932d331b8d57 100644 --- a/docs/zh/latest/plugins/opentelemetry.md +++ b/docs/zh/latest/plugins/opentelemetry.md @@ -71,7 +71,7 @@ description: 本文介绍了关于 Apache APISIX `opentelemetry` 插件的基本 当`trace_id_source`设置为`x-request-id`且请求携带由 Envoy 默认生成的`x-request-id`标头时，将链路数据推送到采集器时可能会出现问题。 -这是因为 Envoy 默认使用 UUID 生成其 `x-request-id` 标头，不符合指定的正则表达式模式 `[0-9a-f]{32}` 标准。 +这是因为 Envoy 默认使用 [UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation) 生成其 `x-request-id` 标头，不符合指定的正则表达式模式 `[0-9a-f]{32}` 标准。 ::: From d858469a146e3d0fdd52f71a3b8b7ea5308dfb78 Mon Sep 17 00:00:00 2001 From: flea Date: Mon, 13 May 2024 09:27:14 +0800 Subject: [PATCH 05/11] description optimize --- docs/en/latest/plugins/opentelemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/latest/plugins/opentelemetry.md b/docs/en/latest/plugins/opentelemetry.md index 0c90dcddf7ca..7444c60a0b32 100644 --- a/docs/en/latest/plugins/opentelemetry.md +++ b/docs/en/latest/plugins/opentelemetry.md @@ -53,7 +53,7 @@ You can set up the collector by configuring it in you configuration file (`conf/ | Name | Type | Default | Description | |--------------------------------------------|---------|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 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 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. | From 749e33df4ae77f6d0960997e763f230c67d119e7 Mon Sep 17 00:00:00 2001 From: flea Date: Mon, 13 May 2024 09:29:49 +0800 Subject: [PATCH 06/11] fix chinese copyrighting ci --- docs/zh/latest/admin-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 描述 From 83181fce6dbf8e00e55318a16cece89ca2681dc8 Mon Sep 17 00:00:00 2001 From: flea Date: Mon, 13 May 2024 09:49:00 +0800 Subject: [PATCH 07/11] add note description for trace_id_source --- docs/en/latest/plugins/opentelemetry.md | 2 +- docs/zh/latest/plugins/opentelemetry.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/latest/plugins/opentelemetry.md b/docs/en/latest/plugins/opentelemetry.md index 7444c60a0b32..6aaa4670ccfd 100644 --- a/docs/en/latest/plugins/opentelemetry.md +++ b/docs/en/latest/plugins/opentelemetry.md @@ -70,7 +70,7 @@ You can set up the collector by configuring it in you configuration file (`conf/ When the `trace_id_source` is set to `x-request-id` and requests carry an `x-request-id` header generated by Envoy, there may be issues pushing traces to the collector. -This occurs because Envoy generates its `x-request-id` header using [UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation) by default, which does not match the specified regex pattern `[0-9a-f]{32}`. +This occurs because Envoy generates its `x-request-id` header using [UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation) by default, which does not match the specified regex pattern `[0-9a-f]{32}` required by opentelemetry's [traceId form](https://opentelemetry.io/docs/specs/otel/trace/api/#retrieving-the-traceid-and-spanid). ::: diff --git a/docs/zh/latest/plugins/opentelemetry.md b/docs/zh/latest/plugins/opentelemetry.md index 932d331b8d57..82bf22204534 100644 --- a/docs/zh/latest/plugins/opentelemetry.md +++ b/docs/zh/latest/plugins/opentelemetry.md @@ -71,7 +71,7 @@ description: 本文介绍了关于 Apache APISIX `opentelemetry` 插件的基本 当`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) 生成其 `x-request-id` 标头，不符合指定的正则表达式模式 `[0-9a-f]{32}` 标准。 +这是因为 Envoy 默认使用 [UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation) 生成其 `x-request-id` 标头，这与 opentelemetry 的 [traceId 格式](https://opentelemetry.io/docs/specs/otel/trace/api/#retrieving-the-traceid-and-spanid)所需的正则表达式模式 `[0-9a-f]{32}` 不匹配。 ::: From 6dee63a3d008b0e3e0749c106aa524c3fd5b97ca Mon Sep 17 00:00:00 2001 From: flea Date: Thu, 16 May 2024 15:45:17 +0800 Subject: [PATCH 08/11] Revert "fix the default value for otel batch_span_processor" This reverts commit f6be948720f03a26913b2b0f62d4bec05aa1db22. --- conf/config-default.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/conf/config-default.yaml b/conf/config-default.yaml index 3a146708ea05..953fb1f098a3 100755 --- a/conf/config-default.yaml +++ b/conf/config-default.yaml @@ -571,13 +571,13 @@ plugin_attr: # Plugin attributes request_headers: # Set the headers to include in requests to the OpenTelemetry collector. Authorization: token # Set the authorization header to include an access token. batch_span_processor: - drop_on_queue_full: true # Drop spans when the export queue is full. - max_queue_size: 2048 # Set the maximum size of the span export queue. - batch_timeout: 5 # Set the timeout for span batches to wait in the export queue before + drop_on_queue_full: false # Drop spans when the export queue is full. + max_queue_size: 1024 # Set the maximum size of the span export queue. + batch_timeout: 2 # Set the timeout for span batches to wait in the export queue before # being sent. - inactive_timeout: 2 # Set the timeout for spans to wait in the export queue before being sent, + inactive_timeout: 1 # Set the timeout for spans to wait in the export queue before being sent, # if the queue is not full. - max_export_batch_size: 256 # Set the maximum number of spans to include in each batch sent to the + max_export_batch_size: 16 # Set the maximum number of spans to include in each batch sent to the # OpenTelemetry collector. set_ngx_var: false # Export opentelemetry variables to NGINX variables. prometheus: # Plugin: prometheus From 040dba59c465ee6c2b7fc65c623a1a30cfacf3c1 Mon Sep 17 00:00:00 2001 From: flea Date: Thu, 16 May 2024 15:50:23 +0800 Subject: [PATCH 09/11] update otel doc with correct collector default config --- docs/en/latest/plugins/opentelemetry.md | 10 +++++----- docs/zh/latest/plugins/opentelemetry.md | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/en/latest/plugins/opentelemetry.md b/docs/en/latest/plugins/opentelemetry.md index 6aaa4670ccfd..1f595fc159a5 100644 --- a/docs/en/latest/plugins/opentelemetry.md +++ b/docs/en/latest/plugins/opentelemetry.md @@ -60,11 +60,11 @@ You can set up the collector by configuring it in you configuration file (`conf/ | 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 diff --git a/docs/zh/latest/plugins/opentelemetry.md b/docs/zh/latest/plugins/opentelemetry.md index 82bf22204534..3d9250d054ae 100644 --- a/docs/zh/latest/plugins/opentelemetry.md +++ b/docs/zh/latest/plugins/opentelemetry.md @@ -61,11 +61,11 @@ description: 本文介绍了关于 Apache APISIX `opentelemetry` 插件的基本 | 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 From 523168dae1aef3c11a38beaa223aeb93a5a449e5 Mon Sep 17 00:00:00 2001 From: flea Date: Tue, 28 May 2024 13:37:55 +0800 Subject: [PATCH 10/11] add more details for otel note --- docs/en/latest/plugins/opentelemetry.md | 4 +--- docs/zh/latest/plugins/opentelemetry.md | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/en/latest/plugins/opentelemetry.md b/docs/en/latest/plugins/opentelemetry.md index 1f595fc159a5..5540b5b08d86 100644 --- a/docs/en/latest/plugins/opentelemetry.md +++ b/docs/en/latest/plugins/opentelemetry.md @@ -68,9 +68,7 @@ You can set up the collector by configuring it in you configuration file (`conf/ :::note -When the `trace_id_source` is set to `x-request-id` and requests carry an `x-request-id` header generated by Envoy, there may be issues pushing traces to the collector. - -This occurs because Envoy generates its `x-request-id` header using [UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation) by default, which does not match the specified regex pattern `[0-9a-f]{32}` required by opentelemetry's [traceId form](https://opentelemetry.io/docs/specs/otel/trace/api/#retrieving-the-traceid-and-spanid). +When the `trace_id_source` is set to `x-request-id` and requests carry an `x-request-id` header generated by Envoy, you might encounter a `bad argument #1 to '?' (invalid value)` error triggered by the `hex2bytes` function. This occurs because Envoy generates its `x-request-id` header using [UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation) by default, which does not match the specified regex pattern `[0-9a-f]{32}` required by opentelemetry's [traceId form](https://opentelemetry.io/docs/specs/otel/trace/api/#retrieving-the-traceid-and-spanid). This inconsistency leads to problems in pushing traces to the collector. ::: diff --git a/docs/zh/latest/plugins/opentelemetry.md b/docs/zh/latest/plugins/opentelemetry.md index 3d9250d054ae..763d8824cf8f 100644 --- a/docs/zh/latest/plugins/opentelemetry.md +++ b/docs/zh/latest/plugins/opentelemetry.md @@ -69,9 +69,7 @@ description: 本文介绍了关于 Apache APISIX `opentelemetry` 插件的基本 :::note -当`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) 生成其 `x-request-id` 标头，这与 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` 标头时，您可能会遇到由 `hex2bytes` 函数触发的 `bad argument #1 to '?' (invalid value)` 错误。这是因为 Envoy 默认使用 [UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation) 生成其 `x-request-id` 标头，这与 opentelemetry 的 [traceId 格式](https://opentelemetry.io/docs/specs/otel/trace/api/#retrieving-the-traceid-and-spanid)所需的正则表达式模式 `[0-9a-f]{32}` 不匹配。这种不一致导致将链路数据推送到采集器时出现问题。 ::: From ce149cc4f55061d185e8b14812f68e6a14503e7e Mon Sep 17 00:00:00 2001 From: flea Date: Tue, 28 May 2024 14:31:57 +0800 Subject: [PATCH 11/11] update otel note --- docs/en/latest/plugins/opentelemetry.md | 4 +++- docs/zh/latest/plugins/opentelemetry.md | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/en/latest/plugins/opentelemetry.md b/docs/en/latest/plugins/opentelemetry.md index 5540b5b08d86..9a0ed137350a 100644 --- a/docs/en/latest/plugins/opentelemetry.md +++ b/docs/en/latest/plugins/opentelemetry.md @@ -68,7 +68,9 @@ You can set up the collector by configuring it in you configuration file (`conf/ :::note -When the `trace_id_source` is set to `x-request-id` and requests carry an `x-request-id` header generated by Envoy, you might encounter a `bad argument #1 to '?' (invalid value)` error triggered by the `hex2bytes` function. This occurs because Envoy generates its `x-request-id` header using [UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation) by default, which does not match the specified regex pattern `[0-9a-f]{32}` required by opentelemetry's [traceId form](https://opentelemetry.io/docs/specs/otel/trace/api/#retrieving-the-traceid-and-spanid). This inconsistency leads to problems in pushing traces to the collector. +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. ::: diff --git a/docs/zh/latest/plugins/opentelemetry.md b/docs/zh/latest/plugins/opentelemetry.md index 763d8824cf8f..f6e322dbe77d 100644 --- a/docs/zh/latest/plugins/opentelemetry.md +++ b/docs/zh/latest/plugins/opentelemetry.md @@ -69,7 +69,9 @@ description: 本文介绍了关于 Apache APISIX `opentelemetry` 插件的基本 :::note -当 `trace_id_source` 设置为 `x-request-id` 且请求携带由 Envoy 默认生成的 `x-request-id` 标头时，您可能会遇到由 `hex2bytes` 函数触发的 `bad argument #1 to '?' (invalid value)` 错误。这是因为 Envoy 默认使用 [UUID](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#trace-context-propagation) 生成其 `x-request-id` 标头，这与 opentelemetry 的 [traceId 格式](https://opentelemetry.io/docs/specs/otel/trace/api/#retrieving-the-traceid-and-spanid)所需的正则表达式模式 `[0-9a-f]{32}` 不匹配。这种不一致导致将链路数据推送到采集器时出现问题。 +如果你在 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 格式不符，因此尝试将跟踪推送到收集器时会导致错误。 :::