4.5. Checks

4.5.1. Summary
4.5.2. Attributes
4.5.3. Available Check Types and Fields
4.5.4. Create Check
4.5.5. Test Check
4.5.6. Test Existing Check
4.5.7. List Checks
4.5.8. Get Check
4.5.9. Update Checks
4.5.10. Delete 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. 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
	Look at the available list of check types and their fields here.

	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
Name	Description	Validation
Attributes used for all checks
type	The type of check.	Immutable String between 1 and 25 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 String between 1 and 256 characters long
target_resolver	Determines how to resolve the check target.	Optional One of (IPv4, IPv6)

	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>default</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": "default"
}

4.5.5. Test Check

4.5.5.1. Test Check And Include Debug Information

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

	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
	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
	You can copy the results of a test check response and paste it directly into a test alarm.

	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>default</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": "default"
        }
    ],
    "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>default</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": "default"
}

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

Legal notices