NGINX 向けに、 OpenTelemetry と Instana を連携させる

トレース・コンテキスト伝達

ネイティブの NGINX モジュール（ OpenTelemetry ）は、分散トレーシングに W3C トレースコンテキスト標準を採用しています。 このモジュールは、以下の標準的な HTTP ヘッダーを使用してトレースコンテキストを伝播します：

• traceparent - トレースID、親スパンID、およびトレースフラグが含まれています
• tracestate - ベンダー固有のトレース情報を保持する

このモジュールは、トレース伝播のための Instana 固有のヘッダーをサポートしていません ：

• X-Instana-T (トレースID)
• X-Instana-S (Span ID)
• X-Instana-L （サンプリングレベルまたは判定）

NGINX が「 W3C 」トレースコンテキストヘッダーを含むリクエストを受信すると、自動的にトレースを継続します。 NGINX がアップストリームへのリクエストを行う際、同じ W3C 標準ヘッダーを使用してトレースコンテキストを伝播します。

OTLP エンドポイントにデータを送信する

Instana エージェントは、 NGINX サーバーから直接 OpenTelemetry データを受信できる OTLP エンドポイントを提供します。

Instana エージェントの OTLP エンドポイントにデータを送信するには、 NGINX サーバーを次のように設定してください：

http {
    otel_exporter {
        endpoint localhost:4317;
    }

    otel_service_name your_service_name;
    otel_trace on;

    server {
        listen 80;
        location / {
            otel_trace_context propagate;
            proxy_pass http://backend;
        }
    }
}

バックエンドの OTLP エンドポイントへのデータ送信

Instana エージェントと直接通信できない環境では、 NGINX サーバーを設定して、 OpenTelemetry のデータを Instana バックエンドに直接送信するようにすることができます。

詳細については、 「 OpenTelemetry のデータを Instana に送信する」 を参照してください。

Instana バックエンドの OTLP エンドポイントにデータを送信するには、 NGINX サーバーを次のように設定してください：

http {
    otel_exporter {
        endpoint https://{instana-backend-otlp-acceptor-endpoint}:4317;
        headers x-instana-key={agent-key};
    }

    otel_service_name your_service_name;
    otel_trace on;

    server {
        listen 80;
        location / {
            otel_trace_context propagate;
            proxy_pass http://backend;
        }
    }
}

{instana-backend-otlp-acceptor-endpoint} を、ご自身の Instana バックエンドエンドポイントに、 {agent-key} を、ご自身の Instana エージェントキーに置き換えてください。

Kubernetes の導入に必要な前提条件

以下の前提条件を満たしていることを確認してください。

• Kubernetes クラスター（例：Minikube、EKS、 GKE、または AKS ）
• Helm 3.x インストール済み
• kubectl クラスターにアクセスするように設定されています
• Instana バックエンドの OTLP エンドポイントと API キー

OpenTelemetry を使用した ingress-nginx のインストール

1. ingress-nginxの Helm リポジトリを追加します：

   helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
   helm repo update

2. OpenTelemetry の設定を含む Helm 値ファイル（例： ingress-nginx-values.yaml）を作成します：

   controller:
     config:
       http-snippet: |
         otel_exporter {
           endpoint https://{instana-backend-otlp-endpoint}:4317;
           header x-instana-key "{agent-key}";
         }
         otel_service_name "{your-service-name}";
         otel_resource_attr "service.namespace" "ingress-nginx";
         otel_resource_attr "k8s.cluster.name" "{your-cluster-name}";
       main-snippet: |
         load_module /etc/nginx/modules/ngx_otel_module.so;
       otel-span-attr: |
         http.request_id $request_id
         k8s.namespace $namespace
         k8s.ingress.name $ingress_name
         k8s.service.name $service_name
       otel-trace: "on"
       otel-trace-context: propagate
     image:
       digest: ""
       image: ingress-nginx-otel
       pullPolicy: Never
       registry: docker.io/library
       tag: "{version}"

   設定内の以下の値を置き換えてください：

   • {instana-backend-otlp-endpoint} - Instana のバックエンドにある OTLP エンドポイント（例： otlp-red-saas.instana.io ）
   • {agent-key} - Instana のエージェントキー
   • {your-cluster-name} - Kubernetes クラスタ名
   • {your-service-name} - サービス名
   • {version} - OpenTelemetry に対応した ingress-nginx イメージのバージョン
   • イメージ設定 - レジストリおよびイメージの要件に合わせて設定してください

3. ingress-nginx コントローラーを、以下のカスタム設定値でインストールします：

   helm install ingress-nginx ingress-nginx/ingress-nginx \
     --namespace ingress-nginx \
     --create-namespace \
     --values ingress-nginx-values.yaml

4. インストールの検証

   kubectl get pods -n ingress-nginx
   kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx

構成オプション

Helm の値ファイルには、いくつかの重要な設定セクションが含まれています：

• http-snippet : Instana エンドポイントや認証設定など、 OpenTelemetry の主要なエクスポーター設定が含まれています
• main-snippet : モジュール「 OpenTelemetry 」を読み込みます NGINX
• otel-span-attr : 各トレースに追加されるカスタム・スパン属性を定義します。これには、 Kubernetes 固有のメタデータも含まれます
• otel-trace : OpenTelemetry のトレースを有効にします
• otel-trace-context : 下流のサービスへのトレースコンテキストの伝播を設定します

カスタムspan属性

この設定には、 Instana で有用なコンテキストを提供する、 Kubernetes 固有の属性が含まれています：

これらの属性により、 Instana のUI上でトレースを特定の Kubernetes リソースと関連付けることができます。