ホストメトリック

メトリックの投稿

エージェントが収集するメトリック(計測値)を 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 時点での計測値。

応答

成功時

{
  "sucess": true
}

失敗時

STATUS CODE DESCRIPTION
403 必要な権限がないとき
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>: {},
    …
  }
}

失敗時

STATUS CODE DESCRIPTION
403 必要な権限がないとき
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", "bytes", "bytes/sec", "iops" のいずれかです。
metrics array [ <metric>, <metric>, ...] metric は下記参照。

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

KEY TYPE DESCRIPTION
name string カスタムメトリック名. <graphDef>.name の後ろに . に続けて名前([-a-zA-Z0-9_]+またはワイルドカード*, #)を繋げたものである必要があります。
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 必要な権限がないとき
200以外 上記以外のエラー

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

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

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

  • 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時間以上)送信がない場合自動的に削除されますのでご注意ください。