監視ルール

• 監視ルールの登録
• 監視ルールの一覧
• 監視ルールの取得
• 監視ルールの更新
• 監視ルールの削除

監視ルールの登録

各種メトリックに対する監視や、外形監視を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	[optional] warningのAlert発生の閾値。割合監視 *1 の場合は、有効範囲が0~100(%)になります。
critical	number	[optional] criticalのAlert発生の閾値。割合監視 *1 の場合は、有効範囲が0~100(%)になります。
maxCheckAttempts	number	[optional] 何回連続で Warning/Critical になったらアラートを発生させるか。デフォルトは1 (1~10)です。
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,
  "maxCheckAttempts": 3,
  "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,
  "maxCheckAttempts": 3,
  "notificationInterval": 60,
  "scopes": [
    "Hatena-Blog"
  ],
  "excludeScopes": [
    "Hatena-Bookmark: db-master"
  ]
}

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

失敗時

STATUS CODE	DESCRIPTION
400	入力が受け付けられないフォーマットだったとき
400	nameが空文字列のとき
400	memoが2048文字を超えているとき
400	durationが1~10の範囲を越えたとき
400	割合監視 *1 の設定で、warningまたはcriticalが0~100(%)の範囲を越えたとき
400	maxCheckAttemptsが1~10の範囲を越えたとき
400	scopeやexcludeScopesに指定されているサービス名やロール詳細名が未登録のとき
400	再送間隔が10分以上でないとき
403	APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

*1 割合監視

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

metric
"cpu%"
"memory%"
"disk%"
"swap%"
"container-cpu%"
"container-memory%"

*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	[optional] 監視一覧などで参照できる任意の名称。デフォルトはconnectivityです。
memo	string	[optional] 監視ルールのメモ。
alertStatusOnGone	string	[optional] この監視ルールで発生するアラートのアラートステータス。"CRITICAL"（デフォルト値）または "WARNING" です。
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.",
  "alertStatusOnGone": "WARNING",
  "scopes": [
    "service1"
  ],
  "excludeScopes": [
    "service1: role3"
  ]
}

応答(ホスト死活監視)

成功時

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

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

失敗時

STATUS CODE	DESCRIPTION
400	入力が受け付けられないフォーマットだったとき
400	nameが空文字列のとき
400	memoが2048文字を超えているとき
400	alertStatusOnGoneがCRITICALまたはWARNINGでないとき
400	scopeやexcludeScopesに指定されているサービス名やロール詳細名が未登録のとき
400	再送間隔が10分以上でないとき
403	APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

サービスメトリック監視

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

KEY	TYPE	DESCRIPTION
type	string	定数文字列 "service"
name	string	監視一覧などで参照できる任意の名称。
memo	string	[optional] 監視ルールのメモ。
service	string	監視対象となるサービス名。
duration	number	指定されたポイント数の平均値を監視する。有効範囲：直近1~10ポイント
metric	string	監視対象のホストメトリック名。
operator	string	指定した数値より大きいか小さいかというアラート条件を指定。">" または "<"。左辺が観測値で右辺が設定値となります。
warning	number	[optional] warningのAlert発生の閾値。
critical	number	[optional] criticalのAlert発生の閾値。
maxCheckAttempts	number	[optional] 何回連続で Warning/Critical になったらアラートを発生させるか。デフォルトは1 (1~10)です。
missingDurationWarning	number	[optional] 途切れ監視のwarningのAlert発生閾値 (分)。
missingDurationCritical	number	[optional] 途切れ監視の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,
  "maxCheckAttempts": 3,
  "missingDurationWarning": 360,
  "missingDurationCritical": 720,
  "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,
  "maxCheckAttempts": 3,
  "missingDurationWarning": 360,
  "missingDurationCritical": 720,
  "notificationInterval": 60
}

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

失敗時

STATUS CODE	DESCRIPTION
400	入力が受け付けられないフォーマットだったとき
400	nameが空文字列のとき
400	memoが2048文字を超えているとき
400	durationが1~10の範囲を越えたとき
400	maxCheckAttemptsが1~10の範囲を越えたとき
400	missingDurationWarningまたはmissingDurationCriticalが10分の倍数ではないとき、あるいは一週間を超える時
400	serviceに指定されているサービス名が未登録のとき
400	再送間隔が10分以上でないとき
403	APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

外形監視

入力(外形監視)

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リクエストヘッダとして設定されているべき値をnameとvalueで指定。このフィールドを省略するとデフォルトのヘッダが設定されます。ヘッダを設定したくない場合は空の配列を指定してください。
requestBody	string	[optional] リクエスト時のメッセージボディ
followRedirect	boolean	[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	nameが空文字列のとき
400	memoが2048文字を超えているとき
400	urlのスキームがhttp, https以外だったとき
400	再送間隔が10分以上でないとき
400	maxCheckAttemptsが1~10の範囲を越えたとき
403	APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

式による監視

入力(式による監視)

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

入力例

{
  "type": "expression",
  "name": "role average",
  "memo": "Monitors the average of loadavg5",
  "expression": "avg(roleSlots(\"service: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(\"service:role\",\"loadavg5\"))",
  "operator": ">",
  "warning": 5.0,
  "critical": 10.0,
  "notificationInterval": 60
}

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

失敗時

STATUS CODE	DESCRIPTION
400	入力が受け付けられないフォーマットだったとき
400	nameが空文字列のとき
400	memoが2048文字を超えているとき
400	再送間隔が10分以上でないとき
400	無効な式が指定されたとき
403	APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

ロール内異常検知による監視

入力(ロール内異常検知による監視)

KEY	TYPE	DESCRIPTION
type	string	定数文字列 "anomalyDetection"
name	string	監視一覧などで参照できる任意の名称。
memo	string	[optional] 監視ルールのメモ。
scopes	array[string]	監視対象のサービス名とロール詳細名。*2
warningSensitivity	string	[optional] warningのAlert発生の閾値。insensitive、normal、sensitiveのいずれか。
criticalSensitivity	string	[optional] criticalのAlert発生の閾値。insensitive、normal、sensitiveのいずれか。
maxCheckAttempts	number	[optional] 何回連続で Warning/Critical になったらアラートを発生させるか。デフォルトは3 (1~10)です。
trainingPeriodFrom	number	[optional] 再学習させる際に起点となる時刻(epoch秒)。
notificationInterval	number	[optional] 通知の再送設定をするときの再送間隔 (分)。このフィールドを省略すると通知は再送されません。
isMute	boolean	[optional] 監視がミュート状態か否か

入力例

{
  "type": "anomalyDetection",
  "name": "anomaly detection",
  "memo": "my anomaly detection for roles",
  "scopes": [
    "myService: myRole"
  ],
  "warningSensitivity": "insensitive",
  "maxCheckAttempts": 3
}

応答(ロール内異常検知による監視)

成功時

{
  "id"  : "2cSZzK3XfmG",
  "type": "anomalyDetection",
  "name": "anomaly detection",
  "memo": "my anomaly detection for roles",
  "scopes": [
    "myService: myRole"
  ],
  "warningSensitivity": "insensitive",
  "maxCheckAttempts": 3
}

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

失敗時

STATUS CODE	DESCRIPTION
400	入力が受け付けられないフォーマットだったとき
400	nameが空文字列のとき
400	memoが2048文字を超えているとき
400	scopesに指定されているサービス名やロール詳細名が未登録のとき
400	warningSensitivityまたはcriticalSensitivityに insensitive / normal / sensitive 以外の値が指定されたとき
400	warningSensitivityとcriticalSensitivityの両方が未指定の時
400	再送間隔が10分以上でないとき
400	trainingPeriodFromが未来の値のとき
403	APIキーに書き込み権限がないとき

クエリによる監視

入力（クエリによる監視）

KEY	TYPE	DESCRIPTION
type	string	定数文字列 "query"
name	string	監視一覧などで参照できる任意の名称。
memo	string	[optional] 監視ルールのメモ。
query	string	監視対象のクエリ。
legend	string	アラート画面などで表示するグラフの凡例。
operator	string	指定した数値より大きいか小さいかというアラート条件を指定。">" または "<"。左辺が観測値で右辺が設定値となります。
warning	number	warningのAlert発生の閾値。
critical	number	criticalのAlert発生の閾値。
notificationInterval	number	[optional] 通知の再送設定をするときの再送間隔（分）。このフィールドを省略すると通知は再送されません。
isMute	boolean	[optional] 監視がミュート状態か否か。 *3

入力例

{
  "type": "query",
  "name": "cpu utilization",
  "memo": "Monitors the cpu utilization of httpbin",
  "query": "container.cpu.utilization{k8s.deployment.name=\"httpbin\"}",
  "legend": "cpu.utilization {{k8s.node.name}}",
  "operator": ">",
  "warning": 70.0,
  "critical": 90.0,
  "notificationInterval": 60
}

応答（クエリによる監視）

成功時

{
  "id"  : "2cSZzK3XfmG",
  "type": "query",
  "name": "cpu utilization",
  "memo": "Monitors the cpu utilization of httpbin",
  "query": "container.cpu.utilization{k8s.deployment.name=\"httpbin\"}",
  "legend": "cpu.utilization {{k8s.node.name}}",
  "operator": ">",
  "warning": 70.0,
  "critical": 90.0,
  "notificationInterval": 60
}

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

失敗時

STATUS CODE	DESCRIPTION
400	入力が受け付けられないフォーマットだったとき
400	nameが空文字列のとき
400	memoが2048文字を超えているとき
400	再送間隔が10分以上でないとき
400	無効なクエリが指定されたとき
403	APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

---

監視ルールの一覧

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,
      "maxCheckAttempts": 3,
      "scopes": [
        "Hatena-Blog"
      ],
      "excludeScopes": [
        "Hatena-Bookmark: db-master"
      ]
    },
    {
      "id": "2cSZzK3XfmA",
      "type": "connectivity",
      "alertStatusOnGone": "CRITICAL",
      "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,
      "maxCheckAttempts": 1,
      "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"}],
      "maxCheckAttempts": 1
    },
    {
      "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の監視一覧画面と同様)です

---

監視ルールの取得

GET /api/v0/monitors/<monitorId>

APIキーに必要な権限

• Read

応答

{
  "monitor": {
    "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,
    "maxCheckAttempts": 3,
    "scopes": [
      "Hatena-Blog"
    ],
    "excludeScopes": [
      "Hatena-Bookmark: db-master"
    ]
  }
}

• 各項目は監視ルールの登録と同様です

---

監視ルールの更新

PUT /api/v0/monitors/<monitorId>

リクエストとレスポンスは監視ルールの登録と同様です。不足している項目があると必須項目の場合はエラーとなります。 scopesとexcludeScopesの更新は、指定したJsonで完全に上書きされます。たとえば、scopesがすでに存在している場合に項目を省略すると、scopesは削除されます。

死活監視

alertStatusOnGone フィールドを変更した時、変更前にその監視ルールによって発生したアラートは次のようになります。

• 通知の再送設定（notificationInterval）がされているアラート

  alertStatusOnGone の変更後に通知の再送が発生した場合にのみ、そのタイミングで新しいアラートステータスに変更されます。

• 通知の再送設定がされていないアラート

  アラートステータスは変更されません。

また、alertStatusOnGone フィールドを指定しなかった場合、 alertStatusOnGone フィールドの値は更新されません。

外形監視

headers フィールドを指定しなかった場合、headers フィールドの値は更新されません。ヘッダの設定を削除したい場合は空の配列を指定してください。

APIキーに必要な権限

• Read
• Write

応答

成功時

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

失敗時

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

STATUS CODE	DESCRIPTION
400	typeを変更しようとしたとき
400	nameが空文字列のとき
400	memoが2048文字を超えているとき
404	クエリパラメータに指定された<monitorId>が存在しない監視ルールだったとき
403	APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

---

監視ルールの削除

DELETE /api/v0/monitors/<monitorId>

APIキーに必要な権限

• Read
• Write

応答

成功時

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

失敗時

STATUS CODE	DESCRIPTION
404	クエリパラメータに指定された<monitorId>が存在しない監視ルールだったとき
403	APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合