5.4. 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. 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, in Monitoring key terms and concepts

Requirements: An account

Next step: Learn about check types

Table 5.2. 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​{?id,​agent_id}

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. Create 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 entities 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 create an entity request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access. For details, see Retrieving an authentication token

 

Example 5.5. 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"
    }
}

This operation does not accept a request body.

 5.4.2. List entities for an account

 
MethodURIDescription
GET/entities​{?id,​agent_id}

Lists the entities associated with this account.

Use /entities?agent_id=AnAgentID to filter information on the specified agent.

Use /entities?id=entityOneId& id=entityTwoId to filter information on the specified entities.

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 for an account request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access. For details, see Retrieving an authentication token

This operation does not accept a request body.

 5.4.2.2. Response

 

Example 5.6. 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
    }
}

 5.4.3. Get an 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, entity, or account 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 an entity by id request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access. For details, see Retrieving an authentication token

This operation does not accept a request body.

 5.4.3.2. Response

 

Example 5.7. 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"
    }
}

 5.4.4. Update an 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 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. Otherwise, refer to the Entities attributes table.

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, entity, or account 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 an entity by id request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access. For details, see Retrieving an authentication token

 

Example 5.8. Update entity: JSON request

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

This operation does not accept a request body.

 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. Does not return a response 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, entity, or account 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. For details, see Retrieving an authentication token

This operation does not accept a request body.



Contents Search
loading table of contents...