OpenTelemetryを使用したNGINXのディストリビューティッド（分散）トレーシング

モジュールをロードし、nginx.confでトレーシングを有効にします。トップレベル（メインコンテキスト）にload_moduleディレクティブを追加し、httpコンテキスト内にOpenTelemetryディレクティブを追加します：

# Main context — load the dynamic module
load_module modules/ngx_otel_module.so;

http {
    # Export spans to the OpenTelemetry Collector over OTLP/gRPC
    otel_exporter {
        endpoint localhost:4317;
    }

    # A name that identifies this NGINX instance in traces
    otel_service_name nginx-server;

    # Emit a span per request and propagate W3C trace context to upstreams
    otel_trace on;
    otel_trace_context propagate;

    server {
        listen 80;

        location / {
            proxy_pass http://backend_app;
        }
    }
}

この設定:

• OpenTelemetryモジュール（load_module）をロードします。
• localhost:4317（otel_exporter）でリッスンしているコレクターに、OTLP/gRPC経由でスパンをエクスポートします。
• すべてのリクエスト（otel_trace on）に対してスパンを作成します。高スループット環境でトラフィックのサブセットをトレースするには、onの代わりにotel_traceを変数（たとえば、split_clientsによって駆動されるもの）に設定します。
• トレースコンテキスト（otel_trace_context propagate）を伝播します：これにより、受信したtraceparentヘッダーを抽出し（NGINXスパンを呼び出し元のサービスにリンクします）、更新されたコンテキストをアップストリームに送信されるrequestsに注入します（ダウンストリームサービスがトレースを継続できるようにします）。

特定の仮想ホストまたはルートのみをトレースしたい場合は、otel_trace onおよびotel_trace_contextディレクティブをserverまたはlocationブロックごとに設定することもできます。

ディレクティブの完全なリファレンスについては、ngx_otel_moduleのドキュメントを参照してください。

OTel Collectorを設定して、ngx_otel_moduleからトレースを受信し、NGINXスタブステータスエンドポイントからメトリクスを受信し、両方にNGINX IDを付与して、New Relicに転送します。

receivers:
  # Receives spans from ngx_otel_module (NGINX → localhost:4317)
  otlp:
    protocols:
      grpc:
        endpoint: "0.0.0.0:4317"
      http:
        endpoint: "0.0.0.0:4318"
  # Collects NGINX metrics from the stub status endpoint
  nginx:
    endpoint: <YOUR_STUB_STATUS_ENDPOINT>  # e.g. http://127.0.0.1/status
    collection_interval: 30s

processors:
  resourcedetection:
    detectors: [system]
    system:
      resource_attributes:
        host.id:
          enabled: true

  # Adds the NGINX identity so spans and metrics resolve to the SAME NGINXSERVER entity
  resource/nginx:
    attributes:
      - key: nginx.server.endpoint
        value: "<YOUR_STUB_STATUS_ENDPOINT>"  # must match the nginx receiver endpoint
        action: upsert
      - key: nginx.deployment.name
        value: "<YOUR_DEPLOYMENT_NAME>"        # a stable name for this NGINX deployment
        action: upsert

  # Sets nginx.display.name for the metrics pipeline
  transform/nginx_metrics:
    metric_statements:
      - context: resource
        statements:
          - set(attributes["nginx.display.name"], Concat(["server", attributes["nginx.deployment.name"]], ":"))

  # Same display-name stamp for the traces pipeline — ngx_otel_module spans carry no
  # NGINX identity by default; resource/nginx adds the endpoint + deployment name, and
  # this adds nginx.display.name, so the spans resolve to the NGINXSERVER entity.
  transform/nginx_traces:
    trace_statements:
      - context: resource
        statements:
          - set(attributes["nginx.display.name"], Concat(["server", attributes["nginx.deployment.name"]], ":"))

  batch:

exporters:
  otlp_http:
    endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT}
    headers:
      api-key: ${env:NEW_RELIC_LICENSE_KEY}

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resourcedetection, resource/nginx, transform/nginx_traces, batch]
      exporters: [otlp_http]
    metrics/nginx:
      receivers: [nginx]
      processors: [resourcedetection, resource/nginx, transform/nginx_metrics, batch]
      exporters: [otlp_http]

このコレクター設定には、2つのパイプラインが含まれています：

• トレースパイプライン：ngx_otel_moduleおよびインストゥルメントされたアプリケーションから、gRPC（ポート4317）またはHTTP（ポート4318）経由でOTLPトレースデータを受信します。これは、New RelicにOTLPデータを送信するすべてのサービスで使用するのと同じ標準のトレースパイプラインです。
• メトリクスパイプライン：nginxreceiverを使用して、NGINXスタブステータスエンドポイントからパフォーマンスメトリクス（接続、requests）を収集します。これらのメトリクスにより、New Relicにゴールデンメトリクスを備えたNGINXエンティティが作成されます。

両方のパイプラインは以下のプロセッサを共有します：

• resourcedetection：OpenTelemetryエコシステム全体でホストを識別するために使用される標準リソース属性であるhost.idを追加します。
• resource/nginx：nginx.server.endpointとnginx.deployment.nameを追加します。これら2つの属性は、NGINXエンティティのアイデンティティを形成します。これらを両方のパイプラインに適用することで、NGINXのスパンとメトリクスは、重複したサービスエンティティではなく、同じNGINXSERVERエンティティに解決されるようになります。
• transform/nginx_*：わかりやすいエンティティ名としてnginx.display.nameを追加します。

必要な環境変数を設定し、コレクターを起動（または再起動）します：

$
export NEW_RELIC_LICENSE_KEY="<YOUR_LICENSE_KEY>"
$
export OTEL_EXPORTER_OTLP_ENDPOINT="<YOUR_NEWRELIC_OTLP_ENDPOINT>"
$

$
sudo systemctl restart nrdot-collector

<YOUR_LICENSE_KEY>をライセンスキーに置き換えます。OTLPエンドポイントについては、New Relic OTLPエンドポイントの設定を参照してください。

設定をテストし、NGINXをリロードしてOpenTelemetryモジュールをロードします：

$
sudo nginx -t
$
sudo systemctl reload nginx

NGINXとコレクターが実行されたら、インストゥルメントされたアプリケーションを通じてトラフィックを生成します。数分後、データがNew Relicに到着していることを確認します：

-- Verify NGINX trace spans
FROM Span SELECT count(*)
WHERE nginx.deployment.name = '<YOUR_DEPLOYMENT_NAME>'
SINCE 10 minutes ago

-- Verify NGINX metrics
FROM Metric SELECT count(*)
WHERE metricName LIKE 'nginx.%'
SINCE 10 minutes ago

トレースデータが流れ始めると、New RelicはサービスとNGINXエンティティの間にCALLS関係を自動的に作成します。関係が表示されるまでに最大10分かかります。

関係を表示するには：

1. one.newrelic.com > All capabilities > All entitiesに移動します。

2. NGINXエンティティ、またはインストゥルメントされたサービスのいずれかを検索します。

3. エンティティを選択して、そのサマリーページを開きます。

4. Service mapをクリックして、エンティティ関係グラフを表示します。

   クライアントサービスがNGINXに接続され、NGINXがバックエンドサービスに接続されていることが確認できます：

   [Client app] → CALLS → [NGINX] → CALLS → [Backend app]

   コピー

   NRQLを使用して関連付けをクエリすることもできます：

   FROM Relationship SELECT *
   WHERE source.entityName = '<YOUR_NGINX_DISPLAY_NAME>'
     OR target.entityName = '<YOUR_NGINX_DISPLAY_NAME>'
   SINCE 1 day ago

   コピー

• NGINXがエラーなしでリロードされたことを確認します：sudo nginx -tおよび sudo journalctl -u nginx -n 50 --no-pager
• ngx_otel_moduleがロードされていることを確認します。unknown directive "otel_exporter"エラーは、モジュールがロードされていないことを意味します。load_moduleのパスを確認し、NGINXのバージョンに対応するnginx-module-otelがインストールされていることを確認してください。
• OTel Collectorが実行されており、otel_exporterのポートでリッスンしていることを確認します： sudo ss -tlnp | grep 4317
• コレクターのログでエラーを確認します： sudo journalctl -u nrdot-collector -n 50 --no-pager
• otel_exporterエンドポイントがコレクターのgRPCリスナーアドレスと一致していることを確認します。

• 最初のスパンが到着してから関係が表示されるまで、最大10分お待ちください。

• インストゥルメントされたアプリケーションがコレクターを通じてトレースを送信していることを確認します。関係が形成されるには、NGINXのスパンとアプリケーションのスパンの両方がNew Relicに到達する必要があります。

• クライアントアプリケーションがW3Cのtraceparentヘッダーを伝搬していることを確認してください。トレースコンテキスト伝搬がない場合、NGINXのスパンは呼び出し元のサービスに接続されません。

• resourcedetectionプロセッサとresource/nginxプロセッサの両方がコレクタートレースパイプラインに含まれていることを確認します。NGINXスパンがNGINXSERVERエンティティに解決されるには、nginx.server.endpointおよびnginx.deployment.name属性が必要です。

• otel_trace_context propagateが設定されていることを確認してください（extractまたはinject単独ではなく）。NGINXを経由するエンドツーエンドのコンテキストフローには、propagateが必要です。

• NGINXとアプリケーションの両方のスパンがトレースIDを共有していることを確認するクエリ：

  FROM Span SELECT uniques(service.name)
  WHERE trace.id IN (
    SELECT uniques(trace.id) FROM Span
    WHERE nginx.deployment.name = '<YOUR_DEPLOYMENT_NAME>'
    SINCE 10 minutes ago LIMIT 5
  )
  SINCE 10 minutes ago

  コピー

  アプリケーションのサービス名と並んで、NGINXサービスが表示されるはずです。

• resource/nginxプロセッサが（メトリクスパイプラインだけでなく）トレースパイプラインで実行されていることを確認してください。これがないと、NGINXスパンにnginx.deployment.name/nginx.server.endpointが欠落し、NGINXSERVERエンティティに解決されるのではなく、汎用サービスとして合成されます。
• nginxレシーバーとresource/nginxプロセッサでnginx.server.endpointの値が完全に同一であること、およびnginx.deployment.nameがNGINXメトリクスで使用される値と一致していることを確認します。エンティティのIDは、これら2つの値の組み合わせです。一致しない場合、異なるエンティティが生成されます。
• メトリクスパイプラインも実行します。NGINXSERVERエンティティのゴールデンメトリクスはnginxreceiverから取得されます；これがない場合、NGINXはトレース経由で引き続き表示されますが、メトリクスは表示されません。

• すべてのサービスのスパンデータが同じアカウントに届くように、各インストゥルメントされたアプリケーションは、同じOTel Collectorを経由して（または直接New Relicに）トレースを送信する必要があります。
• New Relic APMエージェントを使用しているアプリケーションの場合は、ディストリビューティッド（分散）トレーシングが有効になっており、エージェントが接続されていることを確認してください。
• OTel SDKアプリケーションの場合は、OTLPエクスポーターがコレクターに送信するように構成されていることを確認してください。
• さらに時間をおいてください。トラフィック量が少ないサービスのリレーションシップは、表示されるまでに時間がかかる場合があります。