OpenTelemetry コレクター Datadog エクスポーター

OpenTelemetry Collector は、あらゆるベンダーに対応するエージェントプロセスで、さまざまなプロセスにより送信されたテレメトリデータを収集、エクスポートします。Datadog には、OpenTelemetry Collector で使える Exporter があり、OpenTelemetry SDK から Datadog にトレースやメトリクスデータを転送することができます (Datadog Agent は不要です)。すべての対応言語で動作するほか、これらの OpenTelemetry トレースデータをアプリケーションログに接続することができます。

アプリケーションインスツルメンテーションライブラリ、クラウドインテグレーション、その他のモニタリングソリューション (Prometheus など) -> OTel コレクター内の Datadog エクスポーター -> Datadog

コレクターの実行

Datadog Exporter と一緒に OpenTelemetry Collector を実行するには

  1. OpenTelemetry Collector Contribute の最新リリースをプロジェクトのリポジトリからダウンロードします。

  2. コンフィグレーションファイルを作成し、collector.yaml という名前をつけます。以下の Datadog Exporter の構成のサンプルファイルを使用します。

  3. コンフィグレーションファイルを --config パラメータで指定し、コレクターを実行します。

    otelcontribcol_linux_amd64 --config collector.yaml
    

Datadog Exporter の構成

Datadog Exporter を使用するには、OpenTelemetry Collector の構成に追加します。以下は、環境変数 DD_API_KEY に Datadog API キーを設定した後、すぐに利用できる基本的なコンフィグレーションファイルです。

receivers:
  otlp:
    protocols:
      http:
      grpc:
  # Datadog で正しいインフラストラクチャーのメトリクスを取得するためには、hostmetrics レシーバーが必要です。
  hostmetrics:
    collection_interval: 10s
    scrapers:
      paging:
        metrics:
          system.paging.utilization:
            enabled: true
      cpu:
        metrics:
          system.cpu.utilization:
            enabled: true
      disk:
      filesystem:
        metrics:
          system.filesystem.utilization:
            enabled: true
      load:
      memory:
      network:
      processes:
  # prometheus レシーバーは、OpenTelemetry Collector Dashboard に必要なメトリクスをスクレイピングします。
  prometheus:
    config:
      scrape_configs:
      - job_name: 'otelcol'
        scrape_interval: 10s
        static_configs:
        - targets: ['0.0.0.0:8888']

processors:
  batch:
    # Datadog APM Intake の上限は 3.2MB です。バッチがそれを超えないように
    # しましょう。
    send_batch_max_size: 1000
    send_batch_size: 100
    timeout: 10s

exporters:
  datadog:
    api:
      site: 
      key: ${DD_API_KEY}

service:
  pipelines:
    metrics:
      receivers: [hostmetrics, otlp]
      processors: [batch]
      exporters: [datadog]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [datadog]

上記の構成により、OpenTelemetry のインスツルメンテーションライブラリから HTTP と gRPC で OTLP データを受信できるようになり、非開発環境では必須のバッチ処理が設定されます。

高度なコンフィギュレーション

Datadog Exporter の構成オプションは、このドキュメントにあるコンフィギュレーションファイルの例で説明されています。デプロイメントに関連する他のオプション、例えば api::sitehost_metadata セクションにあるものがあるかもしれません。

ホスト名解決

OpenTelemetry シグナルがタグ付けされるホスト名は、以下のソースを基に順番に取得され、現在のソースが利用できないか無効な場合は、次のソースにフォールバックされます。

  1. リソース属性から、例えば host.name (他の多くの属性もサポートされています)。
  2. エクスポーターの構成にある hostname フィールド。
  3. クラウドプロバイダー API。
  4. Kubernetes のホスト名。
  5. 完全修飾ドメイン名。
  6. オペレーティングシステムのホスト名。

アプリケーションの構成

トレースのメタデータを充実させ、Datadog とのインテグレーションを円滑に行うには

  • リソース検出システムを使用する: 言語 SDK で提供されている場合、コンテナ情報をリソース属性としてアタッチします。例えば、Go の場合、WithContainer() リソースオプションを使用します。

  • **統合サービスタグ付け**を適用する: これは、Datadog のテレメトリーを、サービス名、デプロイ環境、サービスバージョンなどのタグで結びつけます。アプリケーションはこれらのタグを OpenTelemetry のセマンティック規則 (service.namedeployment.environmentservice.version) を使用して設定する必要があります。

Docker を使用する

Opentelemetry Collector コンテナを実行し、ローカルホスト、またはその他のコンテナからトレースを受信します。

ローカルホストからトレースを受信する

OpenTelemetry Collector を Docker イメージとして実行し、同じホストからトレースを受信するには

  1. collector.yaml ファイルを作成します。上のテンプレート例を参考にするとよいでしょう。

  2. otel/opentelemetry-collector-contrib などの公開された Docker イメージを選択します。

  3. OpenTelemetry のトレースを OpenTelemetry Collector に送信するために、コンテナ上でどのポートをオープンするかを決定します。デフォルトでは、トレースはポート 4317 の gRPC で送信されます。gRPC を使用しない場合は、ポート 4138 を使用します。

  4. コンテナを実行し、事前に定義した collector.yaml ファイルを使用して、必要なポートを公開します。例えば、ポート 4317 を使用する場合を考えてみましょう。

    $ docker run \
        -p 4317:4317 \
        --hostname $(hostname) \
        -v $(pwd)/otel_collector_config.yaml:/etc/otelcol-contrib/config.yaml \
        otel/opentelemetry-collector-contrib
    
  5. 統合サービスタグ付けに適切なリソース属性がアプリケーションに構成されていることを確認してください。

その他のコンテナからトレースを受信

OpenTelemetry Collector を Docker イメージとして実行し、その他のコンテナからトレースを受信するには

  1. collector.yaml ファイルを作成します。上のテンプレート例を参考にするとよいでしょう。

  2. 統合サービスタグ付けに適切なリソース属性がアプリケーションに構成されていることを確認してください。

  3. Docker ネットワークを作成します。

    docker network create <NETWORK_NAME>
    
  4. OpenTelemetry Collector とアプリケーションコンテナを同じネットワークの一部として実行します。

    # Run the OpenTelemetry Collector
    docker run -d --name opentelemetry-collector \
        --network <NETWORK_NAME> \
        --hostname $(hostname) \
        -v $(pwd)/otel_collector_config.yaml:/etc/otelcol-contrib/config.yaml \
        otel/opentelemetry-collector-contrib
    

    アプリケーションコンテナの実行中は、環境変数 OTEL_EXPORTER_OTLP_ENDPOINT が OpenTelemetry Collector 向けの適切なホスト名を使用して構成されていることをご確認ください。以下の例では opentelemetry-collector を使用しています。

    # Run the application container
    docker run -d --name app \
        --network <NETWORK_NAME> \
        --hostname $(hostname) \
        -e OTEL_EXPORTER_OTLP_ENDPOINT=http://opentelemetry-collector:4317 \
        company/app:latest
    

Kubernetes を使用する

Kubernetes インフラクチャーに OpenTelemetry Collector と Datadog Exporter をデプロイする方法は複数存在します。最も一般的で推奨される方法は、Daemonset を使用する方法です。

DaemonSet のデプロイメント

アプリケーションの構成例も含め、こちらの Datadog Exporter を DaemonSet として使用した OpenTelemetry Collector の全構成例をご確認ください。

特に、DaemonSet の重要なポートがアプリケーションに公開され、アクセスできることを保証する、いくつかの例からの重要な構成オプションに注意してください。

# ...
        ports:
        - containerPort: 4318 # OpenTelemetry HTTP レシーバーのデフォルトポート。
          hostPort: 4318
        - containerPort: 4317 # OpenTelemetry gRPC レシーバーのデフォルトポート。
          hostPort: 4317
        - containerPort: 8888  # Collector の観測可能性メトリクスをクエリするためのデフォルトのエンドポイント。
# ...

もし、アプリケーションに標準の HTTP ポートと gRPC ポートの両方が必要ない場合は、削除しても問題ありません。

Datadog コンテナのタグ付けに使用される貴重な Kubernetes 属性を収集するために、Pod IP をリソース属性として報告します。そのためには、例に示すように:

# ...
        env:
        - name: POD_IP
          valueFrom:
            fieldRef:
              fieldPath: status.podIP
        # k8s.pod.ip は、k8sattributes のポッドを関連付けるために使用されます
        - name: OTEL_RESOURCE_ATTRIBUTES
          value: "k8s.pod.ip=$(POD_IP)"
# ...

これにより、構成マップで使用される Kubernetes Attributes Processor が、トレースにアタッチするために必要なメタデータを抽出することができるようになるのです。このメタデータにアクセスできるようにするために、追加で設定する必要のあるロールが存在します。

この例は完全で、すぐに使用でき、正しいロールが設定されています。必要なのは、アプリケーションコンテナを提供することだけです。

アプリケーションの構成については、以下のアプリケーションの構成セクションをお読みください。

ゲートウェイコレクターサービス

ゲートウェイのデプロイの場合

  1. DaemonSet のデプロイと同様に、各 OpenTelemetry Collector Agent をセットアップします。

  2. DaemonSet に現在設置されている Datadog Exporter の代わりに OTLP エクスポーターを含めるように変更します。

    # ...
    exporters:
      otlp:
        endpoint: "<GATEWAY_HOSTNAME>:4317"
    # ...
    
  3. サービスパイプラインが、サンプルにある Datadog のものでなく、このエクスポーターを使用することを確認してください。

    # ...
        service:
          pipelines:
            metrics:
              receivers: [hostmetrics, otlp]
              processors: [resourcedetection, k8sattributes, batch]
              exporters: [otlp]
            traces:
              receivers: [otlp]
              processors: [resourcedetection, k8sattributes, batch]
              exporters: [otlp]
    # ...
    

    これにより、各 Agent は OTLP プロトコルを介して Collector Gateway にデータを転送することが保証されます。

  4. GATEWAY_HOSTNAME を OpenTelemetry Collector Gateway のアドレスに置き換えます。

  5. Kubernetes のメタデータがトレースに適用され続けるようにするには、k8sattributes プロセッサー に Pod IP を Gateway Collector に転送して、メタデータを取得できるようにします。

    # ...
    k8sattributes:
      passthrough: true
    # ...
    

    passthrough オプションの詳細については、そのドキュメントを参照してください。

  6. Gateway Collector の構成が、Agent で OTLP エクスポーターに置き換わったのと同じ Datadog Exporter 設定を使用していることを確認します。例えば、以下のようになります。

    # ...
    exporters:
      datadog:
        api:
          site: 
          key: ${DD_API_KEY}
    # ...
    

Kubernetes 用 OpenTelemetry Operator

OpenTelemetry Operator を使用するには

  1. OpenTelemetry Operator のデプロイメントに関する公式ドキュメントに従ってください。そこに記載されているように、Operator に加えて、証明書マネージャをデプロイします。

  2. OpenTelemetry Collector の標準構成の 1 つを使用して Operator を構成します。

    例:

    apiVersion: opentelemetry.io/v1alpha1
    kind: OpenTelemetryCollector
    metadata:
      name: opentelemetry-example
    spec:
      mode: daemonset
      hostNetwork: true
      image: otel/opentelemetry-collector-contrib
      env:
        - name: DD_API_KEY
          valueFrom:
            secretKeyRef:
              key:  datadog_api_key
              name: opentelemetry-example-otelcol-dd-secret
    
      config: |
        receivers:
          otlp:
            protocols:
              grpc:
              http:
        hostmetrics:
          collection_interval: 10s
          scrapers:
            paging:
              metrics:
                system.paging.utilization:
                  enabled: true
            cpu:
              metrics:
                system.cpu.utilization:
                  enabled: true
            disk:
            filesystem:
              metrics:
                system.filesystem.utilization:
                  enabled: true
            load:
            memory:
            network:
        processors:
          k8sattributes:
          batch:
            # Datadog APM Intake limit is 3.2MB. Let's make sure the batches do not
            # go over that.
            send_batch_max_size: 1000
            send_batch_size: 100
            timeout: 10s
        exporters:
          datadog:
            api:
              key: ${DD_API_KEY}
        service:
          pipelines:
            metrics:
              receivers: [hostmetrics, otlp]
              processors: [k8sattributes, batch]
              exporters: [datadog]
            traces:
              receivers: [otlp]
              processors: [k8sattributes, batch]
              exporters: [datadog]    
    

アプリケーションの構成

アプリケーションコンテナを構成するには

  1. 正しい OTLP エンドポイントのホスト名が使用されていることを確認します。OpenTelemetry Collector は Agentゲートウェイの両方のデプロイメントで DaemonSet として動作するので、現在のホストをターゲットにする必要があります。アプリケーションコンテナの OTEL_EXPORTER_OTLP_ENDPOINT 環境変数を、サンプル図 のように正しく設定してください。

    # ...
            env:
            - name: HOST_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.hostIP
              # The application SDK must use this environment variable in order to successfully
              # connect to the DaemonSet's collector.
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "http://$(HOST_IP):4318"
    # ...
    
  2. アプリケーションの構成の説明に従って、OpenTelemetry Instrumentation Library SDK が正しく構成されていることを確認します。

Datadog Agent と並行して

Datadog Agent と並行して OpenTelemetry Collector を使用するには

  1. 先に設定した OpenTelmetry Collector DaemonSet と並行して Datadog Agent が各ホストで実行されるように、追加の DaemonSet を設定します。詳細は、Kubernetes での Datadog Agent のデプロイに関するドキュメントをお読みください。

  2. Datadog Agent での OTLP 取り込みを有効にします。

  3. Datadog Agent が OTLP トレースとメトリクスを受信できるようになったので、OpenTelemetry Collector Daemonset を変更して Datadog Exporter ではなく、OTLP エクスポーターを使用するように変更します。これを行うには、構成マップに追加します。

    # ...
    exporters:
      otlp:
        endpoint: "${HOST_IP}:4317"
    # ...
    
  4. DaemonSet で環境変数 HOST_IP が提供されていることを確認します。

    # ...
            env:
            - name: HOST_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.hostIP
    # ...
    
  5. サービスパイプラインが OTLP を使用していることを確認します。

    # ...
        service:
          pipelines:
            metrics:
              receivers: [otlp]
              processors: [resourcedetection, k8sattributes, batch]
              exporters: [otlp]
            traces:
              receivers: [otlp]
              processors: [resourcedetection, k8sattributes, batch]
              exporters: [otlp]
    # ...
    

    この場合、Datadog Agent によってこれらのメトリクスが発行されるため、hostmetrics レシーバーを使用しないでください。