ホスト

ホスト情報の登録

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

POST /api/v0/hosts

APIキーに必要な権限

  • Read
  • Write

入力

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

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

KEY TYPE DESCRIPTION
name string ホスト名。
meta object ホストの情報。*1
interfaces array[hash[string]] [optional] ネットワークインターフェースの情報。*2
roleFullnames array[string] [optional] このホストが所属しているロールの詳細な名前の配列。*3
checks array[string] [optional] このホストが監視するチェック監視項目の名前([a-zA-Z0-9_-]+)の配列。
displayName string [optional] このホストの管理名。
customIdentifier string [optional] このホストの、ユーザー独自の識別子。

応答

成功時

{
  "id": <hostId>
}

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

失敗時

STATUS CODE DESCRIPTION
400 入力が受け付けられないフォーマットだったとき
403 必要な権限がないとき

*1 meta

meta には色々な情報が入ります。

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 が mhzmodel_name を持ちます。
filesystem hash[object] ファイルシステムの情報。キーはファイルシステムの名前、値は kb_available, kb_used などを持ったオブジェクトです。
kernel hash[string] カーネルの情報。uname コマンドで得られるものです。
memory hash[string] メモリの情報。

*2 interfaces

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

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

*3 roleFullnames

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

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

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


ホスト情報の取得

GET /api/v0/hosts/<hostId>

APIキーに必要な権限

  • Read

応答

{
  "host": <host>
}

<host>ホスト情報の登録の内容を持つobjectで、以下のキーが追加されています。roleFullnames は存在しません。

KEY TYPE DESCRIPTION
createdAt number ホストの登録時刻(epoch 秒)
id string
status string ホストのステータス。"working", "standby" などです。
memo string このホストに関するメモ。Web UI から編集できます。
roles hash[array[string]] ホストのロール。キーはサービス名、値はそのサービスにおけるロール名の配列です。
interfaces array[hash[string]] ホストのネットワークインターフェース情報。
isRetired boolean ホストが退役しているかどうか。
displayName string このホストの管理名。
meta hash[string] cpu, memory などのメタ情報。

ホスト情報の更新

PUT /api/v0/hosts/<hostId>

APIキーに必要な権限

  • Read
  • Write

入力

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

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

応答

成功時

{
  "id": <hostId>
}

失敗時

STATUS CODE DESCRIPTION
404 <hostId>に対応するホストが見つからないとき
400 JSON のフォーマットが不正であるとき
403 必要な権限がないとき

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

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 必要な権限がないとき

ホストのロールの更新

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 必要な権限がないとき

ホストの退役

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

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

APIキーに必要な権限

  • Read
  • Write

入力

空のJSONをPOSTします。

{}

応答

成功時

{
  "success": true
}

失敗時

STATUS CODE DESCRIPTION
404 <hostId>に対応するホストが見つからないとき
400 JSON のフォーマットが不正であるとき
403 必要な権限がないとき

ホストの一覧

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] ホストのステータスを絞り込む。複数指定可能。デフォルトは workingstandbyです。
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>に対応するホストが見つからないとき