CLIツール mkr を使う

CLIツールmkrを利用することで、ホストのステータスをまとめて変更するような操作や、手順をスクリプトに組込み自動化することができるようになります。

mkrはGitHubで公開しております。 https://github.com/mackerelio/mkr

使う前に

インストール

yumやaptを利用の場合は、mackerel-agentでも使われているMackerelのpackageリポジトリが追加されている必要があります。

yumを利用

% yum install mkr

aptを利用

% apt-get install mkr

brewを利用

% brew tap mackerelio/mackerel-agent
% brew install mkr

goでビルド

% go get github.com/mackerelio/mkr

セットアップ

mkrを使うためには、まずAPIキーを環境変数で指定します。

export MACKEREL_APIKEY=<API key>

使い方

詳しい使い方は https://github.com/mackerelio/mkr をご参照ください。

ホスト関連

例えばhostIdを指定して、そのホストの情報を取得できます。

mkr status <hostId>
$ mkr status 2eQGEaLxibb
{
    "id": "2eQGEaLxibb",
    "name": "myproxy001",
    "status": "standby",
    "roleFullnames": [
        "My-Service:proxy"
    ],
    "isRetired": false,
    "createdAt": "Nov 15, 2014 at 9:41pm (JST)"
}

またhostIdを指定してステータス変更を行なったり、

mkr update --status maintenance <hostIds>...

ホスト一覧を取得することが可能です。

mkr hosts --service My-Service --role proxy

これらを組み合わせて、指定したサービスとロールのホストのステータスをまとめて変更することができます。

mkr update --st working $(mkr hosts -s My-Service -r proxy | jq -r '.[].id')

監視ルール

mkrではmonitorsサブコマンドで監視ルールを操作することができます。サブコマンドは、pull/diff/pushの3種類あります。サブコマンドを指定しない場合、監視ルール一覧が表示されます。

  • pull
    • Mackerelから監視ルール一覧を取得し、ローカルファイルに保存します。
  • diff
    • Mackerelに設定されている監視ルール一覧と、ローカルファイルとの差分を表示します。
  • push
    • ローカルファイルの監視ルールの設定をMackerelに反映します。

jsonフォーマットについては、API仕様の「監視設定の登録」を参照してください

push時の監視ルールの同一性判定ロジック

pullする際はMackerelが付与したidが必ず含まれます。 pushする場合はidが含まれないルールも許容するために以下のロジックで監視ルールの同一判定を行います。

  • idを含む .. idで同一判定
  • idを含まずnameを含む .. nameで同一判定
    • 同じnameを持つ監視ルールが存在した場合、idでのみ同一判定を行います。そのため全ての監視ルールにidが含まれる必要があります。またWarningメッセージを出力します。
  • idnameも含まないルールがある場合はエラーとなります。

実行例

  • ローカルファイルとMackerel間の差分がない場合のdiff
% mkr monitors diff
Summary: 0 modify, 0 append, 0 remove
  • ローカルファイルとMackerel間の差分がある場合のdiff
% mkr monitors diff
Summary: 1 modify, 1 append, 1 remove

  {
   "name": "Filesystem %",
   "type": "host",
   "metric": "disk%",
   "operator": ">",
-  "warning": 95.000000,
+  "warning": 96.000000,
   "critical": 99.000000,
   "duration": 3,
   "url": "",
    "scopes": [
    ],
    "excludeScopes": [
    ],
  },
- {
-   "id": "<id>",
-   "name": "loadavg5",
-   "type": "host",
-   "metric": "loadavg5",
-   "operator": ">",
-   "warning": 1.000000,
-   "critical": 5.000000,
-   "duration": 3,
-   "url": "",
-   "scopes": [
-     "My-Service:proxy"
-   ],
-   "excludeScopes": [
-   ],
- },
+ {
+   "name": "loadavg",
+   "type": "host",
+   "metric": "loadavg5",
+   "operator": ">",
+   "warning": 1.000000,
+   "critical": 5.000000,
+   "duration": 5,
+   "url": "",
+   "scopes": [
+     "My-Service:proxy"
+   ],
+   "excludeScopes": [
+   ],
+ },
  • pushの例
% mkr monitors push --dry-run -F monitors_new.json
      info Create a new rule.
 {
   "name": "loadavg",
   "type": "host",
   "metric": "loadavg5",
   "operator": ">",
   "warning": 1.000000,
   "critical": 5.000000,
   "duration": 5,
   "url": "",
   "scopes": [
     "My-Service:proxy"
   ],
   "excludeScopes": [
   ],
 },
      info Delete a rule.
 {
   "id": "<id-1>",
   "name": "loadavg5",
   "type": "host",
   "metric": "loadavg5",
   "operator": ">",
   "warning": 1.000000,
   "critical": 5.000000,
   "duration": 3,
   "url": "",
   "scopes": [
     "My-Service:proxy"
   ],
   "excludeScopes": [
   ],
 },
      info Update a rule.
 {
   "id": "<id-2>",
   "name": "Filesystem %",
   "type": "host",
   "metric": "disk%",
   "operator": ">",
   "warning": 96.000000,
   "critical": 99.000000,
   "duration": 3,
   "url": "",
   "scopes": [
   ],
   "excludeScopes": [
   ],
 },

ダッシュボードを生成する

mkrではdashboardsサブコマンドでカスタムダッシュボードを定義ファイルから自動生成することができます。

定義ファイルはYAML形式です。

実行例

以下のように定義ファイルをパラメータで指定して実行することで、mkrに設定されているAPIキーに対応するオーガニゼーション内にカスタムダッシュボードが自動的に作成されます。

% mkr dashboards generate config.yml

また、--printオプションを指定することで、Mackerelへの登録・更新を行わずに標準出力にダッシュボードのmarkdownを出力することもできます。

% mkr dashboards generate config.yml --print

定義ファイル(YAML)の仕様

mkrで生成できるダッシュボードは2種類あります。

  1. ホストとメトリックを指定するホストグラフの一覧
  2. サービスメトリックや式によるグラフなどを個別に指定するグラフの一覧

それぞれのフォーマット例は以下のようになります。

ホストグラフ
config_version: 0.9
url_path: custom-graph
title: Custom Host Graphs
format: iframe
height: 200
width: 400
host_graphs:
  - headline: host graphs 1
    host_ids:
     - XXXXXXXXXXX
     - YYYYYYYYYYY
     - ZZZZZZZZZZZ
    graph_names:
     - loadavg5
     - cpu
     - filesystem
     - custom.linux.disk.elapsed.*
    period: 30m
  - headline: host graphs 2
    host_ids:
     - XXXXXXXXXXX
    graph_names:
     - loadavg5
     - memory
    period: 30m
個別グラフ指定
config_version: 0.9
url_path: custom-graph
title: Custom Graphs
format: iframe
graphs:
  - headline: any graphs
    column_count: 2
    graph_def:
     - service_name: sugoi-service
       graph_name: custom.access_latency.*
     - service_name: sugoi-service
       role_name: api
       graph_name: loadavg5
       stacked: false
       simplified: true
       period: 6h
     - host_id: XXXXXXXXX
       graph_name: custom.inode.count.#.*
       period: 30m
     - host_id: XXXXXXXXX
       graph_name: filesystem
       period: 30m
  - headline: expression graph
    graph_def:
     - query: avg(roleSlots('sugoi-service:api',sum(group(host($HOST_ID, 'cpu.system.percentage'), host($HOST_ID, 'cpu.user.percentage')))))
       period: 30m

YAMLの各項目

共通
項目名 type 説明
config_version string yamlの定義ファイルのversion。 現在は0.9固定
url_path string カスタムダッシュボードのURL。上記例だとhttps://mackerel.io/orgs/<orgname>/dashboards/custom-graphとなる
title string カスタムダッシュボードのタイトル
format string [optional]グラフの形式。iframe or image。デフォルト値はiframe
height int [optional]グラフの高さ。formatがiframeの場合のみ有効。デフォルト値は200。
width int [optional]グラフの幅。formatがiframeの場合のみ有効。デフォルト値は400。
host_graphs array[host_graphs] 以下にホストグラフの定義が配列形式で続く。graphs といずれか片方のみ指定できる。
graphs array[graphs] 以下に個別グラフ指定の定義が配列形式で続く。host_graphs といずれか片方のみ指定できる。
ホストグラフの定義

上記の host_graphs配下の項目として配列形式で定義。

項目名 type 説明
headline string 表の見出し
host_ids array[string] 一覧に展開させるホストの一覧。配列形式で指定。
graph_names array[string] 一覧に展開させるグラフ名の一覧。配列形式で指定。
period string [optional]グラフの表示期間。デフォルト値は"1h"。使用可能な単位はm, h, d, w, mo, y
個別グラフの定義

上記の graphs配下の項目として配列形式で定義。 定義方法により、以下のグラフ形式に対応。

  • service_name のみの指定でサービスグラフ
  • service_name, role_name の指定でロールグラフ
  • host_id の指定でホストグラフ
  • query の指定で式によるグラフ
  • サービスグラフ, ロールグラフ, ホストグラフ, 式によるグラフのいずれにも該当しなければエラー
項目名 type 説明
headline string 表の見出し
column_count int [optional]生成されるグラフのカラム数。デフォルト値は1。
graph_def array[graph_def] 以下にそれぞれのグラフの定義を配列形式で指定
service_name string サービス名
role_name string ロール名
host_id string ホストID
query string
graph_name string グラフ名
period string [optional]グラフの表示期間。デフォルト値は"1h"。使用可能な単位はm, h, d, w, mo, y
stacked boolean [optional]積み上げグラフかどうか。デフォルト値はfalse。ロールグラフのみ有効
simplified boolean [optional]簡略表示かどうか。デフォルト値はfalse。ロールグラフのみ有効

グラフアノテーション

mkrでは、annotationsサブコマンドでグラフアノテーションに関連する操作を行なえます。サブコマンドはcreate/list/update/deleteの4種類あります。

各サブコマンドで返ってくるjsonフォーマットについては、API仕様の「グラフアノテーション」を参照してください。

create

  • グラフアノテーションを作成するサブコマンドです
  • グラフアノテーションの作成に成功すると、作成したグラフアノテーションを表わすjsonが出力されます
  • servicefromtotitleが必須指定の指定パラメータです
  • descriptionrole(複数指定可能)を指定することもできます
% mkr annotations create --service My-Machine --from 1480125301 --to 1486125301 --title "Deploy" --description "Deployed"

{
    "id": "2VpN33ceumh",
    "title": "Deploy",
    "describe": "Deployed",
    "from": 1480125301,
    "to": 1486125301,
    "service": "My-Machine"
}

list

  • 指定したサービス名(service)と期間内(fromto)にあるグラフアノテーションの一覧を返すサブコマンドです
  • グラフアノテーションの一覧を表わすjsonが出力されます
  • servicefromtotitleが必須指定の指定パラメータです
% mkr annotations list --service My-Machine --from 1480125301 --to 1486125301

[
    {
        "id": "2VpN33ceumh",
        "title": "Deploy",
        "from": 1480125301,
        "to": 1486125301,
        "service": "My-Machine"
    }
]

update

  • 指定したグラフアノテーションの更新を行なうサブコマンドです
  • グラフアノテーションの更新に成功すると、更新されたグラフアノテーションを表わすjsonが出力されます
  • idservicefromtotitleが必須指定の指定パラメータです
  • descriptionrole(複数指定可能)を指定することもできます
% mkr annotations update --id 2VpN33ceumh --service My-Machine --from 1485013461 --to 1485169804 --title "updated" --role Desktop --role Laptop

{
    "id": "2VpN33ceumh",
    "title": "updated",
    "from": 1485013461,
    "to": 1485169804,
    "service": "My-Machine",
    "roles": [
        "Desktop",
        "Laptop"
    ]
}

delete

  • グラフアノテーションを削除するサブコマンドです
  • グラフアノテーションの削除に成功すると、削除されたグラフアノテーションを表わすjsonが出力されます
  • idが必須指定の指定パラメータです
% mkr annotations delete --id 2VpN33ceumh

{
    "id": "2VpN33ceumh",
    "title": "updated",
    "from": 1485013461,
    "to": 1485169804,
    "service": "My-Machine",
    "roles": [
        "Desktop",
        "Laptop"
    ]
}