Atom feed of this document
 
 
 

 4.4. Entities

 4.4.1. Summary

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 parameters:

  • A meaningful name for the entity

  • The IP address(es) for the entity (optional)

  • The meta-data that the monitoring system uses if an alarm is triggered (optional)

These parameters are further described in Attributes. See Create Entities for an example of how to create an entity.

 4.4.2. Attributes

Table 4.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

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

 4.4.3. Create Entity

Verb URI Description
POST /entities Creates a new entity. Specify the entity's characteristics using a valid set of parameters from the table shown in the Attributes section above.

Normal Response Code: (201) 'Location' header contains a link to the newly created entity.

Error Response Codes: 400, 401, 403, 500, 503

Once you have created an entity, you will typically create a check for it. See Create Check.

 

Example 4.9. Entity Create Request: XML

<?xml version="1.0" encoding="utf-8"?>
<entity>
  <label>Brand New Entity</label>
  <ip_addresses>
    <default>127.0.0.4</default>
    <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 4.10. Entity Create Request: JSON

{
    "label": "Brand New Entity",
    "ip_addresses": {
        "default": "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"
    }
}


 4.4.4. List Entities

Verb URI Description
GET /entities Lists the entities for this particular account.

There are no parameters for this call.

Normal Response Code: 200

Error Response Codes: 401, 403, 500, 503

 

Example 4.11. List Entities Response: XML

<?xml version="1.0" encoding="utf-8"?>
<container>
  <values>
    <entity id="enAAAAA">
      <label>Brand New Entity</label>
      <ip_addresses>
        <default>127.0.0.4</default>
        <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 4.12. List Entities Response: JSON

{
    "values": [
        {
            "id": "enAAAAA",
            "label": "Brand New Entity",
            "ip_addresses": {
                "default": "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
    }
}


 4.4.5. Get Entity

Verb URI Description
GET /entities/entityId Retrieves the current state of an entity.

This operation allows you to retrieve the current state of an entity.

Normal Response Code: 200

Error Response Codes: 401, 403, 404, 500, 503

 

Example 4.13. Get Entity Response: XML

<?xml version="1.0" encoding="utf-8"?>
<entity id="enAAAAA">
  <label>Brand New Entity</label>
  <ip_addresses>
    <default>127.0.0.4</default>
    <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 4.14. Get Entity Response: JSON

{
    "id": "enAAAAA",
    "label": "Brand New Entity",
    "ip_addresses": {
        "default": "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"
    }
}


 4.4.6. Update Entity

Verb URI Description
PUT /entities/entityId Updates an entity specified by the entityId. Since partial updates to an entity are acceptable, you may specify only the parameters you would like to update. For Rackspace Managed Cloud entities, many fields will be managed by Rackspace, so only the fields 'metadata' and 'agent_id' may be updated via the API.

Normal Response Code: (204) This code contains no content with an empty response body.

Error Response Codes: 400, 401, 403, 404, 500, 503

 

Example 4.15. Entity Update Request: XML

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


 

Example 4.16. Entity Update Request: JSON

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


 4.4.7. Delete Entity

Verb URI Description
DELETE /entities/entityId Deletes an entity from your account. Also deletes any checks and alarms defined for that entity.

Normal Response Code: (204) This code contains no content with an empty response body.

Error Response Codes: 401, 403, 404, 500, 503



loading table of contents...