Mackerel API を使ってホストのカスタムメトリックを投稿するチュートリアル

はじめに

この記事はMackerelAPIを使ってオリジナルのメトリック収集を行うための方法をチュートリアル形式で紹介する記事です。以下のような方が対象でまだMackerelの利用経験が浅いと感じている人向けです。

• アカウントがある
• Mackerelを初めたばかり標準メトリックのグラフしか無い
• APIで独自のホストメトリックを投稿したい

APIキーの発行

APIを利用するにはAPIキーが必要です。APIキーはダッシュボードのAPIキータブで確認できます。
メトリックの投稿にはWrite権限が必要なので、必要に応じて権限の変更や新しいキーの発行を行ないましょう。

ホストIDの取得

監視対象のホストごとにMackerelからIDが設定されています。このIDはホストの /var/lib/mackerel-agent/id に記載されています。

$ cat /var/lib/mackerel-agent/id

こちらで確認しましょう。

投稿APIのURL

ホストメトリックの投稿先はこちらです。

POST: /api/v0/tsdb

URLはhttps://mackerel.io/api/v0/hostsとなります。
ドキュメントにはプロトコル、ドメインが記載されていないので注意が必要です。　 https://mackrer.io にリソース名を続けてください。

APIでホスト情報を取得してみよう

メトリックを投稿する前にAPIでホスト情報を取得してみましょう。
curl コマンドを利用すれば簡単に取得できます。

$ API_KEY="APIキーを記述"
$ HOST_ID=$( cat /var/lib/mackerel-agent/id )
$ curl https://mackerel.io/api/v0/hosts/${HOST_ID} \
-H "X-Api-Key: ${API_KEY}" \
-H "Content-Type: application/json" \
-X GET

jqコマンドを利用すると見やすくなりますよ。

$ curl https://mackerel.io/api/v0/hosts/${HOST_ID} -H "X-Api-Key: ${API_KEY}" | jq

メトリックの名称

メトリックの投稿には4つの情報が必要です。

• hostId: ホストID
• name: メトリック名
• time: エポック秒
• value: time時点での計測値

メトリック名には仕様がありこちらで公開されています。
カスタムメトリックの場合は　custom. から始めることが推奨されていますのでそうしましょう。
例えば custome.random.a を指定すると custom.random というグラフに a という要素で表示されます。

ランダムな値を投稿してみる

APIでランダムな値を投稿してみましょう。ホスト情報の取得と同様にcurlコマンドを使用します。

$ JSON="[{\"hostId\":\"${HOST_ID}\",\"name\":\"custom.random.a\",\"time\":$(date +%s),\"value\":${RANDOM}},{\"hostId\":\"${HOST_ID}\",\"name\":\"custom.random.b\",\"time\":$(date +%s),\"value\":${RANDOM}},{\"hostId\":\"${HOST_ID}\",\"name\":\"custom.random.c\",\"time\":$(date +%s),\"value\":${RANDOM}}]"

$ curl https://mackerel.io/api/v0/tsdb \
-H "X-Api-Key: ${API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d ${JSON}

メトリック名は custom.random.a custom.random.b custom.random.c の3つを設定しています。bashでは ${RANDOM} でランダムな値を取得でき、エポック秒はコマンドを使って date +%s で取得しています。

グラフが表示されました！

指定したカスタムメトリック名でグラフが表示されます。計測値が1つだけなのでグラフではなく点だけですね。

連続してランダムな値を投稿する

続けてランダムな値を投稿します。簡単なシェルスクリプトを書いて1分毎に値を投稿してみましょう。1分ごとに値を10回投稿します。Mackerelでは1分以下の間隔で計測値を投稿してもグラフには表示されません。

random_post.sh

#!/bin/sh


API_KEY="APIキーを記述"
HOST_ID=$( cat /var/lib/mackerel-agent/id )

for i in $(seq 10)
do

    JSON="[{\"hostId\":\"${HOST_ID}\",\"name\":\"custom.random.a\",\"time\":$(date +%s),\"value\":${RANDOM}},{\"hostId\":\"${HOST_ID}\",\"name\":\"custom.random.b\",\"time\":$(date +%s),\"value\":${RANDOM}},{\"hostId\":\"${HOST_ID}\",\"name\":\"custom.random.c\",\"time\":$(date +%s),\"value\":${RANDOM}}]"

    curl https://mackerel.io/api/v0/tsdb \
         -H "X-Api-Key: ${API_KEY}" \
         -H "Content-Type: application/json" \
         -X POST \
         -d ${JSON}

    sleep 60
done

グラフが表示されました！

a b c の3つの折れ線グラフが表示されました！

抑えておきたい公式ドキュメント

MackerelはHatena製サーバー監視ツールということもあり日本語ドキュメントが充実しています。
他にもAPIでいろいろなことが出来るので公式ドキュメントを読んでいろいろチャレンジしてみましょう。

• Mackerel API ドキュメント（v0）
• メトリック仕様
• ホストのカスタムメトリックを投稿する
  • プラグインによる投稿方法なのでAPIでの投稿とは異なりますが、出力フォーマットを変えればどちらにも対応できます。