5.5. Checks

A check is one of the foundational building blocks of the monitoring system. The check determines the parts or pieces of the entity that you want to monitor, the monitoring frequency, how many monitoring zones are originating the check, and so on. You can create up to 1000 checks.

The check, as created, will not trigger alert messages until you create an alarm to generate notifications. Alarms operate on a single check and multiple alarms can be created for a single check (e.g. ensure both that a HTTPS server is responding and that it has a valid certificate).

[Note]Note

Checks are strictly associated with a parent entity, therefore the REST URLs for checks are underneath the entity that they are associated with.

When you create a new check in the monitoring system, you specify the following information.

Table 5.2. Attributes
NameDescriptionValidation
Attributes used for all checks
type The type of check.
  • Immutable

  • String between 1 and 64 characters long

details Details specific to the check type.
  • Optional

  • Hash [String,String between 1 and 255 characters long:Optional]

  • Array or object with number of items between 0 and 256

disabled Disables the check.
  • Optional

  • Boolean

label A friendly label for a check.
  • Optional

  • String between 1 and 255 characters long

metadata Arbitrary key/value pairs.
  • 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

period The period in seconds for a check. The value must be greater than the minimum period set on your account.
  • Optional

  • Integer

  • Value (30..1800)

timeout The timeout in seconds for a check. This has to be less than the period.
  • Optional

  • Integer

  • Value (2..1800)

Attributes used for remote checks
monitoring_zones_poll List of monitoring zones to poll from. Note: This argument is only required for remote (non-agent) checks
  • Optional

  • Array [String]

target_alias A key in the entity's 'ip_addresses' hash used to resolve this check to an IP address. This parameter is mutually exclusive with target_hostname.
  • Optional

  • String between 1 and 64 characters long

target_hostname The hostname this check should target. This parameter is mutually exclusive with target_alias.
  • Optional

  • Valid FQDN, IPv4 or IPv6 address

target_resolver Determines how to resolve the check target.
  • Optional

  • One of (IPv4, IPv6)

[Note]Note

target_alias and target_hostname are mutually exclusive; one, but not both, must be provided.

Use the check API operations to create, view, and manage check resources

MethodURIDescription
POST/entities/{entityId}/checks

Creates a Rackspace Cloud Monitoring check and associates it with an entity.

POST/entities/{entityId}/test-check

Test a check before creating it.

POST/entities/{entityId}/test-check​{?debug}

Test a check and include extra check type-specific debugging information, if available.

POST/entities/{entityId}/checks/{checkId}/test

Test an existing check inline.

GET/entities/{entityId}/checks

Lists the checks associated with a given entityId.

GET/entities/{entityId}/checks/{checkId}

Returns information about the specified check.

PUT/entities/{entityId}/checks/{checkId}

Updates the properties for the specified check.

DELETE/entities/{entityId}/checks/{checkId}

Deletes a check from your account.

 5.5.1. Create a check

 
MethodURIDescription
POST/entities/{entityId}/checks

Creates a Rackspace Cloud Monitoring check and associates it with an entity.

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

The check, as created, does not trigger alert messages until you create an alarm to generate notifications, to enable the creation of a single alarm that acts upon multiple checks (e.g. alert if any of ten different servers stops responding) or multiple alarms off of a single check. (e.g. ensure both that a HTTPS server is responding and that it has a valid certificate).

This table shows the possible response codes for this operation:

Response CodeNameDescription
201Created

'Location' header contains a link to the newly created check.

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.5.1.1. Request

This table shows the header parameters for the create a check request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

 

Example 5.17. Create a check: XML request

<?xml version="1.0" encoding="utf-8"?>
<check>
  <label>Website check 1</label>
  <type>remote.http</type>
  <details>
    <url>http://www.foo.com</url>
    <method>GET</method>
  </details>
  <monitoring_zones_poll>
    <monitoring_zone_id>mzA</monitoring_zone_id>
  </monitoring_zones_poll>
  <timeout>30</timeout>
  <period>100</period>
  <target_alias>entity_ip_addresses_hash_key</target_alias>
</check>

 

Example 5.18. Create a check: JSON request

{
    "label": "Website check 1",
    "type": "remote.http",
    "details": {
        "url": "http://www.foo.com",
        "method": "GET"
    },
    "monitoring_zones_poll": [
        "mzA"
    ],
    "timeout": 30,
    "period": 100,
    "target_alias": "entity_ip_addresses_hash_key"
}

 5.5.2. Test a check

 
MethodURIDescription
POST/entities/{entityId}/test-check

Test a check before creating it.

This operation causes Rackspace Cloud Monitoring to attempt to run the check on the specified monitoring zones and return the results. This operation allows you to test the check parameters in a single step before the check is actually created in the system.

[Note]Note

You can copy the results of a test check response and paste it directly into a test alarm.

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

Request completed.

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.5.2.1. Request

This table shows the header parameters for the test a check request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

 

Example 5.19. Test a check: XML request

<?xml version="1.0" encoding="utf-8"?>
<test_check>
  <type>remote.http</type>
  <details>
    <url>http://www.foo.com</url>
    <method>GET</method>
  </details>
  <monitoring_zones_poll>
    <monitoring_zone_id>mzA</monitoring_zone_id>
  </monitoring_zones_poll>
  <timeout>30</timeout>
  <target_alias>default</target_alias>
</test_check>

 

Example 5.20. Test a check: JSON request

{
    "type": "remote.http",
    "details": {
        "url": "http://www.foo.com",
        "method": "GET"
    },
    "monitoring_zones_poll": [
        "mzA"
    ],
    "timeout": 30,
    "target_alias": "default"
}

 5.5.2.2. Response

 

Example 5.21. Test a check: XML response

<?xml version="1.0" encoding="utf-8"?>
<checks_data>
  <check_data>
    <timestamp>1319222001982</timestamp>
    <monitoring_zone_id>mzxJ4L2IU</monitoring_zone_id>
    <available>true</available>
    <status>code=200,rt=0.257s,bytes=0</status>
    <metrics>
      <bytes>
        <type>i</type>
        <data>0</data>
      </bytes>
      <tt_firstbyte>
        <type>I</type>
        <data>257</data>
      </tt_firstbyte>
      <tt_connect>
        <type>I</type>
        <data>128</data>
      </tt_connect>
      <code>
        <type>s</type>
        <data>200</data>
      </code>
      <duration>
        <type>I</type>
        <data>257</data>
      </duration>
    </metrics>
  </check_data>
</checks_data>

 

Example 5.22. Test a check: JSON response

[
    {
        "timestamp": 1319222001982,
        "monitoring_zone_id": "mzxJ4L2IU",
        "available": true,
        "status": "code=200,rt=0.257s,bytes=0",
        "metrics": {
            "bytes": {
                "type": "i",
                "data": "0"
            },
            "tt_firstbyte": {
                "type": "I",
                "data": "257"
            },
            "tt_connect": {
                "type": "I",
                "data": "128"
            },
            "code": {
                "type": "s",
                "data": "200"
            },
            "duration": {
                "type": "I",
                "data": "257"
            }
        }
    }
]

 5.5.3. Test a check with debug

 
MethodURIDescription
POST/entities/{entityId}/test-check​{?debug}

Test a check and include extra check type-specific debugging information, if available.

Use ?debug=true to add extra check type-specific debugging information, if available.

This operation causes Rackspace Cloud Monitoring to attempt to run the check on the specified monitoring zones and return the results. This allows you to test the check parameters in a single step before the check is actually created in the system. This call also includes debug information. Currently debug information is only available for the remote.http check and includes the response body.

[Note]Note

Only first 512 KB of the response body is read. If the response body is longer, it is truncated to 512KB.

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

Request completed.

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.5.3.1. Request

 

Example 5.23. Test a check: XML request

<?xml version="1.0" encoding="utf-8"?>
<test_check>
  <type>remote.http</type>
  <details>
    <url>http://www.foo.com</url>
    <method>GET</method>
  </details>
  <monitoring_zones_poll>
    <monitoring_zone_id>mzA</monitoring_zone_id>
  </monitoring_zones_poll>
  <timeout>30</timeout>
  <target_alias>default</target_alias>
</test_check>

 

Example 5.24. Test a check: JSON request

{
    "type": "remote.http",
    "details": {
        "url": "http://www.foo.com",
        "method": "GET"
    },
    "monitoring_zones_poll": [
        "mzA"
    ],
    "timeout": 30,
    "target_alias": "default"
}

 5.5.3.2. Response

 

Example 5.25. Test a check: XML response

<?xml version="1.0" encoding="utf-8"?>
<checks_data>
  <check_data>
    <timestamp>1319222001982</timestamp>
    <monitoring_zone_id>mzxJ4L2IU</monitoring_zone_id>
    <available>true</available>
    <status>code=200,rt=0.257s,bytes=0</status>
    <metrics>
      <bytes>
        <type>i</type>
        <data>0</data>
      </bytes>
      <tt_firstbyte>
        <type>I</type>
        <data>257</data>
      </tt_firstbyte>
      <tt_connect>
        <type>I</type>
        <data>128</data>
      </tt_connect>
      <code>
        <type>s</type>
        <data>200</data>
      </code>
      <duration>
        <type>I</type>
        <data>257</data>
      </duration>
    </metrics>
    <debug_info>
      <body>&lt;html&gt;&lt;body&gt;My shiny website&lt;/body&gt;&lt;/html&gt;</body>
    </debug_info>
  </check_data>
</checks_data>

 

Example 5.26. Test a check: JSON response

[
    {
        "timestamp": 1319222001982,
        "monitoring_zone_id": "mzxJ4L2IU",
        "available": true,
        "status": "code=200,rt=0.257s,bytes=0",
        "metrics": {
            "bytes": {
                "type": "i",
                "data": "0"
            },
            "tt_firstbyte": {
                "type": "I",
                "data": "257"
            },
            "tt_connect": {
                "type": "I",
                "data": "128"
            },
            "code": {
                "type": "s",
                "data": "200"
            },
            "duration": {
                "type": "I",
                "data": "257"
            }
        },
        "debug_info": {
            "body": "<html><body>My shiny website</body></html>"
        }
    }
]

 5.5.4. Test an existing check

 
MethodURIDescription
POST/entities/{entityId}/checks/{checkId}/test

Test an existing check inline.

This operation causes Rackspace Cloud Monitoring to attempt to run the check on the specified monitoring zones and return the results. This allows you to test the check parameters.

[Note]Note

You can copy the results of a test check response and paste it directly into a test alarm.

[Note]Note

There is no request body, just posting to the url executes the request.

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

Request completed.

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.5.4.1. Request

This table shows the header parameters for the test an existing check request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This operation does not accept a request body.

 5.5.4.2. Response

 

Example 5.27. Test an existing check: XML response

<?xml version="1.0" encoding="utf-8"?>
<checks_data>
  <check_data>
    <timestamp>1319222001982</timestamp>
    <monitoring_zone_id>mzxJ4L2IU</monitoring_zone_id>
    <available>true</available>
    <status>code=200,rt=0.257s,bytes=0</status>
    <metrics>
      <bytes>
        <type>i</type>
        <data>0</data>
      </bytes>
      <tt_firstbyte>
        <type>I</type>
        <data>257</data>
      </tt_firstbyte>
      <tt_connect>
        <type>I</type>
        <data>128</data>
      </tt_connect>
      <code>
        <type>s</type>
        <data>200</data>
      </code>
      <duration>
        <type>I</type>
        <data>257</data>
      </duration>
    </metrics>
  </check_data>
</checks_data>

 

Example 5.28. Test an existing check: JSON response

[
    {
        "timestamp": 1319222001982,
        "monitoring_zone_id": "mzxJ4L2IU",
        "available": true,
        "status": "code=200,rt=0.257s,bytes=0",
        "metrics": {
            "bytes": {
                "type": "i",
                "data": "0"
            },
            "tt_firstbyte": {
                "type": "I",
                "data": "257"
            },
            "tt_connect": {
                "type": "I",
                "data": "128"
            },
            "code": {
                "type": "s",
                "data": "200"
            },
            "duration": {
                "type": "I",
                "data": "257"
            }
        }
    }
]

 5.5.5. List checks for entity

 
MethodURIDescription
GET/entities/{entityId}/checks

Lists the checks associated with a given entityId.

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.5.5.1. Request

This table shows the header parameters for the list checks for entity request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This operation does not accept a request body.

 5.5.5.2. Response

 

Example 5.29. List checks for entity: XML response

<?xml version="1.0" encoding="utf-8"?>
<container>
  <values>
    <check id="chAAAA">
      <label>Website check 1</label>
      <type>remote.http</type>
      <details>
        <url>http://www.foo.com</url>
        <method>GET</method>
        <follow_redirects>true</follow_redirects>
        <include_body>false</include_body>
      </details>
      <monitoring_zones_poll>
        <monitoring_zone_id>mzA</monitoring_zone_id>
      </monitoring_zones_poll>
      <timeout>30</timeout>
      <period>100</period>
      <target_alias>entity_ip_addresses_hash_key</target_alias>
    </check>
  </values>
  <metadata>
    <count>1</count>
    <limit>50</limit>
    <marker/>
    <next_marker/>
    <next_href/>
  </metadata>
</container>

 

Example 5.30. List checks for entity: JSON response

{
    "values": [
        {
            "id": "chAAAA",
            "label": "Website check 1",
            "type": "remote.http",
            "details": {
                "url": "http://www.foo.com",
                "method": "GET",
                "follow_redirects": true,
                "include_body": false
            },
            "monitoring_zones_poll": [
                "mzA"
            ],
            "timeout": 30,
            "period": 100,
            "target_alias": "entity_ip_addresses_hash_key"
        }
    ],
    "metadata": {
        "count": 1,
        "limit": 50,
        "marker": null,
        "next_marker": null,
        "next_href": null
    }
}

 5.5.6. Get check by ID

 
MethodURIDescription
GET/entities/{entityId}/checks/{checkId}

Returns information about the specified check.

Use this operation to retrieve the current state of a check.

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.

413Over Limit

The response body is too large.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.5.6.1. Request

This table shows the header parameters for the get check 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.5.6.2. Response

 

Example 5.31. Get check by ID: XML response

<?xml version="1.0" encoding="utf-8"?>
<check id="chAAAA">
  <label>Website check 1</label>
  <type>remote.http</type>
  <details>
    <url>http://www.foo.com</url>
    <method>GET</method>
    <follow_redirects>true</follow_redirects>
    <include_body>false</include_body>
  </details>
  <monitoring_zones_poll>
    <monitoring_zone_id>mzA</monitoring_zone_id>
  </monitoring_zones_poll>
  <timeout>30</timeout>
  <period>100</period>
  <target_alias>entity_ip_addresses_hash_key</target_alias>
</check>

 

Example 5.32. Get check by ID: JSON response

{
    "id": "chAAAA",
    "label": "Website check 1",
    "type": "remote.http",
    "details": {
        "url": "http://www.foo.com",
        "method": "GET",
        "follow_redirects": true,
        "include_body": false
    },
    "monitoring_zones_poll": [
        "mzA"
    ],
    "timeout": 30,
    "period": 100,
    "target_alias": "entity_ip_addresses_hash_key"
}

 5.5.7. Update check by ID

 
MethodURIDescription
PUT/entities/{entityId}/checks/{checkId}

Updates the properties for the specified check.

Updates the specified check with the attribute values included in the request body. You only have to specify the attributes that you want to update.

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.5.7.1. Request

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

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

 

Example 5.33. Update check: XML request

<?xml version="1.0" encoding="utf-8"?>
<check>
  <label>New check label</label>
  <timeout>10</timeout>
</check>

 

Example 5.34. Update check: JSON request

{
    "label": "New check label",
    "timeout": 10
}

 5.5.8. Delete a check by ID

 
MethodURIDescription
DELETE/entities/{entityId}/checks/{checkId}

Deletes a check from your account.

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.5.8.1. Request

This table shows the header parameters for the delete a check 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...