ngx_otel_module 模块
示例配置 指令 otel_exporter otel_service_name otel_trace otel_trace_context otel_span_name otel_span_attr 默认跨度属性 嵌入变量 |
ngx_otel_module 模块 (1.23.4) 提供 OpenTelemetry 分布式跟踪支持。该模块支持 W3C 上下文传播和 OTLP/gRPC 导出协议。
该模块的源代码可在 这里 获取。下载和安装说明可在 这里 获取。
该模块也可以在预构建的 nginx-module-otel
软件包 中获取,自 1.25.3 起可用,并作为我们 商业订阅 的一部分提供的 nginx-plus-module-otel
软件包中提供。
示例配置
load_module modules/ngx_otel_module.so; events { } http { otel_exporter { endpoint localhost:4317; } server { listen 127.0.0.1:8080; location / { otel_trace on; otel_trace_context inject; proxy_pass http://backend; } } }
指令
语法: | otel_exporter { ... } |
---|---|
默认: | — |
上下文: | http |
指定 OTel 数据导出参数:
-
endpoint
- 接受遥测数据的 OTLP/gRPC 端点的地址。
-
interval
-
两次导出之间的最大间隔,默认为
5
秒。 -
batch_size
-
每个工作进程中发送的一批跨度的最大数量,默认为
512
。 -
batch_count
-
每个工作进程的挂起批次数,超过限制的跨度将被丢弃,默认为
4
。
示例:
otel_exporter { endpoint localhost:4317; interval 5s; batch_size 512; batch_count 4; }
语法: | otel_service_name |
---|---|
默认: |
otel_service_name unknown_service:nginx; |
上下文: | http |
设置 OTel 资源的 “service.name
” 属性。
语法: | otel_trace |
---|---|
默认: |
otel_trace off; |
上下文: | http , server , location |
启用或禁用 OpenTelemetry 跟踪。该指令也可以通过指定变量来启用:
split_clients "$otel_trace_id" $ratio_sampler { 10% on; * off; } server { location / { otel_trace $ratio_sampler; otel_trace_context inject; proxy_pass http://backend; } }
语法: | otel_trace_context |
---|---|
默认: |
otel_trace_context ignore; |
上下文: | http , server , location |
指定如何传播 traceparent/tracestate 头:
-
extract
- 使用请求中现有的跟踪上下文,以便从传入请求继承跟踪和父跨度的标识符。
-
inject
- 向请求添加新的上下文,覆盖现有的任何头。
-
propagate
- 更新现有上下文(结合了 extract 和 inject)。
-
ignore
- 跳过上下文头处理。
语法: | otel_span_name |
---|---|
默认: | — |
上下文: | http , server , location |
定义 OTel span 的名称。默认情况下,它是请求的位置名称。名称可以包含变量。
语法: | otel_span_attr |
---|---|
默认: | — |
上下文: | http , server , location |
添加自定义 OTel span 属性。值可以包含变量。
默认 span 属性
以下 span 属性 将自动添加:
http.method
http.target
http.route
http.scheme
http.flavor
http.user_agent
http.request_content_length
http.response_content_length
http.status_code
net.host.name
net.host.port
net.sock.peer.addr
net.sock.peer.port
嵌入式变量
-
$otel_trace_id
-
当前跨度所属的跟踪的标识符,例如,
56552bc4daa3bf39c08362527e1dd6c4
-
$otel_span_id
-
当前跨度的标识符,例如,
4c0b8531ec38ca59
-
$otel_parent_id
-
父跨度的标识符,例如,
dc94d281b0f884ea
-
$otel_parent_sampled
-
父跨度的 “
sampled
” 标志,可以是 “1
” 或 “0
”