DogStatsD

DogStatsD は、Datadog Agent に付属するメトリクス集計サービスです。カスタムアプリケーションメトリクスを最も簡単に Datadog に取り込むには、メトリクスを DogStatsD に送信します。DogStatsD は StatsD プロトコルを実装すると共に、Datadog 固有の以下の拡張機能を提供します。

  • ヒストグラムメトリクスタイプ
  • サービスチェック
  • イベント
  • タグ付け

準拠する StatsD クライアントは、DogStatsD および Agent で動作しますが、その場合、Datadog 固有の拡張機能は含まれません。

注: DogStatsD は、StatsD のタイマーをネイティブメトリクスタイプとして実装しません（ただし、ヒストグラム経由でサポートします）。

DogStatsD は、Docker Hub と GCR で利用できます。

Docker HubGCR
hub.docker.com/r/datadog/dogstatsdgcr.io/datadoghq/dogstatsd
2023 年 7 月 10 日、Docker Hub は Datadog の Docker Hub レジストリへのダウンロードレート制限を実施するようになります。これらのレジストリからのイメージのプルは、レート制限割り当てにカウントされます。

Datadog は、Datadog Agent と Cluster Agent の構成を更新して、レート制限が適用されない他のレジストリからプルすることを推奨しています。手順については、コンテナレジストリを変更するを参照してください。

UDS の仕組み

DogStatsD は、UDP 経由でカスタムメトリクス、イベント、およびサービスチェックを受け入れ、それらを定期的に集計して Datadog に転送します。

UDP を使用するため、アプリケーションはメトリクスを DogStatsD に送信した後、応答を待たずに自身の作業を再開できます。DogStatsD を利用できなくなった場合でも、アプリケーションは中断しません。

dogstatsd

DogStatsD は、データを受け取ると共に、_フラッシュ間隔_と呼ばれる時間間隔でメトリクスごとに複数のデータポイントを 1 つのデータポイントに集計します。DogStatsD はフラッシュ間隔を 10 秒としています。

セットアップ

DogStatsD は、Agent v6 以上の UDP ポート 8125 でデフォルトで有効になっています。このポートを変更する必要がない場合は、コードで DogStatsD をセットアップする方法を直接参照してください。

エージェント

    デフォルトでは、DogStatsD は UDP ポート 8125 をリスニングします。これを変更する必要がある場合は、Agent のメイン構成ファイルで dogstatsd_port オプションを構成し、Agent を再起動します。Unix ドメインソケットを使用するように DogStatsD を構成することもできます。カスタム Agent DogStatsD サーバーの UDP ポートを有効にするには:

    1. datadog.yaml ファイルを編集して、use_dogstatsd および dogstatsd_port パラメーターのコメントを解除します。

      ## @param use_dogstatsd - boolean - optional - default: true
## Set this option to false to disable the Agent DogStatsD server.
#
use_dogstatsd: true

## @param dogstatsd_port - integer - optional - default: 8125
## Override the Agent DogStatsD port.
## Note: Make sure your client is sending to the same UDP port.
#
dogstatsd_port: 8125

    2. Agent を再起動します。

    デフォルトでは、DogStatsD は UDP ポート 8125 でリッスンするため、コンテナで Agent を実行する場合、このポートをホストポートにバインドする必要があります。StatsD メトリクスが localhost の外部から取得される場合、メトリクスの収集を許可するには、DD_DOGSTATSD_NON_LOCAL_TRAFFIC を true に設定する必要があります。DogStatsd サーバーを起動した状態で Agent を実行するには、次のコマンドを実行します。

    docker run -d --cgroupns host \
              --pid host \
              -v /var/run/docker.sock:/var/run/docker.sock:ro \
              -v /proc/:/host/proc/:ro \
              -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
              -e DD_API_KEY=<DATADOG_API_KEY> \
              -e DD_DOGSTATSD_NON_LOCAL_TRAFFIC="true" \
              -p 8125:8125/udp \
              gcr.io/datadoghq/agent:latest

    StatsD メトリクスの収集に使用するポートを変更する必要がある場合は、DD_DOGSTATSD_PORT="<新しい_DOGSTATSD_ポート> 環境変数を使用します。Unix ドメインソケットを使用するように DogStatsD を構成することもできます。

    UDP 発信点検出

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

    Kubernetes 以外の環境での発信点検出は、Datagram Format and Shell Usage の DogStatsD プロトコルの拡張機能に基づきます。Agent でこの機能を有効にするには、DD_DOGSTATSD_ORIGIN_DETECTION_CLIENT 環境変数を true に設定します。

    注: Fargate 環境では、発信点検出はサポートされていません。

    StatsD メトリクスの収集を開始するには、DogStatsD ポートをホストポートにバインドする必要があります。Unix ドメインソケットを使用するように DogStatsD を構成することもできます。

    1. hostPort を datadog-agent.yaml マニフェストに追加します。

      ports:
    - containerPort: 8125
      hostPort: 8125
      name: dogstatsdport
      protocol: UDP

      これによりアプリケーションは、実行中のノードのポート 8125 で DogStatsD でメトリクスを送信できるようになります。

      注: hostPort 機能には、Calico、Canal、Flannel などの CNI 仕様に準拠したネットワークプロバイダーが必要です。非 CNI ネットワークプロバイダーの回避策を含む詳細については、Kubernetes のドキュメントを参照してください: HostPort サービスが機能しない。

      注: Operator をデプロイする場合は、agent.config.hostPort でホストポートを構成してください。

    2. DogStatsD 非ローカルトラフィックを有効にして StatsD データ収集を許可し、datadog-agent.yaml マニフェストで DD_DOGSTATSD_NON_LOCAL_TRAFFIC を true に設定します。

      - name: DD_DOGSTATSD_NON_LOCAL_TRAFFIC
  value: 'true'

      これにより、Agent を実行しているコンテナ以外のコンテナから StatsD データを収集できます。

    3. 変更を適用します。

      kubectl apply -f datadog-agent.yaml

    警告: hostPort パラメーターを指定すると、ホストのポートが開かれます。アプリケーションまたは信頼できるソースからのみアクセスを許可するように、ファイアウォールを設定してください。ネットワークプラグインが hostPorts をサポートしていない場合は、hostNetwork: true を Agent ポッド仕様に追加してください。ホストのネットワークネームスペースが Datadog Agent と共有されます。つまり、コンテナで開かれたすべてのポートはホストで開きます。ポートがホストとコンテナの両方で使用されると、競合し (同じネットワークネームスペースを共有するので)、ポッドが開始しません。これを許可しない Kubernetes インストールもあります。

    StatsD メトリクスを Agent に送信する

    アプリケーションには、ホストの IP アドレスを判断するための信頼できる方法を必要です。これは、Kubernetes 1.7 では簡単です。環境変数としてポッドに渡すことができる属性のセットを拡張します。バージョン 1.7 以上では、環境変数を PodSpec に追加することで、ホスト IP を任意のポッドに渡すことができます。たとえば、アプリケーション マニフェストは次のようになります。

    env:
    - name: DD_AGENT_HOST
      valueFrom:
          fieldRef:
              fieldPath: status.hostIP

    これにより、アプリケーションを実行しているポッドは、$DD_AGENT_HOST のポート 8125 で DogStatsD メトリクスを送信できるようになります。

    注: Datadog では、属性を割り当てる際のベストプラクティスとして、統合サービスタグ付けを使用することをおすすめしています。統合サービスタグ付けは、env、service、version の 3 つの標準タグを使用して Datadog テレメトリーと結合します。環境を統合する方法については、統合サービスタグ付けをご参照ください。

    UDP 発信点検出

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

    注:

    • UDP による発信点検出では、ポッド ID をエンティティ ID として使用するため、コンテナレベルのタグは発行されません。
    • UDP 以外には Unix ドメインソケットがあります。

    UDP 経由の発信点検出を有効にするには、アプリケーションマニフェストに次の行を追加します。

    env:
    - name: DD_ENTITY_ID
      valueFrom:
          fieldRef:
              fieldPath: metadata.uid

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

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

    DogStatsD で、helm を使用してカスタムメトリクスを収集するには:

    1. datadog-values.yaml ファイルを更新して DogStatsD を有効にします。

        dogstatsd:
    port: 8125
    useHostPort: true
    nonLocalTraffic: true

      注: hostPort 機能には、Calico、Canal、Flannel などの CNI 仕様に準拠したネットワークプロバイダーが必要です。非 CNI ネットワークプロバイダーの回避策を含む詳細については、Kubernetes のドキュメントを参照してください: HostPort サービスが機能しない。

      警告: hostPort パラメーターを指定すると、ホストのポートが開かれます。アプリケーションまたは信頼できるソースからのみアクセスを許可するように、ファイアウォールを設定してください。ネットワークプラグインが hostPorts をサポートしていない場合は、hostNetwork: true を Agent ポッド仕様に追加してください。ホストのネットワークネームスペースが Datadog Agent と共有されます。つまり、コンテナで開かれたすべてのポートはホストで開きます。ポートがホストとコンテナの両方で使用されると、競合し (同じネットワークネームスペースを共有するので)、ポッドが開始しません。これを許可しない Kubernetes インストールもあります。

    2. Agent コンフィギュレーションをアップグレードする:

      helm upgrade -f datadog-values.yaml <RELEASE_NAME> datadog/datadog

    3. アプリケーションポッドの更新: アプリケーションには、ホストの IP アドレスを判断するための信頼できる方法が必要です。これは、Kubernetes 1.7 では簡単です。環境変数としてポッドに渡すことができる属性のセットを拡張します。バージョン 1.7 以上では、環境変数を PodSpec に追加することで、ホスト IP を任意のポッドに渡すことができます。たとえば、アプリケーションマニフェストは次のようになります。

      env:
    - name: DD_AGENT_HOST
      valueFrom:
          fieldRef:
              fieldPath: status.hostIP

      これにより、アプリケーションを実行しているポッドは、$DD_AGENT_HOST のポート 8125 から DogStatsD メトリクスを送信できるようになります。

    コード

    DogStatsD クライアントをインストールする

    公式の Datadog-DogStatsD クライアントライブラリは、次の言語で使用できます。準拠する StatsD クライアントは DogStatsD および Agent で動作しますが、上記の Datadog 固有の機能は含まれていません。

    pip install datadog

    gem install dogstatsd-ruby

    go get github.com/DataDog/datadog-go/v5/statsd

    Java DataDog StatsD Client は maven central とともに配布され、Maven からダウンロードできます。まず、pom.xml に以下の構成を追加します。

    <dependency>
    <groupId>com.datadoghq</groupId>
    <artifactId>java-dogstatsd-client</artifactId>
    <version>4.2.1</version>
</dependency>

    composer.json に以下を追加します。

    "datadog/php-datadogstatsd": "1.4.*"

    注: Composer に付属している最初のバージョンは 0.0.3 です。

    または、github.com/DataDog/php-datadogstatsd でリポジトリを手動でクローンし、require './src/DogStatsd.php' でセットアップします。

    DogStatsD クライアントをインスタンス化する

    DogStatsD クライアントをインストールしたら、コードでインスタンス化します。

    from datadog import initialize, statsd

options = {
    'statsd_host':'127.0.0.1',
    'statsd_port':8125
}

initialize(**options)
    デフォルトでは、Python DogStatsD クライアントインスタンス (statsd グローバルインスタンスを含む) はプロセス間で共有できませんが、スレッドセーフです。このため、親プロセスと各子プロセスは、クライアントの独自のインスタンスを作成するか、disable_buffering を True に設定してバッファリングを明示的に無効にする必要があります。詳細については、datadog.dogstatsd のドキュメントを参照してください。
    # ライブラリをインポートします
require 'datadog/statsd'

# DogStatsD クライアントインスタンスを作成します。
statsd = Datadog::Statsd.new('localhost', 8125)
    コンテナ Agent または Kubernetes で DogStatsD を使用する場合、Unix ドメインソケットを使用している場合は $DD_DOGSTATSD_SOCKET 環境変数を、ホストポートバインディング方式を使用している場合は $DD_AGENT_HOST 環境変数を使用して、StatsD メトリクスの転送先のホストをインスタンス化する必要があります。
    dogstatsd_client, err := statsd.New("127.0.0.1:8125")
if err != nil {
    log.Fatal(err)
}

    その他のオプションについては、Datadog の GoDoc を参照してください。

    import com.timgroup.statsd.NonBlockingStatsDClientBuilder;
import com.timgroup.statsd.StatsDClient;

public class DogStatsdClient {

    public static void main(String[] args) throws Exception {

        StatsDClient statsd = new NonBlockingStatsDClientBuilder()
            .prefix("statsd")
            .hostname("localhost")
            .port(8125)
            .build();


        // または
        StatsDClient statsdAlt = new NonBlockingStatsDClient(
            new NonBlockingStatsDClientBuilder(
                .prefix("statsd")
                .hostname("localhost")
                .port(8125)
                .resolve()));

    }
}

    composer を使用して、新しい DogStatsd オブジェクトをインスタンス化します。

    <?php

require __DIR__ . '/vendor/autoload.php';

use DataDog\DogStatsd;

$statsd = new DogStatsd(
    array('host' => '127.0.0.1',
          'port' => 8125,
     )
  );

    DogStatsd クラスを構成します。

    // コードは StatsdClient ネームスペースの下にあります
using StatsdClient;

// ...

var dogstatsdConfig = new StatsdConfig
{
    StatsdServerName = "127.0.0.1",
    StatsdPort = 8125,
};

using (var dogStatsdService = new DogStatsdService())
{
    if (!dogStatsdService.Configure(dogstatsdConfig))
        throw new InvalidOperationException("Cannot initialize DogstatsD. Set optionalExceptionHandler argument in the `Configure` method for more information.");
    // ...
} // 未送信のメトリクスをフラッシュします

    クライアントのインスタンス化パラメーター

    注: Datadog では、タグを割り当てる際のベストプラクティスとして、統合サービスタグ付けを使用することをおすすめしています。統合サービスタグ付けは、env、service、version の 3 つの標準タグを使用して Datadog テレメトリーと結合します。環境を統合する方法については、統合サービスタグ付けをご参照ください。

    必須の DogStatsD 構成（url と port）に加えて、DogStatsD クライアントでは次のオプションのパラメーターを使用できます。

    パラメータータイプデフォルト説明
    statsd_host文字列localhostDogStatsD サーバーのホスト。
    statsd_port整数8125DogStatsD サーバーのポート。
    statsd_socket_path文字列nullDogStatsD Unix ドメインソケットへのパス (host および port を上書き。Agent v6 以降のみに対応)。
    statsd_constant_tags文字列のリストnullすべてのメトリクス、イベント、サービスチェックに適用するタグ。
    statsd_namespace文字列nullすべてのメトリクス、イベント、サービスチェックのプレフィックスになるネームスペース。

    datadog.initialize() で使用できるオプションのパラメーターと、datadog.dogstatsd.DogStatsd インスタンスを明示的にインスタンス化する場合にのみ使用できるパラメーターの完全なリストについては、Datadog Python ライブラリを参照してください。

    パラメータータイプデフォルト説明
    host文字列localhostDogStatsD サーバーのホスト。
    port整数8125DogStatsD サーバーのポート。
    socket_path文字列nullDogStatsD Unix ドメインソケットへのパス（host と port をオーバーライドします。Agent v6 以上でのみサポートされます）。
    tags文字列のリストnullすべてのメトリクス、イベント、サービスチェックに適用するタグ。
    namespace文字列nullすべてのメトリクス、イベント、サービスチェックの前に付けるネームスペース。
    single_threadBooleanfalseコンパニオンスレッドではなく、有効になっている場合、クライアントがメインスレッドでメトリクスを送信するようにします。

    オプションのパラメーターの完全なリストについては、GitHub の dogstatsd-ruby リポジトリを参照してください。

    Go クライアントには、クライアントの動作を設定するための複数のオプションがあります。

    パラメータータイプ説明
    WithNamespace()文字列すべてのメトリクス、イベント、サービスチェックの前に付けるネームスペースを構成します。
    WithTags()文字列のリストすべてのメトリクス、イベント、サービスチェックに適用されるグローバルタグ。

    利用可能なすべてのオプションについては、Datadog の GoDoc を参照してください。

    v2.10.0 以降では、NonBlockingStatsDClientBuilder を使ってクライアントをインスタンス化することを推奨します。以下のビルダーメソッドを使用して、クライアントのパラメータを定義することができます。

    ビルダーメソッドタイプデフォルト説明
    prefix(String val)文字列nullすべてのメトリクス、イベント、サービスチェックに適用するプレフィックス。
    hostname(String val)文字列localhostターゲット StatsD サーバーのホスト名。
    port(int val)整数8125ターゲット StatsD サーバーのポート。
    constantTags(String... val)String varargsnullすべてのメトリクス、イベント、サービスチェックに適用されるグローバルタグ。
    blocking(boolean val)Booleanfalseインスタンス化するクライアントのタイプ: ブロッキングか非ブロッキングか。
    socketBufferSize(int val)整数-1基礎となるソケットバッファのサイズ。
    enableTelemetry(boolean val)Booleanfalseクライアントテレメトリーレポート。
    entityID(String val)文字列null発信点検出のためのエンティティ ID。
    errorHandler(StatsDClientErrorHandler val)整数nullクライアント内部でエラーが発生した場合のエラーハンドラー。
    maxPacketSizeBytes(int val)整数8192/1432最大パケットサイズ、UDS で 8192、UDP で 1432。
    processorWorkers(int val)整数1送信のためにバッファを組み立てているプロセッサーワーカスレッドの数。
    senderWorkers(int val)整数1ソケットにバッファを送信している送信側ワーカスレッドの数。
    poolSize(int val)整数512ネットワークパケットバッファプールのサイズ。
    queueSize(int val)整数4096キュー内の未処理メッセージの最大数。
    timeout(int val)整数100ブロック操作のタイムアウト (ミリ秒単位)。unix ソケットにのみ適用されます。

    詳細は、Java DogStatsD パッケージの NonBlockingStatsDClient Class と NonBlockingStatsDClientBuilder Class を検索してください。クライアントのリリースと一致するバージョンを表示するようにしてください。

    パラメータータイプデフォルト説明
    host文字列localhostDogStatsD サーバーのホスト。これが設定されていない場合、Agent は DD_AGENT_HOST 環境変数を調べます。
    port整数8125DogStatsD サーバーのポート。これが設定されていない場合、Agent は DD_DOGSTATSD_PORT 環境変数を調べます。
    socket_path文字列nullDogStatsD Unix ドメインソケットへのパス（host と port をオーバーライドします）。Agent v6 以上でのみサポートされます。
    global_tags文字列のリストnullすべてのメトリクス、イベント、サービスチェックに適用するタグ。@dd.internal.entity_id タグは、DD_ENTITY_ID 環境変数から global_tags に追加されます。
    パラメータータイプデフォルト説明
    StatsdServerName文字列localhostターゲット StatsD サーバーのホスト名。
    StatsdPort整数8125ターゲット StatsD サーバーのポート。
    Prefix文字列nullすべてのメトリクス、イベント、サービスチェックに適用するプレフィックス。
    ConstantTags文字列のリストnullすべてのメトリクス、イベント、サービスチェックに適用されるグローバルタグ。

    DogStatsD の理解

    DogStatsD と StatsD はほぼ同じですが、DogStatsD には、使用可能なデータ型、イベント、サービスチェック、タグなど、Datadog に固有の高度な機能が含まれています。

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


    DogStatsD が使用するデータグラム形式についてさらに理解を深めたい場合、または独自の Datadog ライブラリを開発したい場合は、データグラムとシェルの使用を参照してください。ここでは、メトリクスとイベントをコマンドラインから直接送信する方法についても説明しています。

    その他の参考資料

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

    DogStatsD 入門ドキュメント more more 公式/コミュニティ作成の API および DogStatsD クライアントライブラリドキュメント more more DogStatsD ソースコードGITHUB more more Datadog で Azure App Service 上の Linux Web アプリを監視するブログ more more