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



# はじめに


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

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

# APIキーの発行

APIを利用するにはAPIキーが必要です。APIキーは[ダッシュボードのAPIキータブ](https://mackerel.io/orgs/First?tab=apikeys)で確認できます。
メトリックの投稿にはWrite権限が必要なので、必要に応じて権限の変更や新しいキーの発行を行ないましょう。

![スクリーンショット_2017-03-17_14_36_20.png](https://qiita-image-store.s3.amazonaws.com/0/159511/54527a16-1a6b-a1aa-c6e2-2c4a5e52ba1e.png "スクリーンショット_2017-03-17_14_36_20.png")


# ホストIDの取得

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

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

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


# 投稿APIのURL

ホストメトリックの投稿先は[こちら](https://mackerel.io/ja/api-docs/entry/host-metrics#post)です。

```
POST: /api/v0/tsdb
```

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


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

メトリックを投稿する前にAPIで[ホスト情報を取得](https://mackerel.io/ja/api-docs/entry/hosts#get)してみましょう。
`curl` コマンドを利用すれば簡単に取得できます。

```sh
$ 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`コマンドを利用すると見やすくなりますよ。

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

# メトリックの名称

[メトリックの投稿](https://mackerel.io/ja/api-docs/entry/host-metrics#post)には4つの情報が必要です。

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

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

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

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

```bash
$ 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つだけなのでグラフではなく点だけですね。

![スクリーンショット_2017-03-08_15.05.05.png](https://qiita-image-store.s3.amazonaws.com/0/159511/3c8146e5-defb-2860-f7b8-d0cf09cb8f43.png "スクリーンショット_2017-03-08_15.05.05.png")

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

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

```sh: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つの折れ線グラフが表示されました！

![スクリーンショット_2017-03-08_15.19.36.png](https://qiita-image-store.s3.amazonaws.com/0/159511/2a2b6c03-0ba2-2d76-cc5d-451892182401.png "スクリーンショット_2017-03-08_15.19.36.png")


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

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

- [Mackerel API ドキュメント（v0）](https://mackerel.io/ja/api-docs/)
- [メトリック仕様](https://mackerel.io/ja/docs/entry/spec/metrics)
- [ホストのカスタムメトリックを投稿する](https://mackerel.io/ja/docs/entry/advanced/custom-metrics)
	- プラグインによる投稿方法なのでAPIでの投稿とは異なりますが、出力フォーマットを変えればどちらにも対応できます。