Hosts

Registering host information

Registering an agent-running host to Mackerel.

POST /api/v0/hosts

Required permissions for API key

  • Read
  • Write

Input

By designating a host’s service and role in the rollFullnames input to the API, the host will be assigned to that role. If service and role names that don’t yet exist are entered, they will be created.

Objects that hold the following keys:

KEY TYPE DESCRIPTION
name string host name
meta object host information *1
interfaces array[hash[string]] [optional] network interface information *2
roleFullnames array[string] [optional] array of full names of the roles to which this host belongs *3
checks array[hash[string]] [optional] array of check monitorings that monitor this host *4
displayName string [optional] this host’s management name
customIdentifier string [optional] user-specific identifier for this host

Response

Success

{
  "id": <hostId>
}

<hostId> : The host ID that was assigned to this host. With this request the host will be identified by this ID.

Error

STATUS CODE DESCRIPTION
400 when the input is in a format that can’t be accepted.
403 when the API doesn't have the required permissions / when accessing from outside the permitted IP address range

*1 meta

meta contains various information.

KEY TYPE DESCRIPTION
agent-name string agent name e.g. "mackerel-agent/0.27.0 (Revision dfbccea)"
agent-revision string agent revision (Git commit SHA1) e.g. "2f531c6"
agent-version string agent version, e.g. "0.4.2"
block_device hash[object] block device info. object that contains key name, variables like size etc.
cpu array[object] each CPU’s core info. each object holds mhz and model_name
filesystem hash[object] filesystem information. an object that holds “key is a name of filesystem”, kb_available, kb_used, etc.
kernel hash[string] kernel information; can be got with the command uname
memory hash[string] memory information

*2 interfaces

One element of interfaces is an object that holds the following keys.

KEY TYPE DESCRIPTION
name string interface name, e.g. "eth0"
ipAddress string interface IP address
macAddress string interface MAC address
ipv4Addresses array[string] interface IPv4 addresses
ipv6Addresses array[string] interface IPv6 addresses

*3 roleFullnames

The full names of roles are in this character string format: <service name>:<role name>

e.g. A role named db-master in a service named Hatena-Bookmark would be Hatena-Bookmark:db-master

Usable characters include /^[A-Za-z0-9][A-Za-z0-9_-]+$/

*4 checks

One element of checks is an object that holds the following keys.

KEY TYPE DESCRIPTION
name string name of the monitor ([a-zA-Z0-9_-]+).
memo string [optional] a memo about the monitor.

Getting host information

GET /api/v0/hosts/<hostId>

Required permissions for API key

  • Read

Response

{
  "host": <host>
}

<host> is an object that holds the contents of Registering host information with the addition of the below key. roleFullnames does not exist.

KEY TYPE DESCRIPTION
createdAt number host registration timestamp (Unix time)
id string
status string the status of the host. (e.g. "working", "standby")
memo string the memo regarding this host; can be edited in the web UI.
roles hash[array[string]] the host’s role. the array of “key is the service name”, “variable is the name of the role in that service.”
interfaces array[hash[string]] host network interface information
isRetired boolean whether or not the host is retiring
displayName string this host’s management name
meta hash[string] the meta information of cpu, memory, etc.

Updating host information

PUT /api/v0/hosts/<hostId>

Required permissions for API key

  • Read
  • Write

Input

Same as Registering host information.

A host remains to belong to the roles which you didn't specify by roleFullnames. If you want to Un-assign roles from a host, please use Updating host roles API.

Response

Success

{
  "id": <hostId>
}

Error

STATUS CODE DESCRIPTION
404 when the host that corresponds to the <hostId> can’t be located
400 when JSON format is incorrect
403 when the API doesn't have the required permissions / when accessing from outside the permitted IP address range

Updating host status

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

Required permissions for API key

  • Read
  • Write

Input

{
  "status": <hostStatus>
}

<hostStatus> is one of these: "standby", "working", "maintenance", or "poweroff"

Response

Success

{
  "success": true
}

Error

STATUS CODE DESCRIPTION
404 when the host that corresponds to the <hostId> can’t be located
400 when JSON format is incorrect
403 when the API doesn't have the required permissions / when accessing from outside the permitted IP address range

Updating host roles

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

Required permissions for API key

  • Write

Input

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

roleFullnames is the same as roleFullnames object in Registering host information.

Response

Success

{
  "success": true
}

Error

STATUS CODE DESCRIPTION
404 when the host that corresponds to the hostId can’t be located
400 when JSON format is incorrect
400 when the format of roleFullnames is incorrect
403 when the API doesn't have the required permissions / when accessing from outside the permitted IP address range

Retiring hosts

This will retire a registered host.

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

Required permissions for API key

  • Read
  • Write

Input

This will POST empty JSON.

{}

Response

Success

{
  "success": true
}

Error

STATUS CODE DESCRIPTION
404 when the host that corresponds to the <hostId> can’t be located
400 when JSON format is incorrect
403 when the API doesn't have the required permissions / when accessing from outside the permitted IP address range

list of hosts

GET /api/v0/hosts

/api/v0/hosts.json returns the same contents with the same query parameters.

Required permissions for API key

  • Read

Input (Query parameter)

The following parameter will extract hosts. If nothing has yet been assigned, all hosts will be returned.

PARAM TYPE DESCRIPTION
service string [optional] service name
role string [optional] role names in the service, multiple assignments possible (result will be a unit of the hosts that belong to each role) if service has not been assigned it will be ignored.
name string [optional] host name
status string [optional] extract host status, multiple assignments possible, defaults are working and standby.
customIdentifier string [optional] user-specific identifier for the host (registered at Registering host information or Updating host information API)

Response

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

<host> is the same type as the object that changes in Getting host information

List of metric names

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

Required permissions for API key

  • Read

Response

Success

{
  "names": [<metricName>, <metricName>, ...]
}
KEY TYPE DESCRIPTION
names array[string] The name of the metrics being posted in the Host.

Error

STATUS CODE DESCRIPTION
404 when the Host corresponding to <hostId> can't be found