DogStatsD

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

UDS の仕組み

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

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

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

セットアップ

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_TRAFFICtrue に設定する必要があります。DogStatsd サーバーを起動した状態で Agent を実行するには、次のコマンドを実行します。

docker run -d -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 を構成することもできます。

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

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

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

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

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

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

    - 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 では、属性を割り当てる際のベストプラクティスとして、統合サービスタグ付けを使用することをおすすめしています。統合サービスタグ付けは、envserviceversion の 3 つの標準タグを使用して Datadog テレメトリーと結合します。環境を統合する方法については、[統合サービスタグ付け][8]ドキュメントをご参照ください。

UDP 発信点検出

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

: UDP 以外には Unix ドメインソケットがあります。

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

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

発信点検出を使用して収集されたメトリクスにタグカーディナリティを設定するには、環境変数 DD_DOGSTATSD_TAG_CARDINALITYlow (デフォルト) または 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 パラメーターを指定すると、ホストのポートが開かれます。アプリケーションまたは信頼できるソースからのみアクセスを許可するように、ファイアウォールを設定してください。その他の注意: 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 に送信_できます_が、上記の Datadog 固有の機能を使用することはできません。

pip install datadog
gem install dogstatsd-ruby
go get github.com/DataDog/datadog-go/statsd

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

<dependency>
    <groupId>com.datadoghq</groupId>
    <artifactId>java-dogstatsd-client</artifactId>
    <version>2.10.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)
# ライブラリをインポートします
require 'datadog/statsd'

# DogStatsD クライアントインスタンスを作成します。
statsd = Datadog::Statsd.new('localhost', 8125)
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();

    }
}

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())
{
    dogStatsdService.Configure(dogstatsdConfig);
    // ...
} // 未送信のメトリクスをフラッシュします

: コンテナ Agent または Kubernetes で DogStatsD を使用する場合、Unix ドメインソケットを使用している場合は $DD_DOGSTATSD_SOCKET 環境変数を、ホストポートバインディング方式を使用している場合は $DD_AGENT_HOST 環境変数を使用して、StatsD メトリクスの転送先のホストをインスタンス化する必要があります。

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

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

必須の DogStatsD 構成(urlport)に加えて、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 すべてのメトリクス、イベント、サービスチェックのプレフィックスになるネームスペース。

詳細については、DogStatsD モジュールのドキュメントを参照してください。

パラメーター タイプ デフォルト 説明
host 文字列 localhost DogStatsD サーバーのホスト。
port 整数 8125 DogStatsD サーバーのポート。
socket_path 文字列 null DogStatsD Unix ドメインソケットへのパス(hostport をオーバーライドします。Agent v6 以上でのみサポートされます)。
tags 文字列のリスト null すべてのメトリクス、イベント、サービスチェックに適用するタグ。
namespace 文字列 null すべてのメトリクス、イベント、サービスチェックの前に付けるネームスペース。
パラメーター タイプ 説明
Namespace 文字列 すべてのメトリクス、イベント、サービスチェックの前に付けるネームスペース。
Tags 文字列のリスト すべてのメトリクス、イベント、サービスチェックに適用されるグローバルタグ。
Buffered Boolean 1 つのペイロードに複数の DogStatsD メッセージをパックするために使用されます。true に設定すると、ペイロードの合計サイズが MaxMessagesPerPayload またはペイロードの構築開始から 100ms を超えるまでメッセージがバッファリングされます。
MaxMessagesPerPayload 整数 単一のペイロードに含めることができるメトリクス、イベント、サービスチェックの最大数。このオプションは、クライアントがバッファリングされている場合にのみ有効です。
WriteTimeoutUDS 整数 UDS パケットがドロップされるまでのタイムアウト。

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

パラメーター タイプ 説明
prefix 文字列 すべてのメトリクス、イベント、サービスチェックに適用するプレフィックス。
hostname 文字列 ターゲット StatsD サーバーのホスト名。
port 整数 ターゲット StatsD サーバーのポート。
constantTags 文字列のリスト すべてのメトリクス、イベント、サービスチェックに適用されるグローバルタグ。

詳細については、NonBlockingStatsDClient クラスのドキュメントを参照してください。

パラメーター タイプ デフォルト 説明
host 文字列 localhost DogStatsD サーバーのホスト。これが設定されていない場合、Agent は DD_AGENT_HOST 環境変数を調べます。
port 整数 8125 DogStatsD サーバーのポート。これが設定されていない場合、Agent は DD_DOGSTATSD_PORT 環境変数を調べます。
socket_path 文字列 null DogStatsD Unix ドメインソケットへのパス(hostport をオーバーライドします)。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 ライブラリを開発したい場合は、データグラムとシェルの使用を参照してください。ここでは、メトリクスとイベントをコマンドラインから直接送信する方法についても説明しています。