2016-03-18

ホストメトリック

メトリックの投稿
ホストのメトリックの値の取得
メトリックの最新値の取得
グラフ定義の投稿

メトリックの投稿

エージェントが収集するメトリック（計測値）を Mackerel に送信します。記録された値は Web のグラフなどで確認できます。

POST /api/v0/tsdb

APIに対して過去の値を送信した場合、Mackerel上の値は上書きされます。24時間以上前の古いタイムスタンプで投稿した場合は、そのメトリックは記録されません（ステータスコード 200 でレスポンスを返します）。また、アラートの発生はMackerel上の最新の値に基づいて行われるため、そのデータが最新の値ではない場合には、閾値を超えていたとしてもアラートは発生しません。

APIキーに必要な権限

Read
Write

入力

[ <metricValue>, <metricValue>, … ]

<metricvalue> : 以下のキーをもつオブジェクトです。

KEY	TYPE	DESCRIPTION
`hostId`	string	ホスト ID（ホスト登録時にサーバから与えられるものです）
`name`	string	メトリック名（`[a-zA-Z0-9._-]+`）
`time`	number	エポック秒。
`value`	number	`time` 時点での計測値。

応答

成功時

{
  "success": true
}

失敗時

STATUS CODE	DESCRIPTION
403	APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合
200以外	上記以外のエラー

ホストのメトリックの値の取得

エージェントから投稿されたメトリックの値を取得できます。

GET /api/v0/hosts/<hostId>/metrics

APIキーに必要な権限

Read

入力（クエリパラメータ）

次のパラメータでメトリック名と取得する期間を指定します。

KEY	TYPE	DESCRIPTION
`name`	string	メトリック名（`loadavg5` など。詳しくは → メトリック仕様）
`from`	number	メトリックを取得したい期間の最初 (epoch秒)
`to`	number	メトリックを取得したい期間の最後 (epoch秒)

応答

成功時

{
  "metrics": [
    {
      "time": <time>,
      "value": <value>
    },
    {
      "time": <time>,
      "value": <value>
    },
    …
  ]
}

並び順は、時刻が古い順です
メトリックの時刻を表す <time> はエポック秒です

失敗時

STATUS CODE	DESCRIPTION
404	ホストまたはメトリックが存在しない時
200以外	上記以外のエラー

メトリックの最新値の取得

エージェントから投稿されたメトリックの最新の値をホストごとに取得できます。

GET /api/v0/tsdb/latest

APIキーに必要な権限

Read

入力（クエリパラメータ）

次のパラメータでホストとメトリック名を指定します。

KEY	TYPE	DESCRIPTION
`hostId`	string	ホストID、複数指定可能。
`name`	string	メトリック名（`loadavg5` など。詳しくは → メトリック仕様）、複数指定可能。

応答

成功時

{
  "tsdbLatest": {
    <hostId>: {
      <name>: <metricValue>,
      <name>: <metricValue>,
      …
    },
    <hostId>: {
      …
    },
    …
  }
}

<metricvalue> : 以下のキーをもつオブジェクトです。

KEY	TYPE	DESCRIPTION
`time`	number	エポック秒。
`value`	number	`time` 時点での計測値。

失敗時

STATUS CODE	DESCRIPTION
403	APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合
200以外	上記以外のエラー

グラフ定義の投稿

カスタムメトリックのグラフ定義を Mackerel に送信します。

POST /api/v0/graph-defs/create

APIキーに必要な権限

Read
Write

入力

[ <graphDef>, <graphDef>, … ]

<graphDef> : 以下のキーをもつオブジェクトです。

KEY	TYPE	DESCRIPTION
`name`	string	メトリック名の最後の `.` より前の部分。 `custom.` ではじまる必要があります。また、ワイルドカード`#`, `*` を使用することもできます。
`displayName`	string	[optional] グラフの表示名。
`unit`	string	[optional] グラフの値の種類。可能な値は "float", "integer", "percentage", "seconds", "milliseconds", "bytes", "bytes/sec", "bits/sec", "iops" のいずれかです。
`metrics`	array	`[ <metric>, <metric>, ...]` metric は下記参照。

<metric> : 以下のキーをもつオブジェクト。

KEY	TYPE	DESCRIPTION
`name`	string	カスタムメトリック名。 `<graphDef>.name` の後ろに `.` に続けて名前（`[-a-zA-Z0-9_]+`またはワイルドカード`*`, `#`）を繋げたものである必要があります。ワイルドカードを使用する場合、`<graphDef>.name` にもワイルドカードの指定が必要になります。
`displayName`	string	[optional] メトリックの表示名。省略した場合はメトリック名の最後の`.` の後ろが使用されます。`%1`、`%2`.. のようにしてメトリック名の1つ目、2つ目.. のワイルドカードにマッチした部分を利用できます。
`isStacked`	boolean	対応するメトリックを積み上げ表示するかどうか。偽なら折れ線で表示されます。

入力例

[
  {
      "name" : "custom.cpu.foo",
      "displayName": "CPU",
      "unit": "percentage",
      "metrics": [
         { "name": "custom.cpu.foo.user", "displayName": "CPU user", "isStacked": true },
         { "name": "custom.cpu.foo.idle", "displayName": "CPU idle", "isStacked": true },
         ...
      ]
  },
  {
      "name" : "custom.wild.#",
      "displayName": "wildcard",
      "unit": "float",
      "metrics": [
         { "name": "custom.wild.#.foo", "displayName": "wild foo" },
         { "name": "custom.wild.#.bar", "displayName": "wild bar" },
         ...
      ]
  },
  {
    "name": "custom.cpu.bar",
    ...
  }
]

応答

成功時

{
  "success": true
}

失敗時

STATUS CODE	DESCRIPTION
403	APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合
200以外	上記以外のエラー

カスタムメトリック名とワイルドカードについて

カスタムメトリック名に使用できる文字は英数字もしくはハイフン（-）、アンダースコア（_）のいずれか、または連続しないドット（.）です。
カスタムメトリック名の先頭は custom. とする必要があります。（mackerel-agent は custom. を自動で付与します。）
またグラフ定義のメトリック名にはワイルドカード（* または #）を２つのドット（.）の間、または最後のドット（.）の後ろに単独で使用できます。
ワイルドカードはドットを除く文字の連続 [-a-zA-Z0-9_]+ にマッチします。
また、凡例のグループ化（後述）が可能なワイルドカード # は一つまでしか使えません。メトリック名全体は ^custom(\.([-a-zA-Z0-9_]+|[*#]))+$ のようになります。

ワイルドカード # を使った場合はメトリック名の# にマッチした部分でグラフの凡例がグループ化されます。例えば custom.docker.cpu.#.user、 custom.docker.cpu.#.system という２つの定義があって

custom.docker.cpu.f5240a.user
custom.docker.cpu.f5240a.system
custom.docker.cpu.e866aq.user
custom.docker.cpu.e866aq.system
custom.docker.cpu.e552ad.user
custom.docker.cpu.e552ad.system

のように6つのカスタムメトリックを送信した場合の凡例は下のようになります。

f:id:mackerelio:20150909172654p:plain

また、ワイルドカードを含むグラフ定義のカスタムメトリックは一定時間（およそ6〜8時間以上）送信がない場合自動的に削除されますのでご注意ください。