Datadogは、Webコンソールからだけではなく、APIも充実しており、かなり自動化ができるプラットフォームになっています。APIをより便利に使うための小粋なTipsを探していたのですが、今回も小粒なTipsということでいくつかご紹介します。

Postman

APIを扱うツールとしての定番にPostmanがあると思います。私も長らく使用していますが、ドキュメントの参照回数やタイピングの量が多くなりがちなAPIのテストにはとても便利なツールですね。

Datadogでは、Postmanのコレクションが提供されているので、すぐに始められるところもPostmanがおすすめな理由の１つです。コレクションとはAPI呼び出しのテンプレート集で、URLのパスやメソッド、パラメーター名などが設定されているので、値をセットするだけで簡単に試すことができます。

では、APIのドキュメントの英語版のGetting Startedの▶︎Run in Postmanから、コレクションをPostmanに取り込んでみましょう。日本語版のドキュメント中のリンクは古いようなので英語版からがおすすめです。

▶︎Run in PostmanをクリックするとPostmanが開き、Forkをしましょうというダイアログが出ます。

Fork Collectionしましょう。認証画面が出ますので、サインインするかアカウントを新規作成します。

Fork先の情報を設定して、いざForkします。ここではあらかじめDatadogというワークスペースを作成して、それを指定しています。削除したい時もワークスペースごと消せばよいので、新しいワークスペースを作成して使うのがおすすめです。

初めてForkする際には、プロファイルを公開するように促されますので何らか設定して公開します。
Fork Collectionをクリックした後、Forkに失敗したようなメッセージが出るかもしれませんが、Forkできているかどうか確認してみてください。おや？と思って何度もFork Collectionをクリックすると、たくさんForkされることがありますので、とりあえずワークスペースを開いて確認してみてください。おそらく以下のように成功していると思います。

コレクションを開いてみるとAPIのテンプレートがたくさん見えますね。早速使っていきましょう。まずは認証情報を設定します。

Activityの中の"Datadog Authentication"リンクをクリックします。

または、Environmentsから"Datadog Authentication"を開きます。

DatadogのAPI KeyとApplication Keyを設定します。

複数のOrganizationで作業する場合は、この"Datadog Authentication"を複製して、値をそれぞれのOrganizationのものに設定しておくと、切り替えながらAPIにアクセスすることができます。
デフォルトではNo Environmentとなっているところからプルダウンで切り替えられます。ここでは最初に設定した"Datadog Authentication"を選びます。

ではいよいよAPIを呼んでみましょう。例としてダッシュボードのリストを取得してみます。Dashboardsの中のGet all dashboardsを選びます。Query Paramsにパラメーターがありますので、VALUEに値を設定したり、不要なものはチェックを外して使用しないようにするなど、必要に応じて設定してください。

Dogshell

Postmanで簡単に対話的にAPIを試すことができますが、自動化のためにはスクリプトを書く必要が出てきます。PostmanのGUIツールと完全スクリプティングの中間くらいのコマンドラインツールがDogshellです。これはdogコマンドで色々な操作ができるというものです。ちょっとした日常の作業の自動化には、このくらいのツールがちょうどいいくらいのことが多くあるのではと思います。

ドキュメントはこちらです。DogshellはDatadog APIのPythonライブラリに含まれていて、そのGitHubのレポジトリはこちらです。

では実際に使ってみましょう。pipコマンドでインストールします。

pip install datadog

インストールするとdogコマンドが使えるようになります。（初回起動時はAPI Key, Application Keyの入力が求められます。）例えばtest_metricという名前のメトリクスを送信するには

dog metric post test_metric 1

とするだけです。とても簡単ですね。
私の自宅ではSwitchBotというIoT機器シリーズの温湿度計で気温と室温を測定していますが、これらのデータは、SwitchBotのハブを通してクラウドにデータを保存している場合は、API経由で取り出すことができます。これらのデータを取り出して、メトリクスとしてDatadogに送ってみます。

次のようなシェルスクリプトを書いてみました。

#!/bin/bash

token="_____SwitchBot_Token_____"
device_id=("__DEVICE1_ID__" "__DEVICE2_ID__")
device_name=("室内" "室外")

for i in {0..1}
do
  result=($(
    curl -s "https://api.switch-bot.com/v1.0/devices/${device_id[i]}/status" \
      --header "Authorization: ${token}" \
      --header "Content-Type: application/json; charset=utf8" \
    | jq ".body.humidity, .body.temperature"
  ))
  /usr/local/bin/dog metric post switchbot.humidity ${result[0]} --tags "device:${device_name[$i]}"
  /usr/local/bin/dog metric post switchbot.temperature ${result[1]} --tags "device:${device_name[$i]}"
done

curlコマンドでSwitchBotのAPIにアクセスして気温と湿度のデータを取得し、jqコマンドで数値部分だけど抜き出しています。

抜き出したデータをdogコマンドでDatadogに送信しています。温湿度計は室内と室外の2台あり、それぞれ区別できるように--tagsオプションでタグを設定しています。

このシェルスクリプトをcronで毎分実行するようにしました。思いつきで書いてみた、このくらいの行数のものであればシェルスクリプトで十分ですね。もう少し凝ったことをしたくなったらPythonなどのスクリプトに書き換えるかもしれません。

このようにして送信されたメトリクスを、ダッシュボードでグラフにしてみました。気温と湿度が可視化されて、deviceタグで室内と室外が区別されていますね。

スクリプト化して定期的に自動実行するような場合だけでなく、もっとアドホックに、手動で何か記録したいということもあるかと思います。例えば何か変化のきっかけになるような操作をイベントとして記録しておきます。

dog event post "換気" "窓開放"

そうすると、Datadogのイベントに登録され、ダッシュボードでグラフにオーバーレイして、イベントとメトリクスの関連が可視化されます。グラフの中の縦の線が、右側に示されるイベントが発生したタイミングを示しています。窓を開けたというイベントと室温の変化がリンクしている様子が見て取れますね。

モニター（アラート）からDatadog APIを呼び出す

モニターからWebhookを呼び出して、アラート状態が発生した時に次のアクションを起動することができますが、そのWebhookとしてDatadog APIを呼び出すことも可能です。

例えば、

あるアラートが発生した時に、関連する他のモニターをミュートする
あるアラートが発生した時に、メトリクスをポストしてダッシュボードに表示させる

といった利用例が考えられます。この他にもいろいろユースケースがあると思います。

詳細はこちらのドキュメントをご参照ください。

Dogmover

最後にAPIを活用した便利なツールをご紹介します。

Dogmoverというツールで、APIで取得できる設定情報を保存・復元することができます。
取り扱う設定情報は、ダッシュボード・モニター・ユーザー・Synthetics (APIテスト・ブラウザテスト)・AWSインテグレーション設定・ログのパイプライン・ノートブックです。

このツールの機能は、あるOrganizationから別のOrganizationに移行する時に、APIで取得できる設定情報を、元のOrganizationからダウンロードし、移行先のOrganizationにアップロードするというものです。前半のダウンロード部分だけを使えば、設定のバックアップツールとして使用することもできます。

APIを活用することで、Datadogをより幅広いユースケースに対応させたり、自動化を行ったりすることができますので、ぜひあれこれ試してみてください。

Happy Datadogging!