API と mkrコマンドを使ってみる

この記事は、Mackerel アドベントカレンダー（全部CRE）の18日目の記事です。

Mackerelでは複数のインターフェースを用意しています。いちばんよく見るGUIの他に、別のアプリケーションなどからMackerelを操作可能にするAPI、そして、APIをより簡単に利用することができる、mkr コマンドです。

APIを叩いてみる
mkrコマンドを使ってみる
mkr コマンドで監視ルールを変更してみる

APIを叩いてみる

APIには、幅広くMackerelの操作をするためのものが揃っています。

サービス
ホスト
ホストメトリック
サービスメトリック
チェック監視
メタデータ
監視設定
通知チャンネル
通知グループ
アラート
ダッシュボード
グラフアノテーション
ユーザ
招待
オーガニゼーション

APIはcurlでも実行してみることができるので、どんな情報が取得・更新できるのか、使い心地をぜひ試してみてください。試しに、ホストAPIを使って、指定したサービスとロールに所属するホストの一覧を取得してみます。

curl -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" -X GET https://api.mackerelio.com/api/v0/hosts?service=sample-service\&role=sample-role

APIを叩くスクリプトや、アプリケーションを書くと、いろいろなことを自動化できそうでわくわくしますね。

ドキュメトにもっと詳しいことが載っています。

mackerel.io

mkrコマンドを使ってみる

APIを活用するには、何かしらスクリプトや簡単なコードを書く必要がある場合がありますが、そういったことをしなくても、APIを簡単に実行できるインターフェースが mkr コマンドです。

コマンド	できること
status	ホストの情報を取得します
hosts	ホストの一覧を取得します
create	新規ホストを作成します
update	ホストのステータスやロールを変更します
throw	ホストメトリックまたはサービスメトリックを投稿します
metrics	メトリックの値を取得します
fetch	最新のメトリックの値を取得します
retire	ホストを退役させます
services	サービスの一覧を取得します
monitors	監視ルールの操作を行います
alerts	アラートの一覧を取得、クローズします
dashboards	ダッシュボードの操作を行います
annotations	グラフアノテーションの操作を行います
org	オーガニゼーションの一覧を取得します
plugin	プラグインの管理をします
help, h	ヘルプを表示します

mkr コマンドを使って同じようにホストの一覧を取得する方法をまとめてみます。

今回は、ローカルのmacOSに mkr コマンドをインストールしていきます。インストールには brew を使います。

まずは、brew tap コマンドでリポジトリを追加します。

$ brew tap mackerelio/mackerel-agent

mkr コマンドをインストールします。

$ brew install mkr

mkr コマンドで利用するAPIキーを環境変数で指定します。

$ export MACKEREL_APIKEY=YOUR_API_KEY

mkr コマンドで、先ほどと同じようにサービスとロールを指定してホストの一覧を取得するとこのような感じです。パッとホストIDの一覧や、ホスト名などを拾ってきたい場合には便利です。

$ mkr hosts -s sample-service -r sample-role
[
    {
        "id": "HOST_ID",
        "name": "sample-host",
        "status": "working",
        "roleFullnames": [
            "sample-service:sample-role"
        ],
        "isRetired": false,
        "createdAt": "2018-04-09T13:08:55+09:00",
        "ipAddresses": {
            "eth0": "IP_ADDRESS"
        }
    }
]

mkr コマンドで監視ルールを変更してみる

mkr コマンドのイチオシ機能は、監視ルールを手元で管理することができる monitors オプションです。使い方はこんな感じです。

まずは、monitors オプションの中身を見てみましょう。このように、監視ルールの設定をjson形式で見ることができるのが、このオプションです。

$ mkr monitors
[
    {
        "id": "MONITOR_ID",
        "name": "CPU %",
        "type": "host",
        "metric": "cpu%",
        "operator": ">",
        "warning": 80,
        "critical": 90,
        "duration": 1,
        "maxCheckAttempts": 1,
        "scopes": [
            "sample-service: sample-role"
        ]
    },

(省略)

画面で該当箇所を見るとこんな感じです。

f:id:missasan:20181216160518p:plain

このjsonは手元にファイルとしてダウンロードしてくることができます。それが monitors pull オプションです。

$ mkr monitors pull
      info Monitor rules are saved to 'monitors.json' (6 rules).

ls をしてみると、monitors.json というファイル名でダウンロードされていることがわかります。

$ ls monitors.json 
monitors.json

jsonファイルはそのまま手元で編集することができます。vi コマンドでファイルを編集してみましょう。今回は、warningの閾値を80%から85%に緩和してみます。

$ vi monitors.json

さらに monitors diff オプションを使うと、変更箇所の差分を見ることができます。 warningの閾値が80%から85%になっていることがわかりやすく表示されています。

$ mkr monitors diff
Summary: 1 modify, 0 append, 0 remove

 {
   "critical": 90,
   "duration": 1,
   "maxCheckAttempts": 1,
   "metric": "cpu%",
   "name": "CPU %",
   "operator": ">",
   "scopes": [
     "sample-service: sample-role"
   ],
   "type": "host",
-  "warning": 80
+  "warning": 85
 },

このままでは、単に手元のjsonファイルが変更されているだけなので、これをMackerel本体に同期します。 monitors push オプションを利用します。

$ mkr monitors push
      info Update a rule.
{
  "id": "3fRyxz3Nez3",
  "name": "CPU %",
  "type": "host",
  "metric": "cpu%",
  "operator": ">",
  "warning": 85,
  "critical": 90,
  "duration": 1,
  "maxCheckAttempts": 1,
  "scopes": [
    "sample-service: sample-role"
  ]
},

アップデートが成功したメッセージが出力され、実際に画面を見ると、閾値が変更されていることがわかります。

f:id:missasan:20181216160947p:plain

このようにして、手元で監視ルールの書き換え、反映を行うことができます。また、この monitors.json ファイルを git などに置いておけば、バージョン管理をすることもできます。その他のCIツールなどと連携して、git で変更がコミットされたら、mkr monitors push をキックするなどのような仕組みもつくれます。

mkrコマンドでは他にもさまざまな操作ができます。詳しくはこちらもヘルプをどうぞ。

mackerel.io

API や mkrコマンドを活用して、普段の作業を自動化してみてはいかがでしょう。