DogStatsDの解説

このチュートリアルでは、開発しているアプリケーションからDatadogへカスタムメトリクスを送信する方法を順を追って説明していきます。チュートリアルを読み進めていく上でサポートが必要な場合は、お問い合わせページで紹介している方法でご連絡ください。

Datadogにカスタムメトリクスを取り込ませる最も簡単な方法はDogStatsDを使うことです。DogStatsDは、Datadog Agent 3.0以上に同胞されているメトリクス集約サーバです。DogStatsDは、StatsDプロトコルをサポートすると共に、datadog専用の機能にも対応するよう拡張されています。

どのように動作するの

DogStatsDは、アプリケーションのカスタムメトリクスをUDPを使って受信し、集計した後、グラフ化表示のために定期的にDatadog側に送信します。

次に図は、DogStatsDを使ったカスタムメトリクスのグラフ化までの構成図です:

集計

DogSt​​atsDの主な機能は、所定の時間間隔(デフォルトでは10秒)に発生するデータポイントの情報を、単一のメトリクスに集計/集約することです。それでは、これがどのように機能するかを理解するための例を見てみましょう。

例えば、データベースクエリを実行している回数を知りたいと仮定します。アプリケーションは、クエリが実行される度に、DogStatsDに対しカウンタを進めることを支持します。

次のようになります:

def query_my_database():
    dog.increment('database.query.count')
    # Run the query ...

この関数が、次のメトリクス送信タイミング(デフォルトでは10秒間隔)までに100回実行されたとします。この関数は、100個の、”‘database.query.count’を、カウント”というUDPパケットを送信します。 DogStatsDは、これらのUDPパケットが送られたデータポイントを集計し、メトリクス値に置き換えます。 今回のケースでは、100ということになります。その上で、Datadog側に送信し、ダッシュボードでグラフ表示に備えます。

このようにすることにより、計測対象のデータが不規則に発生している状態でも、メトリクス送信タイミングの間隔ごとに一つのメトリクスと値のセットを生成することを保証しています。

なぜUDPなのですか。

StatsDと同様にDogSt​​atsDは、UDPを使って計測ポイント情報を受け取ります。UDPは、パケットの到達を管理していないのでアプリケーションの計測には最適です。パケットの到達を管理しないということは、アプリケーションがメトリクスサーバからの応答を待って、実行中の作業を停止し待機状態になる必要がないということです。パッケットの応答を待つ状態がないということは、メトリクスサーバが停止している時やそれにアクセスできない事態が発生した際に実行中のアプリケーションに影響を与えないという観点では、非常に有効です。

セットアップ

既にDatadog Agentが起動し動作しているなら、開発に使用しているプログラミング言語に対応したDogSt​​atsDクライアントをインストールすれば、準備完了です。もちろん、一般的なStatsDクライアントでも問題なく動作します。しかし、DogStatsDクライアントを利用すれば、いくつかの追加機能(例: tags、histogramsなど)が使えるようになります。

DogStatsDクライアントについて

プログラミング言語ごとのDogStatsDクライアントに関しては、ライブラリーページを参照してください。

メトリクス

Pythonを使ってDogStatsDがサポートしているメトリクスのタイプを解説してきます。ここで解説する内容は、他のプログラミング言語でも同様に適用することができます。

DogStatsDは、次のメトリクスタイプに対応しています:

Gauges (ゲージ)

車両のガソリンタンク内の燃料量やシステムに接続しているユーザーの数などゲージは、ある時間の対象物の値を測定します。

dog.gauge('gas_tank.level', 0.75)
dog.gauge('users.active', 1001)

Counters (カウンタ)

データベースへのリクエストやページビューのようにカウンタは、毎秒の発生回数を追跡します。

dog.increment('database.query.count')
dog.increment('page_view.count', 10)

Histograms (ヒストグラム)

データベースへのクエリ実行時間やユーザーによってアップロードされたファイルのサイズなどの集計数のように、ヒストグラムは、値の集合の度数分布を追跡します。各ヒストグラムは、平均値、最小値、最大値、中央値及び95パーセンタイルを追跡します。

dog.histogram('database.query.time', 0.5)
dog.histogram('file.upload.size', file.get_size())

ヒストグラムは、StatsDの拡張です。この機能が必要な場合は、DogStatsDクライアントを使用する必要があります。

Sets (セット)

セットは、グループ内のユニークな要素の数をカウントするために使用します。サイトへのユニークビジター数を追跡したい場合は、セットが最も適しています。

dog.set('users.uniques', user.id)

セットは、StatsDの拡張です。この機能が必要な場合は、DogStatsDクライアントを使用する必要があります。

Timers (タイマー)

StatsDの度数分布は、一般的な値(アップロードされたファイルのサイズやクエリから返される行数など)には対応しておらず、時間計測のみにしか使うことができません。時間計測は、度数分布の特殊のケースであり、後方互換のためにDogStatsDでも同じように扱うようになっています。

サンプルレート

高いパフォーマンスを求められるプリグラムコードの部分では、UDPパケットを送信する部分は大きな負荷になることがあります。この問題を回避するために、DogStatsDクライアントは、サンプルレートの変更をサポートしています。これは、メトリクスの一定割合を指定し、送信回数を削減するとことです。

例えば:

dog.histogram('my.histogram', 1, sample_rate=0.5)

この例では、実際の半分のデータポイントのデータをDogStatsDサーバに送信するよいうになります。しかし、メトリクスの生成には、受信値をサンプルレートの逆数倍し、実際の値の推定するようになっています。

タグ

タグは、Datadogでのみで使うことができるStatsDへの拡張です。タグは、メトリクスの分類に多面性を持たせ、多種多彩な切り口でのグラフ表示を可能にします。例えば、異なる2つのビデオレンダリングアルゴリズムの性能を測定したい場合は、アルゴリズムのバージョンをメトリクスにタグ付けして識別することができます。

タグは、StatsDの拡張です。この機能が必要な場合は、DogStatsDクライアントを使用する必要があります。

# Randomly choose which rendering function we want to use ...
if random() < 0.5:
    renderer = old_slow_renderer
    version = 'old'
else:
    renderer = new_shiny_renderer
    version = 'new'

start_time = time()
renderer()
duration = time() - start_time
dog.histogram('rendering.duration', tags=[version])

イベント

イベントストリームに、イベントを投稿することができます。更に、それらのイベントにタグ付けし、優先順位を設定し、又たのイベントと集約することできます。

必須フィールド

  • title (String) — イベントのタイトル。
  • text (String) — イベントテキスト。改行をサポートしています。

イベントは、イベントストリーム上で次の分類によって集約されます:

‘hostname/event_type/source_type/aggregation_key’

event_typeに情報がない場合、そのイベントは、他のevent_typeが空のイベントとグループ化されます。

# Post a simple message
statsd.event('There might be a storm tomorrow', 'A friend warned me earlier.')

# Cry for help
statsd.event('SO MUCH SNOW', 'The city is paralyzed!', alert_type='error', tags=['urgent', 'endoftheworld'])

設定項目

  • 必須項目:
    • title (String) — イベントのタイトル。
    • text (String) — イベントテキスト。改行をサポートしています。
  • オプション項目:
    • date_happened (Time, None) — default: None — イベントにタイムスタンプを付けます。
    • hostname (String, None) — default: None — イベントにホスト名を付けます。
    • aggregation_key (String, None) — default: None — 他のイベントとグループ分けするために集約用のキーを付けます。
    • priority (String, None) — default: ‘normal’ — ‘normal’ または ‘low’を指定します。
    • source_type_name (String, None) — default: None — イベントにソースタイプを付けます。
    • alert_type (String, None) — default: ‘info’ — ‘error’, ‘warning’, ‘info’, ‘success’のどれかを指定します。
    • tags - (Array[str], None) — default: None — タグのリストを付けます。

設定

DogStatsDでは、UDPパケットの受信ポートとメトリクスの送信間隔をDatadog Agentの設定ファイル内で設定することができます。

# The port DogStatsD runs on. If you change this, make your the apps sending to
# it change as well.
dogstatsd_port: 8125

# The number of seconds to wait between flushes to the server.
dogstatsd_interval: 10

データグラム

メトリクス

独自の方法でDogSt​​atsDにメトリクスを送信したい場合は、以下がパケットのフォーマットになります:

metric.name:value|type|@sample_rate|#tag1:value,tag2

以下は各フィールドの概要:

  • metric.name “:“, “-”, “@” 以外の文字列。
  • value 数字。
  • 集約タイプの指定は、cはCounter, gはGauge, hはHistogram, msはTimer, sはSet.
  • サンプルレートは、オプション指定項目です。 指定する場合は、0~1 の浮動小数点数になります。
  • タグは、オプション指定項目です。タグとタグの間位には”,“が入ります。キーバリューがセットのタグについては、”:“を開いただに挟みます。

次は、データグラムのサンプルとその内容の解説です:

# ページビューのカウンタのインクリメント指示を送信
page.views:1|c

# 自動車の燃料タンクの状況が半分になっている計測結果を送信
fuel.level:0.5|g

# 発生回数の半分の機会に、歌の時間を計測結果を送信
song.length:240|h|@0.5

# サイトへのユニークビジター数の追跡のために、ユーザーIDを送信
users.uniques:1234|s

# 国に基づくオンラインユーザーの数をカウントするためのインクリメント指示を送信
users.online:1|c|#country:china

# 上記のすべてのコンセプトを取り込んだデータグラムの例
users.online:1|c|@0.5|#country:china

イベント

独自の方法でDogSt​​atsDにイベントを送信したい場合は、以下がパケットのフォーマットになります:

_e{title.length,text.length}:title|text|d:date_happened|h:hostname|p:priority|t:alert_type|#tag1,tag2

設定項目

  • 必須項目:
    • title — イベントのタイトルを指定できます。
    • text — イベントテキストを指定できます。改行をサポートしています。
  • オプション項目: |[key]:[value]
    • |d:date_happened — default: None — イベントにタイムスタンプを指定できます。オプションへの設定がない場合は、現在のUNIX時間が付けられます。
    • |h:hostname — default: None — イベントにホスト名を指定できます。
    • |k:aggregation_key — default: None — 他のイベントとグループ分けするために集約用のキーを指定できます。
    • |p:priority — default: ‘normal’ — ‘normal’ または ‘low’を指定できます。
    • |s:source_type_name — default: None — イベントにソースタイプを指定します。
    • |t:alert_type — default: ‘info’ — ‘error’, ‘warning’, ‘info’, ‘success’が指定できます。
    • |#tag1:value1,tag2,tag3:value3 — default: None.
      注: それぞれのタグ文字列に含まれる:は、タグの一部です。

ソースコード

DogStatsDは、BSDライセンスでオープンソースとして公開しています。ソースコードは、githubのDatadogアカウント以下のdd-agentのリポジトリを参照してください。