データグラム形式とシェルの使用方法

<METRIC_NAME>:<VALUE>|<TYPE>|@<SAMPLE_RATE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

以下に、データグラムの例を示します。

• page.views:1|c : page.views COUNT メトリクスを増やします。
• fuel.level:0.5|g: 燃料タンクが半分空になったことを記録します。
• song.length:240|h|@0.5: 半分の時間だけ送信したように song.length ヒストグラムをサンプリングします。
• users.uniques:1234|s: サイトへのユニークビジターを追跡します。
• users.online:1|c|#country:china: アクティブユーザー COUNT メトリクスを増やし、所属国ごとにタグ付けします。
• users.online:1|c|@0.5|#country:china: アクティブな中国ユーザーを追跡し、サンプルレートを使用します。

DogStatsD プロトコル v1.1

Agent >=v6.25.0 && <v7.0.0 または >=v7.25.0 からは、値のパッキングが可能になります。これは、 SET を除くすべてのメトリクスタイプでサポートされています。値は : で区切られ、例えば次のようになります。

<METRIC_NAME>:<VALUE1>:<VALUE2>:<VALUE3>|<TYPE>|@<SAMPLE_RATE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

TYPE、SAMPLE_RATE、TAGS はすべての値で共有されます。これは、それぞれ 1 つの値で複数のメッセージを送信するよりも、同じメトリクスを生成します。これは、HISTOGRAM、TIMING、DISTRIBUTION の各メトリクスに有効です。

データグラムの例

• page.views:1:2:32|d: page.views DISTRIBUTION メトリクスを 1、2、32 の値で 3 回サンプリングします。
• song.length:240:234|h|@0.5: song.length ヒストグラムを、半分の時間を 2 回送信したかのようにサンプリングします。それぞれの値には 0.5 のサンプルレートが適用されます。

DogStatsD プロトコル v1.2

Agent >=v6.35.0 および <v7.0.0 または >=v7.35.0 からは、新しいコンテナ ID フィールドがサポートされています。 Datadog Agent は、コンテナ ID の値を使用して、追加のコンテナタグで DogStatsD メトリクスをリッチ化します。

コンテナ ID の先頭には c: が付きます。例:

<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|c:<CONTAINER_ID>

注: datadog.yaml ファイルまたは環境変数 DD_DOGSTATSD_ORIGIN_DETECTION_CLIENT=true で dogstatsd_origin_detection_client を true に設定すると、Datadog Agent にコンテナ ID フィールドを抽出して、対応するコンテナタグをアタッチするように指示が出ます。

データグラムの例

• page.views:1|g|#env:dev|c:83c0a99c0a54c0c187f461c7980e9b57f3f6a8b0c918c8d93df19a9de6f3fe1d: Datadog Agent は、image_name や image_tag などのコンテナタグを page.views メトリクスに追加します。

コンテナタグについては、Kubernetes と Docker のタグ付けのドキュメントをご覧ください。

DogStatsD プロトコル v1.3

Agent v6.40.0+ および v7.40.0+ は、オプションで Unix タイムスタンプフィールドをサポートしています。

このフィールドを指定すると、Datadog Agent は、タグでメトリクスをリッチ化する以外、メトリクスの処理を行いません (集計を行いません)。これは、アプリケーションで既にメトリクスを集計しており、余分な処理なしで Datadog に送信したい場合に便利です。

Unix のタイムスタンプは、過去の有効な正の数である必要があります。GAUGE と COUNT メトリクスのみサポートされています。

値は Unix タイムスタンプ (UTC) であり、プレフィックスとして T を付ける必要があります。例:

<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|T<METRIC_TIMESTAMP>

データグラムの例

• page.views:15|c|#env:dev|T1656581400: 2022 年 6 月 30 日午前 9 時 30 分 (UTC) に 15 ページビューが発生したことを示す COUNT

_e{<TITLE_UTF8_LENGTH>,<TEXT_UTF8_LENGTH>}:<TITLE>|<TEXT>|d:<TIMESTAMP>|h:<HOSTNAME>|p:<PRIORITY>|t:<ALERT_TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

以下に、データグラムの例を示します。

## 例外を送信する
_e{21,36}:An exception occurred|Cannot parse CSV file from 10.0.0.17|t:warning|#err_type:bad_file

## テキスト内に改行を含むイベントを送信する
_e{21,42}:An exception occurred|Cannot parse JSON request:\\n{"foo: "bar"}|p:low|#err_type:bad_request

_sc|<NAME>|<STATUS>|d:<TIMESTAMP>|h:<HOSTNAME>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|m:<SERVICE_CHECK_MESSAGE>

以下に、データグラムの例を示します。

# リモート接続の CRITICAL ステータスを送信する
_sc|Redis connection|2|#env:dev|m:Redis connection timed out after 10s

メトリクスの送信に使用される形式は以下のとおりです。

<メトリクス名>:<値>|<タイプ>|@<サンプリングレート>|#<タグキー_1>:<タグ値_1>,<タグ_2>

以下の例では、shell タグを使用して custom_metric というゲージメトリクスのデータポイントを送信します。

Linux の場合

echo -n "custom_metric:60|g|#shell" >/dev/udp/localhost/8125

echo -n "custom_metric:60|g|#shell" | nc -4u -w0 127.0.0.1 8125

echo -n "custom.metric.name:1|c"|nc -4u -w1 localhost 8125

Windows の場合

PS C:\> .\send-statsd.ps1 "custom_metric:123|g|#shell"

任意のプラットフォームで Python を使用する場合 (Windows では、Agent の埋め込み Python インタープリターを使用できます。これは、Agent バージョン <= 6.11 の場合は %ProgramFiles%\Datadog\Datadog Agent\embedded\python.exe、Agent バージョン >= 6.12 の場合は %ProgramFiles%\Datadog\Datadog Agent\embedded<PYTHON_MAJOR_VERSION>\python.exe にあります。)

Python 2

import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) # UDP
sock.sendto("custom_metric:60|g|#shell", ("localhost", 8125))

Python 3

import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) # UDP
sock.sendto(b"custom_metric:60|g|#shell", ("localhost", 8125))

イベントの送信に使用される形式は以下のとおりです。

_e{<タイトル>.length,<テキスト>.length}:<タイトル>|<テキスト>|d:<日付イベント>|h:<ホスト名>|p:<優先度>|t:<アラートタイプ>|#<タグキー_1>:<タグ値_1>,<タグ_2>.

以下の例では、イベントのタイトルと本文のサイズを計算しています。

Linux の場合

$ title="シェルからのイベント"

$ text="これは Bash から送信されました！"

$ echo "_e{${#title},${#text}}:$title|$text|#shell,bash"  >/dev/udp/localhost/8125

Windows の場合

PS C:> $title = "シェルからのイベント"
PS C:> $text = "これは PowerShell から送信されました！"
PS C:> .\send-statsd.ps1 "_e{$($title.length),$($text.Length)}:$title|$text|#shell,PowerShell"

サービスチェックの送信に使用される形式は以下のとおりです。

_sc|<名前>|<ステータス>|d:<タイムスタンプ>|h:<ホスト名>|#<タグキー_1>:<タグ値_1>|m:<サービスチェックメッセージ>

Linux の場合

echo -n "_sc|Redis 接続|2|#env:dev|m:Redis 接続が 10 秒後にタイムアウトしました" >/dev/udp/localhost/8125

Windows の場合

PS C:\> .\send-statsd.ps1 "_sc|Redis 接続|2|#env:dev|m:Redis 接続が 10 秒後にタイムアウトしました"