ngx_otel_module 模組

ngx_otel_module 模組 (1.23.4) 提供 OpenTelemetry 分散式追蹤支援。此模組支援 W3C 上下文傳播和 OTLP/gRPC 匯出協定。

此模組的原始碼可在此處取得：這裡。下載和安裝說明可在此處取得：這裡。

自 1.25.3 起，此模組也可在預建的 nginx-module-otel 套件中使用，並且在 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 資料匯出參數

端點

將接受遙測資料的 OTLP/gRPC 端點位址。

間隔

兩次匯出之間的最大間隔，預設為 5 秒。

批次大小

每個 worker 在一個批次中傳送的最大 span 數，預設為 512。

批次計數

每個 worker 的待處理批次數，超過限制的 span 將被捨棄，預設為 4。

範例

otel_exporter {
    endpoint    localhost:4317;
    interval    5s;
    batch_size  512;
    batch_count 4;
}

otel_service_name unknown_service:nginx;

設定 OTel 資源的「service.name」屬性。

otel_trace off;

啟用或停用 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 ignore;

指定如何傳播 traceparent/tracestate 標頭

提取

使用請求中的現有追蹤上下文，使 追蹤和父 span的識別碼繼承自傳入的請求。

注入

將新的上下文新增到請求，如果有的話，會覆寫現有標頭。

傳播

更新現有上下文（組合提取和注入）。

忽略

跳過上下文標頭處理。

定義 OTel span 的名稱。預設情況下，它是請求的位置名稱。該名稱可以包含變數。

新增自訂 OTel 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

目前 span 所屬追蹤的識別碼，例如：56552bc4daa3bf39c08362527e1dd6c4

$otel_span_id

目前 span 的識別碼，例如：4c0b8531ec38ca59

$otel_parent_id

父 span 的識別碼，例如：dc94d281b0f884ea

$otel_parent_sampled

父 span 的「sampled」旗標，可以是「1」或「0」