ホスト

ホスト情報の登録

エージェントが稼動しているホストをMackerelに登録します。

POST /api/v0/hosts

APIキーに必要な権限

  • Read
  • Write

入力

入力にホストが所属しているロールが与えられたとき、ホストへのロールの割り当てが行われます。この際存在しないサービス・ロール名が与えられた場合、それらが新規作成されます。

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

KEY TYPE DESCRIPTION
name string ホスト名
displayName string [optional] ホストの管理名
customIdentifier string [optional] ホストに対するユーザー独自の、オーガニゼーションで一意な識別子*1
memo string [optional] ホストに関するメモ
meta object ホストのメタ情報*2。空のオブジェクトでも登録することができます。
interfaces array[object] [optional] ホストのネットワークインターフェース情報*3
roleFullnames array[string] [optional] ホストが所属しているロールの名前の配列*4
checks array[hash[string]] [optional] ホストを監視するチェック監視項目の配列*5

応答

成功時

{
  "id": <hostId>
}

<hostId> : このホストに割り当てられたホスト IDです。以降のリクエストではこの ID を用いてホストを識別します。

失敗時

STATUS CODE DESCRIPTION
400 入力が受け付けられないフォーマットだったとき
403 APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

*1 customIdentifier

customIdentifier に null もしくは "" （空文字）を指定した場合、HTTPリクエストメソッドにより、以下のような挙動となります。

POST の場合

null で登録されます。

PUT の場合

登録されている値が null で上書きされます。

*2 meta

meta には色々な情報が入ります。例えば、mackerel-agent やクラウドインテグレーションにより登録されたホストの場合は以下のような情報が登録されます。

KEY TYPE DESCRIPTION
agent-name string エージェントの名前 e.g. "mackerel-agent/0.27.0 (Revision dfbccea)"
agent-revision string エージェントのリビジョン（Git のコミット SHA1） e.g. "2f531c6"
agent-version string エージェントのバージョン。 e.g. "0.4.2"
block_device hash[object] ブロックデバイスの情報。キーは名前、値は size などを持ったオブジェクトです。
cpu array[object] 各 CPU コアの情報。それぞれの object が mhz や model_name を持ちます。
filesystem hash[object] ファイルシステムの情報。キーはファイルシステムの名前、値は kb_available, kb_used などを持ったオブジェクトです。
kernel hash[string] カーネルの情報。uname コマンドで得られるものです。
memory hash[string] メモリの情報。
cloud hash[object] AWSインテグレーションなどのクラウドインテグレーションにより登録されたホストの場合に存在します。provider metadata などを持ったオブジェクトです。

*3 interfaces

interfacesの一つの要素は以下のキーを持つオブジェクトです。

KEY TYPE DESCRIPTION
name string インターフェースの名前。 e.g. "eth0"
macAddress string [optional] インターフェースの MAC アドレス。
ipv4Addresses array[string] [optional] インターフェースの IPv4 アドレス。
ipv6Addresses array[string] [optional] インターフェースの IPv6 アドレス。
ipAddress string [optional] インターフェースの IPv4 アドレス。
ipv6Address string [optional] インターフェースの IPv6 アドレス。

ただし ipAddress と ipv4Addresses、または ipv6Address と ipv6Addresses が同時に指定された場合は、それぞれ ipv4Addresses ipv6Addresses が優先されます。

*4 roleFullnames

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

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

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

*5 checks

checksの一つの要素は以下のキーを持つオブジェクトです。

KEY TYPE DESCRIPTION
name string チェック監視項目の名前（[a-zA-Z0-9_-]+）。
memo string [optional] チェック監視項目のメモ。

ホスト情報の取得

GET /api/v0/hosts/<hostId>

APIキーに必要な権限

  • Read

応答

{
  "host": <host>
}

<host> は以下のキーを持つオブジェクトです。

KEY TYPE DESCRIPTION
createdAt number ホストの登録時刻（epoch秒）
id string ホストID
name string ホスト名
displayName string [optional] ホストの管理名
customIdentifier string [optional] ホストに対するユーザー独自の、オーガニゼーションで一意な識別子
meta object ホストのメタ情報
interfaces array[object] ホストのネットワークインターフェース情報
size string ホストの種類 （"standard" または "micro"）
status string ホストのステータス（"working", "standby" など）
memo string ホストに関するメモ
isRetired boolean ホストが退役しているかどうか
retiredAt number [optional] ホストの退役時刻（epoch秒）
roles hash[array[string]] ホストが所属しているロールの一覧。キーはサービス名、値はそのサービスにおけるロール名の配列です。

customIdentifier を指定したホスト情報の取得

指定した customIdentifier を持つ、退役していない単一のホスト情報を取得できます。customIdentifier は / や ? といったURL予約文字を含み得るため、必要に応じてURLエンコードしてください。

GET /api/v0/hosts-by-custom-identifier/<customIdentifier>

APIキーに必要な権限

  • Read

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

以下のパラメータを指定することで、大文字小文字を区別せずに <customIdentifier> を比較して単一のホスト情報を取得することができます。その場合、最も古いものが選ばれます。caseInsensitive が指定されていない場合は、大文字小文字を区別して探索します。

PARAM TYPE DESCRIPTION
caseInsensitive boolean [optional] <customIdentifier> を、大文字小文字を区別せずに比較するかどうか。真なら大文字小文字を区別しません。

応答

{
  "host": <host>
}

<host> はホスト情報の取得で返ってくるオブジェクトと同型です。

ホスト情報の更新

PUT /api/v0/hosts/<hostId>

APIキーに必要な権限

  • Read
  • Write

入力

ホスト情報の登録と同様です。

roleFullnames で指定しなかったホストがもともと所属しているロールには所属したままとなります。 ホストにもともと所属しているロールをはずしたい場合は ホストのロールの更新 を使用します。

応答

成功時

{
  "id": <hostId>
}

失敗時

STATUS CODE DESCRIPTION
404 <hostId>に対応するホストが見つからないとき
400 JSON のフォーマットが不正であるとき
403 APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

ホストのステータスの更新

POST /api/v0/hosts/<hostId>/status

APIキーに必要な権限

  • Read
  • Write

入力

{
  "status": <hostStatus>
}

<hostStatus> は "standby", "working", "maintenance", "poweroff" のいずれかです。

応答

成功時

{
  "success": true
}

失敗時

STATUS CODE DESCRIPTION
404 <hostId>に対応するホストが見つからないとき
400 JSON のフォーマットが不正であるとき
403 APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

ホストの一括ステータス更新

登録したホストを複数個まとめてステータス変更します。

POST /api/v0/hosts/bulk-update-statuses

APIキーに必要な権限

  • Read
  • Write

入力

{
  "status": <hostStatus>,
  "ids": [ <hostId>, <hostId>, … ]
}

<hostId> を最大 30 個まで指定できます。 <hostStatus> は "standby", "working", "maintenance", "poweroff" のいずれかです。

応答

成功時

{
  "success": true
}

失敗時

STATUS CODE DESCRIPTION
404 1つでも<hostId>に対応するホストが見つからないとき
400 JSON のフォーマットが不正であるとき
400 一度にステータス変更できるホスト数（30個）の制限を超えてステータス変更しようとしたとき
403 APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

ホストのロールの更新

PUT /api/v0/hosts/<hostId>/role-fullnames

APIキーに必要な権限

  • Write

入力

{
  "roleFullnames": [ <string>, <string>, … ]
}

roleFullnames は ホスト情報の登録の項目の roleFullnames と同じ。

応答

成功時

{
  "success": true
}

失敗時

STATUS CODE DESCRIPTION
404 hostId に対応するホストが見つからないとき
400 JSON のフォーマットが不正であるとき
400 roleFullnames のフォーマットが不正であるとき
403 APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

ホストの退役

登録したホストを退役状態にします。

POST /api/v0/hosts/<hostId>/retire

APIキーに必要な権限

  • Read
  • Write

入力

空のJSONをPOSTします。

{}

応答

成功時

{
  "success": true
}

失敗時

STATUS CODE DESCRIPTION
404 <hostId>に対応するホストが見つからないとき
400 JSON のフォーマットが不正であるとき
403 APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

ホストの一括退役

登録したホストを複数個まとめて退役状態にします。

POST /api/v0/hosts/bulk-retire

APIキーに必要な権限

  • Read
  • Write

入力

<hostId> を最大 30 個まで指定できます。

{
  "ids": [ <hostId>, <hostId>, … ]
}

応答

成功時

{
  "success": true
}

失敗時

STATUS CODE DESCRIPTION
404 1つでも<hostId>に対応するホストが見つからないとき
400 JSON のフォーマットが不正であるとき
400 一度に退役できるホスト数（30個）の制限を超えて退役しようとしたとき
403 APIキーに書き込み権限がないとき / 許可されたIPアドレス範囲外からのアクセスの場合

ホストの一覧

GET /api/v0/hosts

/api/v0/hosts.json も同じクエリパラメータで同じ内容を返します。

APIキーに必要な権限

  • Read

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

次のパラメータでホストを絞り込むことができます。なにも指定されていない場合は、全ホストが返却されます。

PARAM TYPE DESCRIPTION
service string [optional] サービス名。
role string [optional] サービス内のロール名。複数指定可能（結果は各ロールに所属するホスト群の和集合となります）。serviceが指定されていない場合は無効です。
name string [optional] ホスト名。
status string [optional] ホストのステータスを絞り込む。複数指定可能。デフォルトは working と standbyです。
customIdentifier string [optional] ホスト情報の登録やホスト情報の更新で登録したユーザー独自のオーガニゼーションで一意な識別子。

応答

{
  "hosts": [ <host>, <host>, …]
}

<host> はホスト情報の取得で返ってくるオブジェクトと同型です。

メトリック名の一覧

GET /api/v0/hosts/<hostId>/metric-names

APIキーに必要な権限

  • Read

応答

成功時

{
  "names": [<metricName>, <metricName>, ...]
}
KEY TYPE DESCRIPTION
names array[string] ホストに投稿されているメトリック名。

失敗時

STATUS CODE DESCRIPTION
404 <hostId>に対応するホストが見つからないとき

監視ステータスの一覧

ホストに紐付いた監視ルールとそのステータス（監視ステータス）を取得します。対象は死活監視、メトリック監視、チェック監視、ロール内異常検知です。

GET /api/v0/hosts/<hostId>/monitored-statuses

APIキーに必要な権限

  • Read

応答

成功時

{
  "monitoredStatuses": [<monitoredStatus>, <monitoredStatus>, ...]
}

<monitoredStatus> は以下のキーを持つ、監視ステータスを表すオブジェクトです。

KEY TYPE DESCRIPTION
monitorId string 監視ルールのID
status string アラートステータス。"OK"、 "CRITICAL"、 "WARNING"、 "UNKNOWN" のいずれかになります。
detail object [optional] 詳細情報*6

*6 detail

監視ステータスに付随する詳細情報です。現在はチェック監視の監視ステータスにのみ付加されます。

KEY TYPE DESCRIPTION
type string 詳細情報の種類。チェック監視の場合、常に check です。
message string コマンド出力結果などの補助的なテキスト
memo string [optional] チェック監視に設定されたメモ

失敗時

STATUS CODE DESCRIPTION
404 指定されたIDのホストがみつからないとき