監視設定

監視設定の登録

各種メトリックに対する監視や、外形監視をMackerelに登録します。 監視対象によって入力が異なります。

POST /api/v0/monitors

APIキーに必要な権限

  • Read
  • Write

ホストメトリック監視

入力(ホストメトリック監視)

KEY TYPE DESCRIPTION
type string 定数文字列 "host"
name string 監視一覧などで参照できる任意の名称。
memo string [optional] 監視設定のメモ。
duration number 指定された間隔(分)の平均値を監視します。有効範囲:1~10分。
metric string 監視対象のホストメトリック名。特定の定数文字列を指定することで、割合監視が可能です。 *1
operator string 指定した数値より大きいか小さいかというアラート条件を指定。">" または "<"。左辺が観測値で右辺が設定値となります。
warning number warningのAlert発生の閾値。
critical number criticalのAlert発生の閾値。
notificationInterval number [optional] 通知の再送設定をするときの再送間隔 (分)。このフィールドを省略すると通知は再送されません。
scopes array[string] [optional] 監視対象のサービス名またはロール詳細名。*2
excludeScopes array[string] [optional] 監視除外対象のサービス名またはロール詳細名。*2
isMute boolean [optional] 監視がミュート状態か否か *3
入力例
{
  "type": "host",
  "name": "disk.aa-00.writes.delta",
  "memo": "This monitor is for Hatena Blog.",
  "duration": 3,
  "metric": "disk.aa-00.writes.delta",
  "operator": ">",
  "warning": 20000.0,
  "critical": 400000.0,
  "notificationInterval": 60,
  "scopes": [
    "Hatena-Blog"
  ],
  "excludeScopes": [
    "Hatena-Bookmark: db-master"
  ]
}

応答(ホストメトリック監視)

成功時
{
  "id"  : "2cSZzK3XfmG",
  "type": "host",
  "name": "disk.aa-00.writes.delta",
  "memo": "This monitor is for Hatena Blog.",
  "duration": 3,
  "metric": "disk.aa-00.writes.delta",
  "operator": ">",
  "warning": 20000.0,
  "critical": 400000.0,
  "notificationInterval": 60,
  "scopes": [
    "Hatena-Blog"
  ],
  "excludeScopes": [
    "Hatena-Bookmark: db-master"
  ]
}

id が付与されて返却されます。

失敗時
STATUS CODE DESCRIPTION
400 入力が受け付けられないフォーマットだったとき
400 memoが250文字を超えているとき
400 durationが1~10の範囲を越えたとき
400 scopeexcludeScopesに指定されているサービス名やロール詳細名が未登録のとき
400 再送間隔が10分以上でないとき
403 必要な権限がないとき

*1 割合監視

ホストメトリック監視の場合、metric に特定の文字列を指定することでメトリックに対する割合監視となります。 割合監視として指定可能な metric は下記のとおりです。

metric
"cpu%"
"memory%"
"disk%"
"swap%"

*2 サービス名またはロール詳細名

サービス名またはロールの詳細な名前は <service name> または <service name>:<role name> というフォーマットの文字列です。

e.g. Hatena-Bookmark サービスならHatena-BookmarkHatena-Bookmark サービスの db-master ロールならHatena-Bookmark:db-master

使用できる文字列は /^[A-Za-z0-9][A-Za-z0-9_-]+$/

*3 監視のミュート

監視における通知を行わないようにする機能です。 監視の閾値に応じてアラートは発生しますが、通知チャンネルへの通知は送信されません。

ホスト死活監視

入力(ホスト死活監視)

KEY TYPE DESCRIPTION
type string 定数文字列 "connectivity"
name string 監視一覧などで参照できる任意の名称。
memo string [optional] 監視設定のメモ。
scopes array[string] [optional] 監視対象のサービス名またはロール詳細名。*2
excludeScopes array[string] [optional] 監視除外対象のサービス名またはロール詳細名。*2
notificationInterval number [optional] 通知の再送設定をするときの再送間隔 (分)。このフィールドを省略すると通知は再送されません。
isMute boolean [optional] 監視がミュート状態か否か
入力例
{
  "type": "connectivity",
  "name": "connectivity service1",
  "memo": "A monitor that checks connectivity.",
  "scopes": [
    "service1"
  ],
  "excludeScopes": [
    "service1: role3"
  ]
}

応答(ホスト死活監視)

成功時
{
  "id"  : "2cSZzK3XfmG",
  "type": "connectivity",
  "name": "connectivity service1",
  "memo": "A monitor that checks connectivity.",
  "scopes": [
    "service1"
  ],
  "excludeScopes": [
    "service1: role3"
  ]
}

id が付与されて返却されます。

失敗時
STATUS CODE DESCRIPTION
400 入力が受け付けられないフォーマットだったとき
400 memoが250文字を超えているとき
400 scopeexcludeScopesに指定されているサービス名やロール詳細名が未登録のとき
400 再送間隔が10分以上でないとき
403 必要な権限がないとき

サービスメトリック監視

入力(サービスメトリック監視)

KEY TYPE DESCRIPTION
type string 定数文字列 "service"
name string 監視一覧などで参照できる任意の名称。
memo string [optional] 監視設定のメモ。
service string 監視対象となるサービス名。
duration number 指定されたポイント数の平均値を監視する。有効範囲:直近1~10ポイント
metric string 監視対象のホストメトリック名。
operator string 指定した数値より大きいか小さいかというアラート条件を指定。">" または "<"。左辺が観測値で右辺が設定値となります。
warning number warningのAlert発生の閾値。
critical number criticalのAlert発生の閾値。
notificationInterval number [optional] 通知の再送設定をするときの再送間隔 (分)。このフィールドを省略すると通知は再送されません。
isMute boolean [optional] 監視がミュート状態か否か
入力例
{
  "type": "service",
  "name": "Hatena-Blog - access_num.4xx_count",
  "memo": "A monitor that checks the number of 4xx for Hatena Blog",
  "service": "Hatena-Blog",
  "duration": 1,
  "metric": "access_num.4xx_count",
  "operator": ">",
  "warning": 50.0,
  "critical": 100.0,
  "notificationInterval": 60
}

応答(サービスメトリック監視)

成功時
{
  "id"  : "2cSZzK3XfmG",
  "type": "service",
  "name": "Hatena-Blog - access_num.4xx_count",
  "memo": "A monitor that checks the number of 4xx for Hatena Blog",
  "service": "Hatena-Blog",
  "duration": 1,
  "metric": "access_num.4xx_count",
  "operator": ">",
  "warning": 50.0,
  "critical": 100.0,
  "notificationInterval": 60
}

id が付与されて返却されます。

失敗時
STATUS CODE DESCRIPTION
400 入力が受け付けられないフォーマットだったとき
400 memoが250文字を超えているとき
400 durationが1~10の範囲を越えたとき
400 serviceに指定されているサービス名が未登録のとき
400 再送間隔が10分以上でないとき
403 必要な権限がないとき

外形監視

入力(外形監視)

KEY TYPE DESCRIPTION
type string 定数文字列 "external"
name string 監視一覧などで参照できる任意の名称。
memo string [optional] 監視設定のメモ。
url string 監視対象のURL。
method string [optional] リクエスト時のメソッド。GET, POST, PUT, DELETEのいずれかで、省略時はGET
service string [optional] サービス名(ここで関連づけたサービスのサービスメトリックに監視時のレスポンスタイムがグラフ化されます)
notificationInterval number [optional] 通知の再送設定をするときの再送間隔 (分)。このフィールドを省略すると通知は再送されません。
responseTimeWarning number [optional] warningのAlert発生の応答時間の閾値 (ミリ秒) service 指定が必要です。
responseTimeCritical number [optional] criticalのAlert発生の応答時間の閾値 (ミリ秒) service 指定が必要です。
responseTimeDuration number [optional] 指定された期間のリクエストの平均値を監視する。(1~10分) service 指定が必要です。
containsString string [optional] レスポンスボディに含まれているべき文字列。
maxCheckAttempts number [optional] 何回連続で Warning/Critical になったらアラートを発生させるか。デフォルトは1 (1~10)です。
certificationExpirationWarning number [optional] 証明書の有効期限切れ監視のWaning閾値。期限までの残り日数。
certificationExpirationCritical number [optional] 証明書の有効期限切れ監視のCritical閾値。期限までの残り日数。
skipCertificateVerification boolean [optional] 証明書の照合を行わなわずに監視をおこなう。
isMute boolean [optional] 監視がミュート状態か否か
headers array[object] [optional] HTTPリクエストヘッダとして設定されているべき値をnamevalueで指定。このフィールドを省略するとデフォルトのヘッダが設定されます。ヘッダを設定したくない場合は空の配列を指定してください。
requestBody string [optional] リクエスト時のメッセージボディ

応答時間の監視を行うには responseTimeWarning, responseTimeCritical, responseTimeDuration の全てを指定する必要があります。 証明書有効期限の監視を行うには certificationExpirationWarning, certificationExpirationCritical の両方を指定する必要があります。

入力例
{
  "type": "external",
  "name": "Example Domain",
  "memo": "Monitors example.com",
  "method": "GET",
  "url": "https://example.com",
  "service": "Hatena-Blog",
  "notificationInterval": 60,
  "responseTimeWarning": 5000,
  "responseTimeCritical": 10000,
  "responseTimeDuration": 3,
  "containsString": "Example",
  "maxCheckAttempts": 3,
  "certificationExpirationWarning": 90,
  "certificationExpirationCritical": 30,
  "isMute": false,
  "headers": [{"name":"Cache-Control", "value":"no-cache"}]
}

応答(外形監視)

成功時
{
  "id"  : "2cSZzK3XfmG",
  "type": "external",
  "name": "example.com",
  "memo": "Monitors example.com",
  "method": "GET",
  "url": "https://example.com",
  "service": "Hatena-Blog",
  "notificationInterval": 60,
  "responseTimeWarning": 5000,
  "responseTimeCritical": 10000,
  "responseTimeDuration": 3,
  "containsString": "Example",
  "maxCheckAttempts": 3,
  "certificationLimitWarning": 90,
  "certificationLimitCritical": 30,
  "isMute": false,
  "headers": [{"name":"Cache-Control", "value":"no-cache"}]
}

id が付与されて返却されます。

失敗時
STATUS CODE DESCRIPTION
400 入力が受け付けられないフォーマットだったとき
400 memoが250文字を超えているとき
400 urlのスキームがhttp, https以外だったとき
400 再送間隔が10分以上でないとき
403 必要な権限がないとき

式による監視

入力(式による監視)

KEY TYPE DESCRIPTION
type string 定数文字列 "expression"
name string 監視一覧などで参照できる任意の名称。
memo string [optional] 監視設定のメモ。
expression string 監視対象の式。グラフの系列が1本になるもののみ有効。
operator string 指定した数値より大きいか小さいかというアラート条件を指定。">" または "<"。左辺が観測値で右辺が設定値となります。
warning number warningのAlert発生の閾値。
critical number criticalのAlert発生の閾値。
notificationInterval number [optional] 通知の再送設定をするときの再送間隔 (分)。このフィールドを省略すると通知は再送されません。
isMute boolean [optional] 監視がミュート状態か否か *3
入力例
{
  "type": "expression",
  "name": "role average",
  "memo": "Monitors the average of loadavg5",
  "expression": "avg(roleSlots(\"server:role\",\"loadavg5\"))",
  "operator": ">",
  "warning": 5.0,
  "critical": 10.0,
  "notificationInterval": 60
}

応答(式による監視)

成功時
{
  "id"  : "2cSZzK3XfmG",
  "type": "expression",
  "name": "role average",
  "memo": "Monitors the average of loadavg5",
  "expression": "avg(roleSlots(\"server:role\",\"loadavg5\"))",
  "operator": ">",
  "warning": 5.0,
  "critical": 10.0,
  "notificationInterval": 60
}

id が付与されて返却されます。

失敗時
STATUS CODE DESCRIPTION
400 入力が受け付けられないフォーマットだったとき
400 memoが250文字を超えているとき
400 再送間隔が10分以上でないとき
400 無効な式が指定されたとき
403 必要な権限がないとき

監視設定の取得

GET /api/v0/monitors

APIキーに必要な権限

  • Read

応答

{
  "monitors": [
    {
      "id"  : "2cSZzK3XfmB",
      "type": "host",
      "name": "disk.aa-00.writes.delta",
      "memo": "This monitor is for Hatena Blog.",
      "duration": 3,
      "metric": "disk.aa-00.writes.delta",
      "operator": ">",
      "warning": 20000.0,
      "critical": 400000.0,
      "scopes": [
        "Hatena-Blog"
      ],
      "excludeScopes": [
        "Hatena-Bookmark: db-master"
      ]
    },
    {
      "id": "2cSZzK3XfmA",
      "type": "connectivity",
      "scopes": [],
      "excludeScopes": []
    },
    {
      "id"  : "2cSZzK3XfmC",
      "type": "service",
      "name": "Hatena-Blog - access_num.4xx_count",
      "memo": "A monitor that checks the number of 4xx for Hatena Blog",
      "service": "Hatena-Blog",
      "duration": 1,
      "metric": "access_num.4xx_count",
      "operator": ">",
      "warning": 50.0,
      "critical": 100.0,
      "notificationInterval": 60
    },
    {
      "id"  : "2cSZzK3XfmD",
      "type": "external",
      "name": "example.com",
      "memo": "Monitors example.com",
      "url": "http://www.example.com",
      "service": "Hatena-Blog",
      "headers": [{"name":"Cache-Control", "value":"no-cache"}]
    },
    {
      "id"  : "2cSZzK3XfmE",
      "type": "expression",
      "name": "role average",
      "memo": "Monitors the average of loadavg5",
      "expression": "avg(roleSlots(\"server:role\",\"loadavg5\"))",
      "operator": ">",
      "warning": 5.0,
      "critical": 10.0,
      "notificationInterval": 60
    }
  ]
}
  • 各項目は監視設定の登録と同様です
  • 並び順はモニター種別 -> 名前の順 (mackerel.ioの監視一覧画面と同様)です

監視設定の更新

PUT /api/v0/monitors/<monitorId>

リクエストとレスポンスは監視設定の登録と同様です。不足している項目があると必須項目の場合はエラーとなります。 scopesexcludeScopesの更新は、指定したJsonで完全に上書きされます。たとえば、scopesがすでに存在している場合に項目を省略すると、scopesは削除されます。 type = external の監視設定で headers フィールドを指定しなかった場合、headers フィールドの値は更新されません.ヘッダの設定を削除したい場合は空の配列を指定してください。

APIキーに必要な権限

  • Read
  • Write

応答

成功時

更新後の監視設定を返します。監視設定の登録 と同様の形式です。

失敗時

監視設定の登録と同様のエラーです。

STATUS CODE DESCRIPTION
400 typeを変更しようとしたとき
400 memoが250文字を超えているとき
404 クエリパラメータに指定された<monitorId>が存在しない監視設定だったとき
403 必要な権限がないとき

監視設定の削除

DELETE /api/v0/monitors/<monitorId>

APIキーに必要な権限

  • Read
  • Write

応答

成功時

削除される直前の監視設定の状態が返却されます。 形式は監視設定の登録と同様です。

失敗時

STATUS CODE DESCRIPTION
404 クエリパラメータに指定された<monitorId>が存在しない監視設定だったとき
403 必要な権限がないとき