Entities

An entity represents the object or resource that you want to monitor. You can create an entity to monitor your website, a particular web service, or your Rackspace server, or server instance. Each entity represents only one item in the monitoring system. For example, if you wanted to monitor each server in a cluster, you would create an entity for each of the servers. You would not create a single entity to represent the entire cluster.

An entity can have multiple checks associated with it. Multiple checks enable you to check multiple services on the same host by creating multiple checks on the same entity, instead of multiple entities each with a single check.

When you create a new entity in the monitoring system, you specify the following information:

Attributes

Use the following entity API operations to create and manage entities.

• Create an entity
• List entities for an account
• Get an entity by ID
• Update an entity by ID
• Delete entity by ID

Create an entity

POST /entities

Create a new entity in the monitoring system by using a valid set of attributes from the entities attributes table.

The following table shows the possible response codes for this operation:

Request

The following table shows the header parameters for the request:

Example Create entity: JSON request

{
"label": "Brand New Entity",
"ip_addresses": {
"entity_ip_addresses_hash_key": "127.0.0.4",
"b": "127.0.0.5",
"c": "127.0.0.6",
"test": "127.0.0.7"
},
"metadata": {
"all": "kinds",
"of": "stuff",
"can": "go",
"here": "null is not a valid value"
}
}

Response

This operation does not return a response body.

List entities for an account

GET /entities

Lists the entities associated with this account.

This operation can be paginated. For information, see Paginated collections.

The following table shows the possible response codes for this operation:

Request

The following table shows the header parameters for the request:

Note

This operation does not accept a request body.

Response

Example List entities for account: JSON response

{
"values": [
{
"id": "enAAAAA",
"label": "Brand New Entity",
"ip_addresses": {
"entity_ip_addresses_hash_key": "127.0.0.4",
"b": "127.0.0.5",
"c": "127.0.0.6",
"test": "127.0.0.7"
},
"metadata": {
"all": "kinds",
"of": "stuff",
"can": "go",
"here": "null is not a valid value"
}
}
],
"metadata": {
"count": 1,
"limit": 50,
"marker": null,
"next_marker": null,
"next_href": null
}
}

Get an entity by ID

GET /entities/{entityId}

Returns information about the specified entity.

The following table shows the possible response codes for this operation:

Request

The following table shows the header parameters for the request:

Note

This operation does not accept a request body.

Response

Example Get entity by ID: JSON response

{
"id": "enAAAAA",
"label": "Brand New Entity",
"ip_addresses": {
"entity_ip_addresses_hash_key": "127.0.0.4",
"b": "127.0.0.5",
"c": "127.0.0.6",
"test": "127.0.0.7"
},
"metadata": {
"all": "kinds",
"of": "stuff",
"can": "go",
"here": "null is not a valid value"
}
}

Update an entity by ID

PUT /entities/{entityId}

Updates the entity specified by the entityId. You can make partial updates to an entity. When you submit the update request, only specify the parameters that you want to update.

For Rackspace Managed Cloud resources, many fields are managed by Rackspace. If you update these entities, you can only update the metadata and agent_id fields using this API operation. Other attributes, like label and ip_addresses, are updated based on the information from the source system. For example, if you update the label of a cloud server instance in MyCloud control panel, the label of the matching entity will be updated automatically within seconds. For full entity attributes list, refer to the Entities attributes table.

The following table shows the possible response codes for this operation:

Request

The following table shows the header parameters for the request:

Note

This operation does not accept a request body.

Example Update entity: JSON request

{
"label": "Brand New Entity 2"
}

Response

The following operation does not return a response body.

Delete entity by ID

DELETE /entities/{entityId}

Deletes a specified entity from your account. Also deletes any checks and alarms defined for that entity.

The following table shows the possible response codes for this operation:

Request

The following table shows the header parameters for the request:

Note

This operation does not accept a request body.

Response

This operation does not return a response body.