Unix ドメインソケット上の DogStatsD

バージョン 6.0 以降の Agent は、UDP 転送に代わる手段として、Unix ドメインソケット (UDS) でメトリクスを収集できるようになりました。

UDP はローカルホストではたいへんよく機能しますが、コンテナ環境でのセットアップが難しい場合があります。Unix ドメインソケットを使用すると、Datadog Agent コンテナの IP に関係なく、ソケットファイルで接続を確立できます。また、次のような利点もあります。

  • ネットワークスタックをバイパスするため、高トラフィック時のパフォーマンスが大幅に改善します。
  • UDP にはエラー処理がありませんが、UDS では Agent をノンブロッキングで使用したまま、パケットの欠落や接続エラーを検出できます。
  • DogStatsD がメトリクスの生成元のコンテナを検出し、それに応じてメトリクスにタグを付けることができます。

仕組み

IP:port ペアを使用して接続を確立する代わりに、Unix ドメインソケットは、プレースホルダーソケットファイルを使用します。いったん接続が開かれると、データは UDP と同じデータグラム形式で転送されます。Agent が再起動した場合、既存のソケットは削除され、新しいソケットに置き換わります。クライアントライブラリはこの変化を検出し、新しいソケットにシームレスに接続します。

注:

  • UDS は、その目的上、トラフィックがホスト内に制限されます。したがって、メトリクスの送信元となるそれぞれのホストで Datadog Agent を実行する必要があります。
  • UDS はWindows ではサポートされません。

セットアップ

Unix Domain Socket で DogStatsD をセットアップするには、dogstatsd_socket パラメーターを使用して DogStatsD サーバーを有効にします。次に、コードで DogStatsD クライアント を構成します。

Agent DogStatsD UDS を有効にするには

    注: Agent のインストールスクリプトは自動的に適切な権限を持つソケットファイルを作成し、use_dogstatsd: true および dogstatsd_socket: "/var/run/datadog/dsd.socket" がデフォルトで設定されています。
    1. DogStatsD がリスニングソケットとして使用するソケットファイルを作成します。例:
      sudo mkdir -p /var/run/datadog/
    2. dd-agent ユーザーにソケットファイルへの読み取り権限と書き込み権限があることを確認します。
      sudo chown dd-agent:dd-agent /var/run/datadog/
    3. Agent のメインコンフィギュレーションファイルを編集します。

      1. use_dogstatsd を true に設定します。

      2. dogstatsd_socket に DogStatsD がリスニングソケットを作成すべきパスを設定してください。

        ## @param dogstatsd_socket - string - optional - default: ""
## Listen for Dogstatsd metrics on a Unix Socket (*nix only).
## Set to a valid and existing filesystem path to enable.
#
dogstatsd_socket: "/var/run/datadog/dsd.socket"
    4. Agent を再起動します。

    1. Agent コンテナの環境変数 DD_DOGSTATSD_SOCKET=<あなたの UDS パス> でソケットパスを設定します。

    2. アプリケーションコンテナ (読み取り専用) と Agent コンテナ (読み書き) の両側でホストディレクトリをマウントし、ソケットファイルをアプリケーションコンテナへアクセスできるようにします。個別のソケットではなく親フォルダーをマウントすることで、DogStatsD が再起動してもソケット通信を維持することができます。

      • -v /var/run/datadog:/var/run/datadog で Agent コンテナを起動します。
      • -v /var/run/datadog:/var/run/datadog:ro でアプリケーションコンテナを起動します。

    1. タスク定義内で、Agent コンテナの定義にある DD_DOGSTATSD_SOCKET=<YOUR_UDS_PATH> (例: /var/run/datadog/dsd.socket) という環境変数を使用してソケットパスを設定してください。

    2. アプリケーションコンテナからソケットファイルにアクセスできるよう、Agent コンテナとアプリケーションコンテナの両方で共有ボリュームをマウントします。これにより、Datadog Agent コンテナから提供されるソケットをアプリケーションコンテナ側で利用できるようになります。

      1. タスク定義の volumes セクションで、空のフォルダをマウントします。

        "volumes": [
    {
        "name": "dsdsocket",
        "host": {}
    }
],

      2. Agent コンテナの mountPoints セクションでソケットフォルダをマウントします。

        "mountPoints": [
    {
    "containerPath": "/var/run/datadog",
    "sourceVolume": "dsdsocket"
    }
],

      3. アプリケーションコンテナの mountPoints セクションで、同じフォルダをアプリケーションコンテナ内に公開します。

        アプリケーションコンテナがソケットへの書き込み権限を必要とする場合は、"readOnly": true を削除してください。
        "mountPoints": [
    {
    "containerPath": "/var/run/datadog",
    "sourceVolume": "dsdsocket",
    "readOnly": true
    }
],

    1. Agent コンテナの環境変数 DD_DOGSTATSD_SOCKET=<YOUR_UDS_PATH> でソケットパスを設定します (例: /var/run/datadog/dsd.socket)。

    2. アプリケーションコンテナ (読み取り専用) と Agent コンテナ (読み書き) の両側でホストディレクトリをマウントし、ソケットファイルをアプリケーションコンテナへアクセスできるようにします。個別のソケットではなく親フォルダーをマウントすることで、DogStatsD が再起動してもソケット通信を維持することができます。

      1. datadog-agent コンテナでソケットフォルダーをマウントします。

        volumeMounts:
    - name: dsdsocket
      mountPath: /var/run/datadog
    ##...
volumes:
    - hostPath:
          path: /var/run/datadog/
      name: dsdsocket

      2. 同じフォルダーをアプリケーションコンテナで公開します。

        アプリケーションコンテナがソケットへの書き込み権限を必要とする場合は、"readOnly": true を削除してください。
        volumeMounts:
    - name: dsdsocket
      mountPath: /var/run/datadog
      readOnly: true
    ## ...
volumes:
    - hostPath:
          path: /var/run/datadog/
      name: dsdsocket

    1. Agent コンテナの環境変数 DD_DOGSTATSD_SOCKET=<YOUR_UDS_PATH> でソケットパスを設定します (例: /var/run/datadog/dsd.socket)。

    2. アプリケーションコンテナ (読み取り専用) と Agent コンテナ (読み書き) の両側で空のディレクトリをマウントし、ソケットファイルをアプリケーションコンテナへアクセスできるようにします。個別のソケットではなく親フォルダーをマウントすることで、DogStatsD が再起動してもソケット通信を維持することができます。

      1. Pod spec に空のフォルダーをマウントします。

        volumes:
    - emptyDir: {}
      name: dsdsocket

      2. datadog-agent コンテナでソケットフォルダーをマウントします。

        volumeMounts:
    - name: dsdsocket
      mountPath: /var/run/datadog

      3. 同じフォルダーをアプリケーションコンテナで公開します。

        アプリケーションコンテナがソケットへの書き込み権限を必要とする場合は、"readOnly": true を削除してください。
        volumeMounts:
    - name: dsdsocket
      mountPath: /var/run/datadog
      readOnly: true

    netcat でテスト

    シェルスクリプトからメトリクスを送信したり、DogStatsD がソケットでリスニングしているかをテストする場合は、netcat を使用します。netcat のほとんどの実装 (Debian の netcat-openbsd、RHEL の nmap-ncat など) は、-U フラグで Unix ソケットトラフィックをサポートしています。

    echo -n "custom.metric.name:1|c" | nc -U -u -w1 /var/run/datadog/dsd.socket

    発信点検出

    発信点検出により、DogStatsD はコンテナメトリクスとタグメトリクスがどこから発信されたかを自動的に検出します。このモードが有効な場合は、UDS で受信されたすべてのメトリクスがオートディスカバリーメトリクスと同じコンテナタグに基づいてタグ付けされます。

      1. Agent のメイン構成ファイルで dogstatsd_origin_detection オプションを有効にします。

        ## @param dogstatsd_origin_detection - boolean - optional - default: false
## When using Unix Socket, DogStatsD can tag metrics
## with container metadata. If running DogStatsD in a container,
## host PID mode (for example, with --pid=host) is required.
#
dogstatsd_origin_detection: true

      2. 任意 - 発信点検出を使用して収集されたメトリクスにタグカーディナリティを設定するには、パラメーター dogstatsd_tag_cardinality に low (デフォルト)、orchestrator、または high を使用します。

        ## @param dogstatsd_tag_cardinality - string - optional - default: low
## Configure the level of granularity of tags to send for DogStatsD
## metrics and events. Choices are:
##   * low: add tags about low-cardinality objects
##     (clusters, hosts, deployments, container images, ...)
##   * orchestrator: add tags about pods (Kubernetes),
##     or tasks (ECS or Mesos) -level of cardinality
##   * high: add tags about high-cardinality objects
##     (individual containers, user IDs in requests, etc.)
##
## WARNING: Sending container tags for DogStatsD metrics may create
## more metrics (one per container instead of one per host).
## This may impact your custom metrics billing.
#
dogstatsd_tag_cardinality: low

      3. Agent を再起動します。

      1. Agent コンテナの環境変数 DD_DOGSTATSD_ORIGIN_DETECTION=true を設定します。

      2. 任意 - 発信点検出を使用して収集されたメトリクスに[タグカーディナリティ][5]を設定するには、環境変数 DD_DOGSTATSD_TAG_CARDINALITY に low (デフォルト)、orchestrator、または high を使用します。

      DogStatsD がコンテナ内で実行されている場合、発信点検出を高い信頼性で行うには、DogStatsD をホストの PID ネームスペースで実行する必要があります。そのため、--pid=host フラグを用いて Docker で有効にします。注: これは、コンテナのタスク定義内の "pidMode": "host" パラメーターを使用して、ECS によってサポートされます。このオプションは、Fargate ではサポートされません。詳細については、PID モードで AWS のドキュメントを参照してください。

      1. タスク定義内で、Agent コンテナの定義に DD_DOGSTATSD_ORIGIN_DETECTION 環境変数を true として設定します。

        {
    "name": "DD_DOGSTATSD_ORIGIN_DETECTION",
    "value": "true"
},

      2. タスク定義に PidMode パラメータを追加し、次のように task に設定します。

        "pidMode": "task"

      3. 任意 - 発信点検出を使用して収集されたメトリクスにタグカーディナリティを設定するには、環境変数 DD_DOGSTATSD_TAG_CARDINALITY に low (デフォルト)、orchestrator、または high を使用します。

        {
    "name": "DD_DOGSTATSD_TAG_CARDINALITY",
    "value": "low"
},

      1. Agent コンテナの環境変数 `DD_DOGSTATSD_ORIGIN_DETECTION を true に設定します。

        # (...)
env:
    # (...)
    - name: DD_DOGSTATSD_ORIGIN_DETECTION
      value: 'true'

      2. ポッドテンプレートの仕様に hostPID: true を設定します。

        # (...)
spec:
    # (...)
    hostPID: true

      3. 任意 - 発信点検出を使用して収集されたメトリクスにタグカーディナリティを設定するには、環境変数 DD_DOGSTATSD_TAG_CARDINALITY に low (デフォルト)、orchestrator、または high を使用します。

        # (...)
env:
    # (...)
    - name: DD_DOGSTATSD_TAG_CARDINALITY
      value: 'low'

      1. Agent コンテナの環境変数 `DD_DOGSTATSD_ORIGIN_DETECTION を true に設定します。

        # (...)
env:
    # (...)
    - name: DD_DOGSTATSD_ORIGIN_DETECTION
      value: 'true'

      2. ポッドテンプレートの仕様で、shareProcessNamespace: true を設定します。

        # (...)
spec:
    # (...)
    shareProcessNamespace: true

      3. 任意 - 発信点検出を使用して収集されたメトリクスにタグカーディナリティを設定するには、環境変数 DD_DOGSTATSD_TAG_CARDINALITY に low (デフォルト)、orchestrator、または high を使用します。

        # (...)
env:
    # (...)
    - name: DD_DOGSTATSD_TAG_CARDINALITY
      value: 'low'

      注: container_id、container_name、pod_name タグは、カスタムメトリクスが多くなりすぎないようにデフォルトでは追加されていません。

      DogStatsD クライアントコンフィギュレーション

      クライアントライブラリ

      以下の DogStatsD クライアントライブラリは、UDS トラフィックをネイティブでサポートします。UDS トラフィックを有効にする方法については、各ライブラリのドキュメントを参照してください。注: UDP と同様に、トラフィックが多い場合は、パフォーマンスを向上させるため、クライアント側のバッファリングを有効にすることをお勧めします。

      言語ライブラリ
      GolangDataDog/datadog-go
      JavaDataDog/java-dogstatsd-client
      PythonDataDog/datadogpy
      RubyDataDog/dogstatsd-ruby
      PHPDataDog/php-datadogstatsd
      C#DataDog/dogstatsd-csharp-client

      socat プロキシ

      アプリケーションまたはクライアントライブラリが UDS トラフィックをサポートしていない場合は、socat を実行して UDP ポート 8125 でリスニングし、リクエストをソケットにプロキシすることができます。

      socat -s -u UDP-RECV:8125 UNIX-SENDTO:/var/run/datadog/dsd.socket

      追加の実装オプションの作成に関するガイドラインについては、datadog-agent GitHub wiki を参照してください。

      参考資料

      お役に立つドキュメント、リンクや記事:

      DogStatsD 入門DOCUMENTATION more more 公式/コミュニティ作成の API および DogStatsD クライアントライブラリDOCUMENTATION more more