Hosts

Register Host Information

Registering an agent-running host to Mackerel.

POST /api/v0/hosts

Required permissions for the API key

  • Read
  • Write

Input

By designating the role to which a host belongs in the input, the host will be assigned to that role. If a service or role name that does not yet exist is entered, it will be created.

This object holds the following keys:

KEY TYPE DESCRIPTION
name string name of the host
displayName string [optional] host management name
customIdentifier string [optional] an identifier for the host that is user-specific and unique to the organization*1
meta object host metadata*2. Empty objects can also be registered.
memo string [optional] notes related to the host
interfaces array[object] [optional] host network interface information*3
roleFullnames array[string] [optional] an array of the full name of the role to which the host belongs*4
checks array[hash[string]] [optional] an array of the check monitoring item that monitors the host*5

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 key doesn't have the required permissions / when accessing from outside the permitted IP address range

*1 customIdentifier

If null or "" (an empty string) is specified customIdentifier, the following will occur depending on the HTTP request method.

For POST

It is registered as null.

For PUT

The registered value is overwritten with null.

*2 meta

meta contains various information. For example, if the host is registered by mackerel-agent or Cloud Integration, the following information will be registered.

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. The keys are device names, and the values are objects that contain variables like size.
cpu array[object] each CPU’s core info. each object holds mhz and model_name
filesystem hash[object] filesystem information. The keys are filesystem names, and the values are objects that hold kb_available, kb_used, etc.
kernel hash[string] kernel information; can be got with the command uname
memory hash[string] memory information
cloud hash[object] Exists if the host is registered through Cloud Integration such as AWS Integration. An object that contains keys like provider and metadata.

*3 interfaces

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

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

However, if ipAddress and ipv4Addresses or ipv6Address and ipv6Addresses are specified at the same time, then ipv4Addresses and ipv6Addresses will take precedence.

*4 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_-]+$/

*5 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] notes regarding the monitor.

Get Host Information

GET /api/v0/hosts/<hostId>

Required permissions for the API key

  • Read

Response

{
  "host": <host>
}

<host> is an object that holds the following keys:

KEY TYPE DESCRIPTION
createdAt number the host's registration timestamp（in epoch seconds）
id string the host's ID
name string the name of the host
displayName string [optional] the host's management name
customIdentifier string [optional] an identifier for the host that is user-specific and unique to the organization
meta object host metadata
interfaces array[object] host network interface information
size string host type （"standard" or "micro"）
status string status of the host（"working", "standby" etc.）
memo string notes related to the host
isRetired boolean whether or not the host is retired
retiredAt number [optional] the host's retirement timestamp（in epoch seconds）
roles hash[array[string]] List of the roles to which the host belongs. The keys are service names, and the values are arrays of role names.

Get Host Information By Custom Identifier

Get information of a non-retired host by specifying its customIdentifier. You should apply URL encoding to <customIdentifier> because it can contain reserved characters such as / and ?.

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

Required permissions for the API key

  • Read

Input (Query parameter)

With the following parameter, you can compare <customIdentifier> in a case-insensitive manner and retrieve single host information. In that case, old one is chosen. If caseInsensitive is not specified, a host information by a case-sensitive search will be returned.

PARAM TYPE DESCRIPTION
caseInsensitive boolean [optional] whether to compare <customIdentifier> to case-insensitive or not. If true, a case-insensitive search will be performed.

Response

{
  "host": <host>
}

<host> is the same type as the object that changes in Get Host Information

Update Host Information

PUT /api/v0/hosts/<hostId>

Required permissions for the API key

  • Read
  • Write

Input

Same as Register 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 Update Host Roles API.

Response

Success

{
  "id": <hostId>
}

Error

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

Update Host Status

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

Required permissions for the API key

  • Read
  • Write

Input

{
  "status": <hostStatus>
}

<hostStatus> includes: "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 found
400 when JSON format is incorrect
403 when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range

Bulk Update Host Statuses

This will update multiple registered host statuses.

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

Required permissions for the API key

  • Read
  • Write

Input

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

You can specify <hostId> up to 30. <hostStatus> includes: "standby", "working", "maintenance", or "poweroff"

Response

Success

{
  "success": true
}

Error

STATUS CODE DESCRIPTION
404 when some of the hosts that correspond to the <hostId> can't be found
400 when JSON format is incorrect
400 when trying to update hosts status and exceeding the limit (30)
403 when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range

Update Host Roles

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

Required permissions for the API key

  • Write

Input

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

roleFullnames is the same as roleFullnames object in Register Host Information.

Response

Success

{
  "success": true
}

Error

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

Retire Hosts

This will retire a registered host.

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

Required permissions for the 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 found
400 when JSON format is incorrect
403 when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range

Bulk Retire Hosts

This will retire multiple registered hosts.

POST /api/v0/hosts/bulk-retire

Required permissions for the API key

  • Read
  • Write

Input

You can specify <hostId> up to 30.

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

Response

Success

{
  "success": true
}

Error

STATUS CODE DESCRIPTION
404 when some of the hosts that correspond to the <hostId> can't be found
400 when JSON format is incorrect
400 when trying to retire hosts and exceeding the limit (30)
403 when the API key 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 the API key

  • Read

Input (Query parameter)

The following parameters can be used to filter hosts. If nothing has been assigned yet, 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] filters the host status. multiple specifications are possible. defaults are working and standby.
customIdentifier string [optional] an identifier for the host that is user-specific and unique to the organization (registered at Register Host Information or Update Host Information API)

Response

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

<host> is the same type as the object that changes in Get Host Information

List Metric Names

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

Required permissions for the 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

List Monitoring Statuses

Retrieves the monitor associated with the host and its status (monitoring status). Supported for connectivity monitoring, metric monitoring, check monitoring, and anomaly detection for roles.

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

Required permissions for the API key

  • Read

Response

Success

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

<monitoredStatus> is an object that represents the monitoring status and holds the following keys:

KEY TYPE DESCRIPTION
monitorId string monitor ID
status string alert status. either "OK", "CRITICAL", "WARNING", or "UNKNOWN"
detail string [optional] detailed information*6

*6 detail

Detailed information that accompanies the monitoring status. Currently only available for monitoring statuses of check monitoring.

KEY TYPE DESCRIPTION
type string the type of detailed information. check monitoring is always check
message string auxillary text such as command output results
memo string [optional] notes configured for check monitoring

Error

STATUS CODE DESCRIPTION
404 when the host that corresponds to the specified ID can’t be found