Checks

A check is a foundational building block of the monitoring system. The check defines what to monitor and how to monitor. When you define a check, you specify attributes like the following:

  • the parts or pieces of the entity that you want to monitor,

  • monitoring frequency

  • number of monitoring zones originating the check

You can create up to 1000 checks.

After you create a check, you must create an alarm so that the check sends notifications when it is triggered. Alarms operate on a single check, and you can configure multiple alarms for a single check. For example, you might set up a check with two alarms to ensure that an HTTPS server is responding and that it has a valid certificatej.

Note

For more information, see the Check types reference.

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

Attributes used for all checks

Name

Description

Validation

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: Optional]

  • 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

Name

Description

Validation

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

  • IPv4 or IPv6

Use the following Check API operations to create, test, and manage checks and check configuration.

Create a check

POST /entities/{entityId}/checks

Create a new check in the monitoring system by using a valid set of attributes from the checks attributes table. For an example of creating some basic checks, see Creating a check in the Rackspace Cloud Monitoring Getting Started Guide.

A newly-created check does not trigger notifications until you create an alarm to generate notifications. You associate alarms with a single check. You can have multiple alarms for a check, for example “alert if an HTTPS server is not responding and if it has an invalid certificate,” but you cannot create a single alarm and associate it with multiple checks.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

201

Created

‘Location’ header contains a link to the newly created check.

400

Bad request

The system received an invalid value in a request.

401

Unauthorized

The system received a request from a user that is not authenticated.

403

Forbidden

The system received a request that the user is not authorized to make.

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Example Create 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"
}

Response

This operation does not return a response body.

Test a check

POST /entities/{entityId}/test-check

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

Note

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

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

Request completed.

400

Bad request

The system received an invalid value in a request.

401

Unauthorized

The system received a request from a user that is not authenticated.

403

Forbidden

The system received a request that the user is not authorized to make.

404

Not Found

The URL, entity, or account requested is not found in the system.

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request

The following table shows the header parameters for the request:

Name

Type

Description

entityId

String (Required)

The ID for the monitoring zone. Use the List entities operation to find the entityId if you don’t know it.

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Example Test check: JSON request

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

Response

Example Test 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"
            }
        }
    }
]

Test a check with debug

POST /entities/{entityId}/test-check

Test a check and include 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 enables 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 the first 512 KB of the response body is read. If the response body is longer, it is truncated to 512KB.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

Request completed.

400

Bad request

The system received an invalid value in a request.

401

Unauthorized

The system received a request from a user that is not authenticated.

403

Forbidden

The system received a request that the user is not authorized to make.

404

Not Found

The URL, entity, or account requested is not found in the system.

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request

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

Response

Example Test check with debug: 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>"
        }
    }
]

Test an existing check

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

Test an existing check inline.

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

Note

This operation does NOT cause the already-created check to be run, but rather creates a duplicate check with the same parameters as the original, and performs the test using that. You can copy the results of a test check response and paste it directly into a test alarm.

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

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

Request completed.

400

Bad request

The system received an invalid value in a request.

401

Unauthorized

The system received a request from a user that is not authenticated.

403

Forbidden

The system received a request that the user is not authorized to make.

404

Not Found

The URL, entity, or account requested is not found in the system.

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response

Example Test 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"
            }
        }
    }
]

List checks for an entity

GET /entities/{entityId}/checks

Lists the checks associated with a given entityId.

Use /checks?id=checkOneId & id=checkTwoId to filter the results to only include information about the specified checks.

This operation can be paginated. For information, see Paginated collections.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

The request completed.

401

Unauthorized

The system received a request from a user that is not authenticated.

403

Forbidden

The system received a request that the user is not authorized to make.

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response

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

Get a check by ID

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

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

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

The request completed.

401

Unauthorized

The system received a request from a user that is not authenticated.

403

Forbidden

The system received a request that the user is not authorized to make.

404

Not Found

The URL, entity, or account requested is not found in the system.

413

Over Limit

The response body is too large.

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response

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

Update a check by ID

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

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. Refer to the Check attributes table.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

204

OK

The server has fulfilled the request but does not need to return an entity- body.

400

Bad request

The system received an invalid value in a request.

401

Unauthorized

The system received a request from a user that is not authenticated.

403

Forbidden

The system received a request that the user is not authorized to make.

404

Not Found

The URL, entity, or account requested is not found in the system.

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Example Update check by ID: JSON request

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

Response

This operation does not return a response body.

Delete a check by ID

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

Deletes a check from your account.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

204

OK

The server has fulfilled the request. Does not return a response body.

401

Unauthorized

The system received a request from a user that is not authenticated.

403

Forbidden

The system received a request that the user is not authorized to make.

404

Not Found

The URL, entity, or account requested is not found in the system.

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response

This operation does not return a response body.