プロキシのトレース

プロキシに関するトレース情報の収集を含めるよう、トレースを設定することができます。

Datadog APM は Envoy v1.9.0 以降に含まれています。

Datadog APM を有効にする

注: 以下のコンフィギュレーション例は、Envoy v1.19 用です。他のバージョンのコンフィギュレーション例はdd-opentracing-cppGitHub リポジトリにあります。

Datadog APM を Envoy で使用するには、以下の設定をする必要があります。

トレースを Datadog Agent に送信するためのクラスター
トレースをアクティブにするための http_connection_manager コンフィギュレーション

トレースを Datadog Agent に送信するためのクラスターを追加します:

 clusters:
 ... existing cluster configs ...
 - name: datadog_agent
   connect_timeout: 1s
   type: strict_dns
   lb_policy: round_robin
   load_assignment:
     cluster_name: datadog_agent
     endpoints:
     - lb_endpoints:
       - endpoint:
           address:
             socket_address:
               address: localhost
               port_value: 8126

Envoy がコンテナやオーケストレーション環境で動作している場合は、address の値を変更します。

トレースを有効にするには、http_connection_manager セクションに以下の追加構成を含めます。

 - name: envoy.filters.network.http_connection_manager
   typed_config:
     "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
     generate_request_id: true
     request_id_extension:
       typed_config:
         "@type": type.googleapis.com/envoy.extensions.request_id.uuid.v3.UuidRequestIdConfig
         use_request_id_for_trace_sampling: false
     tracing:
       provider:
         name: envoy.tracers.datadog
         typed_config:
           "@type": type.googleapis.com/envoy.config.trace.v3.DatadogConfig
           collector_cluster: datadog_agent
           service_name: envoy-v1.19

collector_cluster の値は、Datadog Agent クラスターに付けられた名前と一致している必要があります。service_name は、Envoy の使用を表す別の値に変えることもできます。

このコンフィギュレーションにより、Envoy への HTTP リクエストが起動し、Datadog トレースに伝播して、リクエストが APM UI に表示されます。

Envoy v1.19 コンフィギュレーションの例

以下の構成例では、Datadog APM を使用してトレースを有効にするために必要な項目の配置を示します。

static_resources:
  listeners:
  - address:
      socket_address:
        address: 0.0.0.0
        port_value: 80
    traffic_direction: OUTBOUND
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          generate_request_id: true
          request_id_extension:
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.request_id.uuid.v3.UuidRequestIdConfig
              use_request_id_for_trace_sampling: false
          tracing:
          # Datadog トレーサーを使用します
            provider:
              name: envoy.tracers.datadog
              typed_config:
                "@type": type.googleapis.com/envoy.config.trace.v3.DatadogConfig
                collector_cluster: datadog_agent   # 指定されたクラスターと一致
                service_name: envoy-v1.19          # ユーザー定義サービス名
          codec_type: auto
          stat_prefix: ingress_http
          route_config:
            name: local_route
            virtual_hosts:
            - name: backend
              domains:
              - "*"
              routes:
              - match:
                  prefix: "/"
                route:
                  cluster: service1
          # ヘルスチェックのリクエストのトレースはサンプリングされるべきではありません。
          http_filters:
          - name: envoy.filters.http.health_check
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.health_check.v3.HealthCheck
              pass_through_mode: false
              headers:
                - exact_match: /healthcheck
                  name: :path
          - name: envoy.filters.http.router
            typed_config: {}
          use_remote_address: true
  clusters:
  - name: service1
    connect_timeout: 0.250s
    type: strict_dns
    lb_policy: round_robin
    load_assignment:
      cluster_name: service1
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: service1
                port_value: 80
  # トレースを送信するための Datadog Agent のアドレスで
  # このクラスターを構成します。
  - name: datadog_agent
    connect_timeout: 1s
    type: strict_dns
    lb_policy: round_robin
    load_assignment:
      cluster_name: datadog_agent
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: localhost
                port_value: 8126

admin:
  access_log_path: "/dev/null"
  address:
    socket_address:
      address: 0.0.0.0
      port_value: 8001

メトリクスの除外

Envoy の dog_statsd コンフィギュレーションを使用してメトリクスを送信している場合、以下のコンフィギュレーションを追加することで、datadog_agent クラスターからのアクティビティを_除外_できます。

stats_config:
  stats_matcher:
    exclusion_list:
      patterns:
      - prefix: "cluster.datadog_agent."

サンプリング

Envoy から始まるトレースのDatadogへの送信量を制御するには、パラメーター DD_TRACE_SAMPLING_RULES を 0.0 (0%) から 1.0 (100%) の間の値に設定し、サンプリングレートを指定してください。値を指定しない場合、Envoy から始まるトレースの 100% が送信されます。

Datadog Agent が算出したサンプリングレート (10 トレース/秒/Agent) を使用し、100% に設定されたデフォルトのサンプリングルールを無視するには、パラメーター DD_TRACE_SAMPLING_RULES を空の配列に設定します。

DD_TRACE_SAMPLING_RULES=[]

また、サービスごとに 0.0 (0%) から 1.0 (100%) の間で明示的にサンプリングレートを定義することができます。例えば、サービス envoy-proxy のサンプリングレートを 10% に設定するには、以下のようにします。

DD_TRACE_SAMPLING_RULES=[{"service": "envoy-proxy","sample_rate": 0.1}]

DD_TRACE_SAMPLING_RULES でサンプリングレートを構成するには、Envoy の実行方法に応じて、以下の方法のいずれかを使用します。

シェルスクリプト: スクリプトで envoy を実行する直前に環境変数を設定します。
```
#!/bin/sh
export DD_TRACE_SAMPLING_RULES=[]
envoy -c envoy-config.yaml
```

Docker Compose のセットアップ: サービス定義の environment セクションに環境変数を設定します。

services:
  envoy:
    image: envoyproxy/envoy:v1.19-latest
    entrypoint: []
    command:
        - envoy
        - -c
        - /etc/envoy/envoy.yaml
    volumes:
        - './envoy.yaml:/etc/envoy/envoy.yaml:ro'
    environment:
        - DD_TRACE_SAMPLING_RULES=[]

Kubernetes ポッド内のコンテナとして: ポッド仕様の対応する containers エントリの env セクションに環境変数を指定します。

apiVersion: v1
kind: Pod
metadata:
  name: envoy
spec:
  containers:
  - name: envoy
    image: envoyproxy/envoy:v1.20-latest
    env:
    - name: DD_TRACE_SAMPLING_RULES
      value: "[]"

環境変数

利用可能な環境変数は、Envoy に埋め込まれた C++ トレーサーのバージョンによって異なります。

注: Datadog Agent のアドレスは cluster 設定を使用して構成されているため、変数 DD_AGENT_HOST、DD_TRACE_AGENT_PORT、DD_TRACE_AGENT_URL は Envoy に適用されません。

Envoy バージョン	C++ トレーサーバージョン
v1.19	v1.2.1
v1.18	v1.2.1
v1.17	v1.1.5
v1.16	v1.1.5
v1.15	v1.1.5
v1.14	v1.1.3
v1.13	v1.1.1
v1.12	v1.1.1
v1.11	v0.4.2
v1.10	v0.4.2
v1.9	v0.3.6

プラグインとコンフィギュレーションを組み合わせて使用することで、NGINX で Datadog APM に対応できます。公式 Linux レポジトリの NGINX を使用して、プラグインのバイナリを事前構築する手順を以下に記載しました。

NGINX オープンソース

プラグインのインストール

注: このプラグインは、古いバージョンの libstdc++ を使用する Linux ディストリビューションでは機能しません。これには、RHEL/Centos 7 および AmazonLinux 1 が含まれます。これの回避策は、Docker コンテナから NGINX を実行することです。Dockerfile の例がこちらにあります。

次のプラグインをインストールする必要があります。

OpenTracing 対応 NGINX プラグイン - linux-amd64-nginx-${NGINX_VERSION}-ot16-ngx_http_module.so.tgz - /usr/lib/nginx/modules にインストール
Datadog OpenTracing C++ プラグイン - linux-amd64-libdd_opentracing_plugin.so.gz - /usr/local/lib など、NGINX にアクセス可能な場所にインストール

次のコマンドを使用してモジュールをダウンロードしてインストールします。

# GitHub から最新のリリースバージョン番号を取得します。
get_latest_release() {
  wget -qO- "https://api.github.com/repos/$1/releases/latest" |
    grep '"tag_name":' |
    sed -E 's/.*"([^"]+)".*/\1/';
}
NGINX_VERSION=1.17.3
OPENTRACING_NGINX_VERSION="$(get_latest_release opentracing-contrib/nginx-opentracing)"
DD_OPENTRACING_CPP_VERSION="$(get_latest_release DataDog/dd-opentracing-cpp)"
# OpenTracing 用の NGINX プラグインをインストールします
wget https://github.com/opentracing-contrib/nginx-opentracing/releases/download/${OPENTRACING_NGINX_VERSION}/linux-amd64-nginx-${NGINX_VERSION}-ot16-ngx_http_module.so.tgz
tar zxf linux-amd64-nginx-${NGINX_VERSION}-ot16-ngx_http_module.so.tgz -C /usr/lib/nginx/modules
# Datadog Opentracing C++ プラグインをインストールします
wget https://github.com/DataDog/dd-opentracing-cpp/releases/download/${DD_OPENTRACING_CPP_VERSION}/linux-amd64-libdd_opentracing_plugin.so.gz
gunzip linux-amd64-libdd_opentracing_plugin.so.gz -c > /usr/local/lib/libdd_opentracing_plugin.so

NGINX コンフィギュレーション

OpenTracing モジュールを NGINX コンフィギュレーションに読み込む必要があります。

# OpenTracing モジュールを読み込む
load_module modules/ngx_http_opentracing_module.so;

http ブロックにより OpenTracing モジュールを有効化し、Datadog トレーサーを読み込みます。

    opentracing on; # OpenTracing を有効化
    opentracing_tag http_user_agent $http_user_agent; # 各トレースにタグを追加。
    opentracing_trace_locations off; # 各リクエストにつき 1 スパンのみ送信。

    # Datadog トレーシングの実装と既定のコンフィグファイルを読み込む。
    opentracing_load_tracer /usr/local/lib/libdd_opentracing_plugin.so /etc/nginx/dd-config.json;

log_format with_trace_id ブロックは、ログとトレースの相関関係を構築するためのものです。完全なフォーマットについては、NGINX config のサンプルファイルを参照してください。値 $opentracing_context_x_datadog_trace_id はトレース ID をキャプチャし、$opentracing_context_x_datadog_parent_id はスパン ID をキャプチャします。

トレーシングが必要なサーバー内の location ブロックに次の指示を追加します。

            opentracing_operation_name "$request_method $uri";
            opentracing_propagate_context;

Datadog トレーシングの実装コンフィグファイルには、次の指示も必要です。

{
  "environment": "prod",
  "service": "nginx",
  "operation_name_override": "nginx.handle",
  "agent_host": "localhost",
  "agent_port": 8126
}

service 値は NGINX の使用に合わせて意味のある値に変更できます。 NGINX をコンテナまたはオーケストレーション環境で使用している場合は、agent_host 値を変更する必要があります。

完成例

このコンフィギュレーションが完了すると、NGINX への HTTP リクエストが開始し Datadog トレースを伝達します。リクエストは APM UI に表示されます。

サンプリング

Datadog に送信される Nginx から始まるトレースの量を制御するには、コンフィギュレーションファイル dd-config.json で sample_rate パラメータを 0.0 (0%) から 1.0 (100%) の間の値に設定して、サンプリングレートを指定します。

{
  "environment": "prod",
  "service": "nginx",
  "agent_host": "localhost",
  "agent_port": 8126,
  "sample_rate": 0.2
}

値を指定しない場合、Datadog Agent が算出したサンプリングレート (10 トレース/秒/Agent) が適用されます。

sampling_rules 構成パラメータで、サービスごとのサンプリングレートを設定します。パラメータ sampling_limit_per_second を設定して、サービスインスタンスごとに秒あたりのトレース数を設定することで、レート制限を設定します。sampling_limit_per_second が設定されていない場合、1 秒間に 100 個のトレースという制限が適用されます。

例えば、nginx というサービスのトレースの 50% を送信するには (1 秒間に最大 50 トレース)

{
  "environment": "prod",
  "service": "nginx",
  "agent_host": "localhost",
  "agent_port": 8126,
  "sampling_rules": [{"service":"nginx", "sample_rate":0.5}],
  "sampling_limit_per_second":50
}

dd-opentracing-cpp ライブラリのサンプリング構成オプションについては、リポジトリドキュメントで詳しく説明しています。

NGINX および FastCGI

場所が HTTP ではなく FastCGI バックエンドを提供している場合、location ブロックは opentracing_propagate_context ではなく opentracing_fastcgi_propagate_context を使用する必要があります。

Kubernetes 対応 NGINX Ingress コントローラー

Kubernetes ingress-nginx コントローラーのバージョン 0.23.0 以降には、OpenTracing 対応 NGINX プラグインが含まれています。

このプラグインを有効化するには、ConfigMap を作成または編集して enable-opentracing: "true" と、トレースの送信先となる datadog-collector-host に設定します。 ConfigMap 名は nginx-ingress コントローラーコンテナのコマンドライン引数により明示的に引用し、--configmap=$(POD_NAMESPACE)/nginx-configuration をデフォルトに設定します。 ingress-nginx が Helm チャートからインストールされた場合は、この ConfigMap の名前は Release-Name-nginx-ingress-controller となります。

Ingress コントローラーは nginx.conf と /etc/nginx/opentracing.json 双方のファイルを管理します。すべての location ブロックでトレーシングが有効化されます。

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-configuration
  namespace: ingress-nginx
  labels:
    app.kubernetes.io/name: ingress-nginx
    app.kubernetes.io/part-of: ingress-nginx
data:
  enable-opentracing: "true"
  datadog-collector-host: $HOST_IP
  # デフォルト
  # datadog-service-name: "nginx"
  # datadog-collector-port: "8126"
  # datadog-operation-name-override: "nginx.handle"

また、nginx-ingress コントローラーのポッド仕様に HOST_IP 環境変数セットが含まれていることを確認してください。環境変数 POD_NAME と POD_NAMESPACE を含む env: ブロックに下記のエントリを追加します。

- name: HOST_IP
  valueFrom:
    fieldRef:
      fieldPath: status.hostIP

アノテーションを使用して Ingress ごとに異なるサービス名を設定するには

  nginx.ingress.kubernetes.io/configuration-snippet: |
            opentracing_tag "service.name" "custom-service-name";

上記はデフォルトの nginx-ingress-controller.ingress-nginx サービス名をオーバーライドします。

サンプリング

Nginx から始まるトレースのDatadogへの送信量を制御するには、パラメーター DD_TRACE_SAMPLING_RULES を 0.0 (0%) から 1.0 (100%) の間の値に設定し、サンプリングレートを指定してください。値を指定しない場合、Nginx から始まるトレースの 100% が送信されます。Kubernetes Nginx ingress controller は dd-opentracing-cpp ライブラリの v1.2.1 を使用します。

例えば、ingress-nginx サービスから始まるトレースの 10% を保持するには

DD_TRACE_SAMPLING_RULES=[{"service":"ingress-nginx","sample_rate":0.1}]

DD_TRACE_SAMPLING_RULES=[]

DD_TRACE_SAMPLING_RULES を設定するには、コントローラーの ConfigMap の data セクションに main-snippet エントリを追加します。

apiVersion: v1
kind: ConfigMap
metadata:
  labels:
      app.kubernetes.io/name: ingress-nginx
      app.kubernetes.io/instance: ingress-nginx
      app.kubernetes.io/component: controller
  name: ingress-nginx-controller
  namespace: ingress-nginx
data:
  enable-opentracing: "true"
  datadog-collector-host: $HOST_IP
  http-snippet: |
      opentracing_trace_locations off;
  main-snippet: |
      env DD_TRACE_SAMPLING_RULES=[];

Datadog は、Istio 環境のあらゆる側面を監視するため、以下を実現できます。

APM でメッシュを実行してアプリケーションの個々の分散型トレースを表示 (以下を参照)。
ログを使用して、Envoy および Istio の Control Plane の健全性を評価。
リクエスト、帯域幅、リソース消費のメトリクスでサービスメッシュのパフォーマンスを詳しく確認。
ネットワークパフォーマンスモニタリングで、コンテナ、ポッド、サービス間のネットワークコミュニケーションをメッシュ状にマッピング。

Istio 環境での Datadog の使用について、詳細は Istio のブログをご参照ください。

コンフィギュレーション

Datadog APM は Istio v1.1.3 以降のバージョンに対応しており、Kubernetes クラスター上でご利用いただけます。

Datadog Agent のインストール

Agent のインストール
Agent に APM が有効になっていることを確認します。
hostPort 設定のコメントを解除し、Istio のサイドカーが Agent に接続してトレースを送信できるようにします。

Istio のコンフィギュレーションとインストール

Datadog APM を有効にするには、Istio をカスタムインストールして、Istio のインストール時に 2 つの追加オプションを設定する必要があります。

--set values.global.proxy.tracer=datadog
--set values.pilot.traceSampling=100.0

istioctl manifest apply --set values.global.proxy.tracer=datadog --set values.pilot.traceSampling=100.0

ポッドのネームスペースでサイドカーインジェクションが有効化されると、トレースが生成されます。これを行うには istio-injection=enabled ラベルを追加する必要があります。

kubectl label namespace example-ns istio-injection=enabled

Istio で、トラフィックが HTTP ベースのプロトコルを使用していることが判断できると、トレースが生成されます。デフォルトで、Istio は自動的にこれを検出します。アプリケーションのデプロイメントおよびサービスでポートに名前を付けることで、手動で構成することも可能です。詳細は、Istio のドキュメントのプロトコルの選択をご確認ください。

デフォルトの場合、トレース作成時に用いられるサービス名はデプロイ名とネームスペースをもとに生成されます。これはデプロイのポッドテンプレートに app ラベルを追加することで手動で設定できます。

template:
  metadata:
    labels:
      app: <SERVICE_NAME>

CronJobs の場合、生成された名前がより高レベルの CronJob ではなく Job から来る場合があるため、app ラベルをジョブテンプレートに追加する必要があります

サンプリング

Istio から始まるトレースのDatadogへの送信量を制御するには、パラメーター DD_TRACE_SAMPLING_RULES を 0.0 (0%) から 1.0 (100%) の間の値に設定し、サンプリングレートを指定してください。値を指定しない場合、Istio から始まるトレースの 100% が送信されます。

DD_TRACE_SAMPLING_RULES=[]

DD_TRACE_SAMPLING_RULES を構成するには、ネームスペースが istio-injection=enabled となっている各デプロイで、デプロイ仕様テンプレートの apm.datadoghq.com/env アノテーションの一部として、環境変数を設定します。

apiVersion: apps/v1
...
kind: Deployment
...
spec:
  template:
    metadata:
      annotations:
        apm.datadoghq.com/env: '{"DD_ENV": "prod", "DD_SERVICE": "my-service", "DD_VERSION": "v1.1", "DD_TRACE_SAMPLING_RULES": "[]"}'

環境変数

Istio サイドカー用の環境変数は apm.datadoghq.com/env アノテーションを使用して、デプロイメントごとに設定することができます。これは、Istio サイドカーを採用したデプロイメントに固有のもので、統合サービスタグ付け用ラベルに加えて設定されます。

apiVersion: apps/v1
...
kind: Deployment
...
spec:
  template:
    metadata:
      annotations:
        apm.datadoghq.com/env: '{ "DD_ENV": "prod", "DD_SERVICE": "my-service", "DD_VERSION": "v1.1"}'

使用可能な環境変数は、Istio サイドカーのプロキシに埋め込まれた C++ トレーサーのバージョンによって異なります。

Istio バージョン	C++ トレーサーバージョン
v1.12.x	v1.2.1
v1.11.x	v1.2.1
v1.10.x	v1.2.1
v1.9.x	v1.2.1
v1.8.x	v1.1.5
v1.7.x	v1.1.5
v1.6.x	v1.1.3
v1.5.x	v1.1.1
v1.4.x	v1.1.1
v1.3.x	v1.1.1
v1.2.x	v0.4.2
v1.1.3	v0.4.2

デプロイおよびサービス

クラスター上の Agent がデフォルトの DaemonSet ではなくデプロイおよびサービスとして実行されている場合は、DNS アドレスと Agent のポートを指定するための追加オプションが必要です。 default ネームスペース内のサービス datadog-agent の場合、アドレスは datadog-agent.default.svc.cluster.local:8126 のようになります。

--set values.global.tracer.datadog.address=datadog-agent.default:8126

クラスターで Mutual TLS が有効化されている場合は、Agent のデプロイでサイドカーインジェクションを無効化し、TLS を無効にするトラフィックポリシーを追加する必要があります。

このアノテーションを Agent のデプロイテンプレートに追加します。

  template:
    metadata:
      annotations:
        sidecar.istio.io/inject: "false"

Istio v1.4.x の場合、トラフィックポリシーは DestinationRule を使用して構成することができます。Istio v1.5.x 以上ではトラフィックポリシーの追加は不要です。

apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
  name: datadog-agent
  namespace: istio-system
spec:
  host: datadog-agent.default.svc.cluster.local
  trafficPolicy:
    tls:
      mode: DISABLE

プロトコルの自動選択でサイドカーと Agent 間のトラフィックが HTTP であることを確認し、トレーシングを有効にすることができます。この機能は、この特定のサービスについてのプロトコルの手動選択を使用することで無効にすることが可能です。datadog-agent サービス内のポート名は tcp-traceport に変更できます。 Kubernetes 1.18+ を使用している場合は、ポートの指定に appProtocol: tcp を追加できます。