4.5. Checks

 4.5.1. Summary

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. When you create a new check in the monitoring system, you specify the following information:

  • A name for the check

  • The check's parent entity

  • The type of check you're creating

  • Details of the check

  • The monitoring zones that will launch the check

The attributes you use for creating checks, including optional parameters, are described in the following Attributes section. Create check provides an example of how to create a new check.

The check, as created, will 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).

[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.

 4.5.2. Attributes

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

 4.5.3. Available check types and fields

Look at the growing list of available check types here.

 4.5.4. Create Check

Verb URI Description
POST /entities/entityId/checks Create a new check and associate it with an entity using the parameters listed in Attributes

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

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

 

Example 4.17. Check create request: XML

<?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 4.18. Check create request: JSON

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


 4.5.5. Test check

Verb URI Description
POST /entities/entityId/test-check/ Test a check before creating it.

Normal Response Code: 200

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

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.

[Note]Note

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

 

Example 4.19. Test check request: XML

<?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 4.20. Test check request: JSON

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


 

Example 4.21. Test check response: XML

<?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 4.22. Test check response: JSON

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


 4.5.5.1. Test check and include debug information

Verb URI Description
POST /entities/entityId/test-check?debug=true Test a check and include extra check type-specific debugging information, if available.

Normal Response Code: 200

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

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.

 

Example 4.23. Test check request: XML

<?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 4.24. Test check request: JSON

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


 

Example 4.25. Test check with debug response: XML

<?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 4.26. Test Check with debug response: JSON

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


 4.5.6. Test existing check

Verb URI Description
POST /entities/entityId/checks/checkId/test Test a check inline.

Normal Response Code: 200

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

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.

 

Example 4.27. Test existing check response: XML

<?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 4.28. Test existing check response: JSON

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


 4.5.7. List checks

Verb URI Description
GET /entities/entityId/checks/ Lists the checks associated with a given entityId.

There are no parameters for this call.

Normal Response Code: 200

Error Response Codes: 401, 403, 500, 503

 

Example 4.29. List checks response: XML

<?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 4.30. List checks response: JSON

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

          

 4.5.8. Get check

Verb URI Description
GET /entities/entityId/checks/checkId Returns the specified check.

There are no parameters for this call.

Normal Response Code: 200

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

 

Example 4.31. Get check response: XML

<?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 4.32. Get check response: JSON

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

          

 4.5.9. Update checks

Verb URI Description
PUT /entities/entityId/checks/checkId Updates a check with the specified checkId.

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

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

[Note]Note

Updating monitoring zones can effect the billing of the product.

 

Example 4.33. Check update request: XML

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


 

Example 4.34. Check update request: JSON

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


 4.5.10. Delete checks

Verb URI Description
DELETE /entities/entityId/checks/checkId Deletes a check from your account.

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