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

Name	Description	Validation
label	Defines a name for the entity.	String between 1 and 255 characters long Non-empty string
agent_id	Agent to which this entity is bound.	Optional String matching the regex `/^[-.\w]{1,255}$/`
ip_addresses	Hash of IP addresses that can be referenced by checks on this entity.	Optional Hash [String,String between 1 and 64 characters long: IPv4 or IPv6 address] Array or object with a number or items between 0 and 64
managed	Whether this entity is managed by Rackspace Managed Cloud.	Optional Boolean
metadata	Arbitrary key/value that are passed during the alerting phase.	Optional Hash [String,String between 1 and 255 characters long: String,String between 1 and 255 characters long] Array or object with a number of items between 0 and 256
uri	The Rackspace Cloud identifier of this entity. Only applies to Rackspace Cloud servers.	Optional String

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

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:

Response Code	Name	Description
201	OK	The ‘Location’ header contains a link to the newly created entity.
400	Bad request	The system received an invalid value in a request.
401	Unauthorized	The system received a request from a user that is not authenticated.
403	Forbidden	The system received a request that the user is not authorized to make.
500	Internal Server Error	An unexpected condition was encountered.
503	Service Unavailable	The system is experiencing heavy load or another system failure.

Request¶

The following table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	A valid authentication token with administrative access. For details, see Get your credentials

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:

Response Code	Name	Description
200	OK	The request completed.
401	Unauthorized	The system received a request from a user that is not authenticated.
403	Forbidden	The system received a request that the user is not authorized to make.
500	Internal Server Error	An unexpected condition was encountered.
503	Service Unavailable	The system is experiencing heavy load or another system failure.

Request¶

The following table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	A valid authentication token with administrative access. For details, see Get your credentials

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:

Response Code	Name	Description
200	OK	The request completed.
401	Unauthorized	The system received a request from a user that is not authenticated.
403	Forbidden	The system received a request that the user is not authorized to make.
404	Not Found	The URL, entity, or account requested is not found in the system.
500	Internal Server Error	An unexpected condition was encountered.
503	Service Unavailable	The system is experiencing heavy load or another system failure.

Request¶

The following table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	A valid authentication token with administrative access. For details, see Get your credentials

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:

Response Code	Name	Description
204	OK	The server has fulfilled the request but does not need to return an entity- body.
400	Bad request	The system received an invalid value in a request.
401	Unauthorized	The system received a request from a user that is not authenticated.
403	Forbidden	The system received a request that the user is not authorized to make.
404	Not Found	The URL, entity, or account requested is not found in the system.
500	Internal Server Error	An unexpected condition was encountered.
503	Service Unavailable	The system is experiencing heavy load or another system failure.

Request¶

The following table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	A valid authentication token with administrative access. For details, see Get your credentials

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:

Response Code	Name	Description
204	OK	The server has fulfilled the request. Does not return a response body.
401	Unauthorized	The system received a request from a user that is not authenticated.
403	Forbidden	The system received a request that the user is not authorized to make.
404	Not Found	The URL, entity, or account requested is not found in the system.
500	Internal Server Error	An unexpected condition was encountered.
503	Service Unavailable	The system is experiencing heavy load or another system failure.

Request¶

The following table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response¶

This operation does not return a response body.

Entities¶

Create an entity¶

Request¶

Response¶

List entities for an account¶

Request¶

Response¶

Get an entity by ID¶

Request¶

Response¶

Update an entity by ID¶

Request¶

Response¶

Delete entity by ID¶

Request¶

Response¶

Create an entity ¶

List entities for an account ¶

Get an entity by ID ¶

Update an entity by ID ¶

Delete entity by ID ¶