DogStatsD

Docs > 開発者 > DogStatsD

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

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

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

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

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

Docker Hub	GCR
hub.docker.com/r/datadog/dogstatsd	gcr.io/datadoghq/dogstatsd

Docker Hub にはイメージのプルレート制限があります。Docker Hub をご利用でない場合は、Datadog Agent および Cluster Agent の構成を更新して、GCR または ECR からプルすることをお勧めします。手順については、コンテナレジストリの変更を参照してください。

仕組み

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

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

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

セットアップ

DogStatsD は、Datadog Agent にバンドルされているサーバーと、複数の言語で利用可能なクライアントライブラリで構成されています。Agent v6+ では、DogStatsD サーバーは UDP ポート 8125 上でデフォルトで有効化されています。必要に応じて、サーバーのポートをカスタマイズすることができます。Datadog Agent DogStatsD サーバーのアドレスとポートに合わせてクライアントを設定してください。

Datadog Agent DogStatsD サーバー

ポートを変更する必要がある場合は、メインの Agent コンフィギュレーションファイルで dogstatsd_port オプションを構成し、Agent を再起動してください。また、UNIX ドメインソケットを使用するように DogStatsD を構成することもできます。

独自の Agent DogStatsD サーバーの UDP ポートを有効にするには:

dogstatsd_port パラメーターを設定します。

## @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

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="<NEW_DOGSTATSD_PORT> 環境変数を使用します。UNIX ドメインソケットを使用するように DogStatsD を構成することもできます。

UDP 発信点検出

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

Docker には以下のタグが追加されます。請求においてはカーディナリティが重要な概念であることに注意してください。

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

既定では、すべての DogStatsD クライアントで発信点検出が有効になっていますが、Datadog Agent では既定で有効になっていません。クライアントで発信点検出を無効化するには、使用している特定の DogStatsD ライブラリのドキュメントを参照してください。

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

StatsD メトリクス収集は、デフォルトで UNIX ドメインソケットで有効になっています。UDP 経由で StatsD メトリクスの収集を開始するには、Operator 設定で DogStatsD 機能を有効にする必要があります。

features.dogstatsd.hostPortConfig.enabled を datadog-agent.yaml マニフェストに追加します。

features:     dogstatsd:         hostPortConfig:             enabled: true

これは datadog-agent.yaml マニフェストの例です。

apiVersion: datadoghq.com/v2alpha1 kind: DatadogAgent metadata:   name: datadog spec:   global:     credentials:       apiSecret:         secretName: datadog-secret         keyName: api-key   features:     dogstatsd:       hostPortConfig:         enabled: true

これにより Agent は、ポート 8125 の UDP 経由で StatsD メトリクスを収集できるようになります。

変更を適用します。
```
kubectl apply -f datadog-agent.yaml 
```

警告: features.dogstatsd.hostPortConfig.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 で受信されたすべてのメトリクスがオートディスカバリーメトリクスと同じポッドタグに基づいてタグ付けされます。

Kubernetes には以下のタグが追加されます。請求においてはカーディナリティが重要な概念であることに注意してください。

送信元検出を有効にするには、global.originDetectionUnified.enabled設定を datadog-agent.yaml マニフェストに追加します。
```
global:     originDetectionUnified:         enabled: true 
```

注:

UDP 以外には UNIX ドメインソケットがあります。
UDP による送信元検出では、エンティティ ID としてポッド ID を使うことができます。

エンティティ ID としてポッド ID を使用するには、アプリケーションマニフェストに次の行を追加します。

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

送信元検出を使用して収集されたメトリクスにタグのカーディナリティを設定するには、features.dogstatsd.tagCardinality の設定を low (デフォルト)、orchestrator、high のいずれかに設定します。

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

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

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 インストールもあります。
Agent コンフィギュレーションをアップグレードする:
```
helm upgrade -f datadog-values.yaml <RELEASE_NAME> datadog/datadog 
```
アプリケーションポッドの更新: アプリケーションには、ホストの IP アドレスを判断するための信頼できる方法が必要です。これは、Kubernetes 1.7 では簡単です。環境変数としてポッドに渡すことができる属性のセットを拡張します。バージョン 1.7 以上では、環境変数を PodSpec に追加することで、ホスト IP を任意のポッドに渡すことができます。たとえば、アプリケーションマニフェストは次のようになります。
```
env:     - name: DD_AGENT_HOST       valueFrom:           fieldRef:               fieldPath: status.hostIP 
```
これにより、アプリケーションを実行しているポッドは、$DD_AGENT_HOST のポート 8125 から DogStatsD メトリクスを送信できるようになります。

DogStatsD クライアント

使用するプログラミング言語向けの DogStatsD クライアントライブラリをインストールし、Datadog Agent 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.6.*"

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

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

Nuget CLI を使用してパッケージを直接インストールするか、NuGet から PackageReference を取得します。

dotnet add package DogStatsD-CSharp-Client

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`	文字列	`localhost`	DogStatsD サーバーのホスト。
`statsd_port`	整数	`8125`	DogStatsD サーバーのポート。
`statsd_socket_path`	文字列	`null`	DogStatsD UNIX ドメインソケットへのパス (`host` および `port` を上書き。Agent v6 以降のみに対応)。
`statsd_constant_tags`	文字列のリスト	`null`	すべてのメトリクス、イベント、サービスチェックに適用するタグ。
`statsd_namespace`	文字列	`null`	すべてのメトリクス、イベント、サービスチェックのプレフィックスになるネームスペース。

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

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

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

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

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

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

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

ビルダーメソッド	タイプ	Default	Description
`prefix(String val)`	文字列	null	すべてのメトリクス、イベント、サービスチェックに適用するプレフィックス。
`hostname(String val)`	文字列	localhost	ターゲット StatsD サーバーのホスト名。
`port(int val)`	整数	8125	ターゲット StatsD サーバーのポート。
`constantTags(String... val)`	String varargs	null	すべてのメトリクス、イベント、サービスチェックに適用されるグローバルタグ。
`blocking(boolean val)`	Boolean	false	インスタンス化するクライアントのタイプ: ブロッキングか非ブロッキングか。
`socketBufferSize(int val)`	整数	-1	基礎となるソケットバッファのサイズ。
`enableTelemetry(boolean val)`	Boolean	false	クライアントテレメトリーレポート。
`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 を検索してください。クライアントのリリースと一致するバージョンを表示するようにしてください。

パラメータータイプDefaultDescription
host文字列localhostDogStatsD サーバーのホスト。これが設定されていない場合、Agent は DD_AGENT_HOST または DD_DOGSTATSD_URL 環境変数を調べます。
port整数8125DogStatsD サーバーのポート。これが設定されていない場合、Agent は DD_DOGSTATSD_PORT または DD_DOGSTATSD_URL 環境変数を調べます。
socket_path文字列nullDogStatsD UNIX ドメインソケットへのパス (host と port をオーバーライドします)。Agent v6 以上でのみサポートされます。これが設定されていない場合、Agent は DD_DOGSTATSD_URL 環境変数を調べます。
global_tags文字列のリストnullすべてのメトリクス、イベント、サービスチェックに適用するタグ。@dd.internal.entity_id タグは、DD_ENTITY_ID 環境変数から global_tags に追加されます。

パラメーター	タイプ	Default	Description
`host`	文字列	`localhost`	DogStatsD サーバーのホスト。これが設定されていない場合、Agent は `DD_AGENT_HOST` または `DD_DOGSTATSD_URL` 環境変数を調べます。
`port`	整数	`8125`	DogStatsD サーバーのポート。これが設定されていない場合、Agent は `DD_DOGSTATSD_PORT` または `DD_DOGSTATSD_URL` 環境変数を調べます。
`socket_path`	文字列	`null`	DogStatsD UNIX ドメインソケットへのパス (`host` と `port` をオーバーライドします)。Agent v6 以上でのみサポートされます。これが設定されていない場合、Agent は `DD_DOGSTATSD_URL` 環境変数を調べます。
`global_tags`	文字列のリスト	`null`	すべてのメトリクス、イベント、サービスチェックに適用するタグ。`@dd.internal.entity_id` タグは、`DD_ENTITY_ID` 環境変数から global_tags に追加されます。

パラメータータイプDefaultDescription
StatsdServerName文字列localhostターゲット StatsD サーバーのホスト名。
StatsdPort整数8125ターゲット StatsD サーバーのポート。
Prefix文字列nullすべてのメトリクス、イベント、サービスチェックに適用するプレフィックス。
ConstantTags文字列のリストnullすべてのメトリクス、イベント、サービスチェックに適用されるグローバルタグ。

パラメーター	タイプ	Default	Description
`StatsdServerName`	文字列	`localhost`	ターゲット StatsD サーバーのホスト名。
`StatsdPort`	整数	`8125`	ターゲット StatsD サーバーのポート。
`Prefix`	文字列	`null`	すべてのメトリクス、イベント、サービスチェックに適用するプレフィックス。
`ConstantTags`	文字列のリスト	`null`	すべてのメトリクス、イベント、サービスチェックに適用されるグローバルタグ。