- Registering host information
- Getting host information
- Updating host information
- Updating host status
- Updating host roles
- Retiring hosts
- List of hosts
- List of metric names
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 |