5.4. Entities

An entity is the target of what you are monitoring. For example, you can create an entity to monitor your website, a particular web service, or your Rackspace server or server instance. Note that an 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. This allows 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 follow information.

Concept: Entity

Requirements: An account

Next step: Learn about check types

Table 5.1. Attributes
NameDescriptionValidation
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 to.
  • 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 number of items between 0 and 64

managed Whether this entity is managed by Rackspace Managed Cloud.
  • Optional

  • Boolean

metadata Arbitrary key/value pairs 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 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 entities API operations to create, view, and manage entity resources

MethodURIDescription
POST/entities

Adds an entity to the system.

GET/entities

Lists the entities associated with this account.

GET/entities/{entityId}

Returns information about the specified entity.

PUT/entities/{entityId}

Updates the properties for the specified entity.

DELETE/entities/{entityId}

Deletes the specified entity.

 5.4.1. Add an entity

 
MethodURIDescription
POST/entities

Adds an entity to the system.

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

This table shows the possible response codes for this operation:

Response CodeNameDescription
201OK

The 'Location' header contains a link to the newly created entity.

400Bad request

The system received an invalid value in a request.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.4.1.1. Request

This table shows the header parameters for the add an entity request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This table shows the body parameters for the add an entity request:

NameTypeDescription

label

​String

(Required)

Defines a name for the entity. Value can be between 1 and 255 characters long.

ip_addresses

​Hash

(Optional)

Hash of IP addresses that can be referenced by checks on this entity. Values can be an array or object with from 0 to 64 items. Each item must be an IPv4 or IPv6 address between 1 and 64 characters long.

metadata

​Hash

(Optional)

Update metadata information on the account, or add a new metadata item. Metadata is formatted in key/value string pairs. The key and value attributes are string values between 1 and 255 characters long.

 

Example 5.9. XML request: Create an entity

<?xml version="1.0" encoding="utf-8"?>
<entity>
  <label>Brand New Entity</label>
  <ip_addresses>
    <entity_ip_addresses_hash_key>127.0.0.4</entity_ip_addresses_hash_key>
    <b>127.0.0.5</b>
    <c>127.0.0.6</c>
    <test>127.0.0.7</test>
  </ip_addresses>
  <metadata>
    <all>kinds</all>
    <of>stuff</of>
    <can>go</can>
    <here>null is not a valid value</here>
  </metadata>
</entity>

 

Example 5.10. JSON request: Add an entity

{
    "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"
    }
}

 5.4.2. List entities

 
MethodURIDescription
GET/entities

Lists the entities associated with this account.

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

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

The request completed.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.4.2.1. Request

This table shows the header parameters for the list entities request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This operation does not accept a request body.

 5.4.2.2. Response

 

Example 5.11. XML response: List entities for account

<?xml version="1.0" encoding="utf-8"?>
<container>
  <values>
    <entity id="enAAAAA">
      <label>Brand New Entity</label>
      <ip_addresses>
        <entity_ip_addresses_hash_key>127.0.0.4</entity_ip_addresses_hash_key>
        <b>127.0.0.5</b>
        <c>127.0.0.6</c>
        <test>127.0.0.7</test>
      </ip_addresses>
      <metadata>
        <all>kinds</all>
        <of>stuff</of>
        <can>go</can>
        <here>null is not a valid value</here>
      </metadata>
    </entity>
  </values>
  <metadata>
    <count>1</count>
    <limit>50</limit>
    <marker/>
    <next_marker/>
    <next_href/>
  </metadata>
</container>

 

Example 5.12. JSON response: List entities for account

{
    "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
    }
}

 5.4.3. Get entity by ID

 
MethodURIDescription
GET/entities/{entityId}

Returns information about the specified entity.

Use this operation to retrieve the current state of an entity.

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

The request completed.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

404Not Found

The URL or entity requested is not found in the system.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.4.3.1. Request

This table shows the header parameters for the get entity by id request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This operation does not accept a request body.

 5.4.3.2. Response

 

Example 5.13. XML response: Get entity by ID

<?xml version="1.0" encoding="utf-8"?>
<entity id="enAAAAA">
  <label>Brand New Entity</label>
  <ip_addresses>
    <entity_ip_addresses_hash_key>127.0.0.4</entity_ip_addresses_hash_key>
    <b>127.0.0.5</b>
    <c>127.0.0.6</c>
    <test>127.0.0.7</test>
  </ip_addresses>
  <metadata>
    <all>kinds</all>
    <of>stuff</of>
    <can>go</can>
    <here>null is not a valid value</here>
  </metadata>
</entity>

 

Example 5.14. JSON response: Get entity by ID

{
    "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"
    }
}

 5.4.4. Update entity by ID

 
MethodURIDescription
PUT/entities/{entityId}

Updates the properties for the specified entity.

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 entities, 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.

This table shows the possible response codes for this operation:

Response CodeNameDescription
204OK

The server has fulfilled the request but does not need to return an entity-body.

400Bad request

The system received an invalid value in a request.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

404Not Found

The URL or entity requested is not found in the system.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.4.4.1. Request

This table shows the header parameters for the update entity by id request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This table shows the body parameters for the update entity by id request:

NameTypeDescription

id

​String

(Required)

The ID assigned to the account.

label

​String

(Required)

Defines a name for the entity. Value can be between 1 and 255 characters long.

agent_id

​String

(Optional)

Agent to which this entity is bound to. Value can be a string that matches the regex /^[-\.\w]{1,255}$/.

ip_addresses

​Hash

(Optional)

Hash of IP addresses that can be referenced by checks on this entity. Values can be an array or object with from 0 to 64 items. Each item must be an IPv4 or IPv6 address between 1 and 64 characters long.

metadata

​Hash

(Optional)

Arbitrary key/value pairs that are passed during the alerting phase. Values can be an array or object with from 0 to 256 items. The key and value attributes are string values between 1 and 255 characters long.

 

Example 5.15. XML request: Update entity

<?xml version="1.0" encoding="utf-8"?>
<entity>
  <label>Brand New Entity 2</label>
</entity>

 

Example 5.16. JSON request: Update entity

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

 5.4.5. Delete entity by ID

 
MethodURIDescription
DELETE/entities/{entityId}

Deletes the specified entity.

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

This table shows the possible response codes for this operation:

Response CodeNameDescription
204OK

The server has fulfilled the request but does not need to return an entity-body.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

404Not Found

The URL or entity requested is not found in the system.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.4.5.1. Request

This table shows the header parameters for the delete entity by id request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This operation does not accept a request body.



loading table of contents...