Quickstart for Cloud Monitoring#

Cloud Monitoring helps you keep a keen eye on all of your resources. You can monitor activity on websites, web servers, routers, load balancers, and more.

Concepts#

To use this service effectively, you should understand how these key ideas are used in this context:

agent

A monitoring daemon that resides on the server being monitored. The agent gathers metrics based on agent checks and pushes them to Cloud Monitoring.

alarm

Contains a set of rules that determine when the monitoring system sends a notification. You can create multiple alarms for the different check types associated with an entity

check

Contains the specific details of how you are monitoring the entity, such as which components of the entity to monitor, the monitoring frequency, and how many monitoring zones are launching the check.

entity

The object or resource that you want to monitor. An entity is commonly a web server, but it might also be a website, a web page, or a web service.

monitoring zone

The launch point of a check; a monitoring zone is a geographical region. When you create a check, you specify which monitoring zone(s) you want to launch the check from.

notification

An informational message sent to one or more addresses by the monitoring system when an alarm is triggered.

notification plan

Contains a set of notification rules to execute when an alarm is triggered. A notification plan can contain multiple notifications for Critical, Warning, and Ok states.

Authentication#

To use this service you have to authenticate first. To do this, you will need your Rackspace username and API key. Your username is the one you use to login to the Cloud Control Panel at http://mycloud.rackspace.com/.

To find your API key, use the instructions in View and reset your API key.

You can specify a default region. Here is a list of available regions:

  • DFW (Dallas-Fort Worth, TX, US)

  • HKG (Hong Kong, China)

  • IAD (Blacksburg, VA, US)

  • LON (London, England)

  • SYD (Sydney, Australia)

Some users have access to another region in ORD (Chicago, IL). New users will not have this region.

Once you have these pieces of information, you can pass them into the SDK by replacing {username}, {apiKey}, and {region} with your info:

CloudIdentity cloudIdentity = new CloudIdentity()
{
    APIKey = "{apikey}",
    Username = "{username}"
};
CloudMonitoringProvider cloudMonitoringProvider = new CloudMonitoringProvider(
      cloudIdentity,
      "{region}",
      null);
// Not currently supported by this SDK
// Not currently supported by this SDK
// Not currently supported by this SDK
require 'vendor/autoload.php';

use OpenCloud\Rackspace;

$client = new Rackspace(Rackspace::US_IDENTITY_ENDPOINT, array(
  'username' => '{username}',
  'apiKey'   => '{apiKey}'
));
import pyrax

pyrax.set_setting("identity_type", "rackspace")
pyrax.set_default_region('{region}')
pyrax.set_credentials('{username}', '{apiKey}')
cm = pyrax.cloud_monitoring
require 'fog'

@client = Fog::Rackspace::Monitoring.new(
  :rackspace_username => '{username}',
  :rackspace_api_key => '{apikey}',
  :rackspace_region => '{region}'
)
# {username}, {apiKey} below are placeholders, do not enclose '{}' when you replace them with actual credentials.

curl -s https://identity.api.rackspacecloud.com/v2.0/tokens -X 'POST' \
   -d '{"auth":{"RAX-KSKEY:apiKeyCredentials":{"username":"{username}", "apiKey":"{apiKey}"}}}' \
   -H "Content-Type: application/json" | python -m json.tool

# From the resulting json, set three environment variables: tenant, TOKEN and endpoint

export TENANT="{tenantId}"
export TOKEN="{tokenId}"
export ENDPOINT="{publicUrl}" # For Monitoring service

Use the API#

Some of the basic operations you can perform with this API are described below.

Workflow#

  • Create an entity to represent the item you want to monitor. For example, the entity might represent a website.

  • Attach a predefined check to the entity. For example, you could use the PING check to monitor your website’s public IP address.

  • Create notifications and notification plans. A notification lets you define an action which Cloud Monitoring uses to communicate with you when a problem occurs. Notification plans allow you to organize a set of several notifications, or actions.

  • Create alarms to specify which notifications get triggered.

Create entity#

To begin monitoring a resource, create an entity that represents the resource in the monitoring system:

NewEntityConfiguration entityConfiguration = new NewEntityConfiguration(
      "{entity_label}",
      null,
      null,
      null);
EntityId entityId = await cloudMonitoringProvider.CreateEntityAsync(
      entityConfiguration,
      CancellationToken.None);
// Not currently supported by this SDK
// Not currently supported by this SDK
// Not currently supported by this SDK
$service = $client->cloudMonitoringService('cloudMonitoring', '{region}');

$service->createEntity(array(
    'label' => '{entityLabel}',
    'ip_addresses' => array(
        'default' => '127.0.0.4',
        'b'       => '127.0.0.5',
        'c'       => '127.0.0.6',
        'test'    => '127.0.0.7'
    ),
    'metadata' => array(
        'foo'  => 'bar'
    )
));
entity = cm.create_entity(label="bestbox",
                          ip_addresses={"bestbox": "192.168.1.32"})
entity = @client.entities.create(:label => 'somehost.domain.com')
$ curl -X POST -d \
  '{
    "label": "{entityLabel}",
    "ip_addresses": {
        "entity_ip_addresses_hash_key": "{ipAddress1}",
        "b": "{ipAddress2}",
        "c": "{ipAddress3}",
        "test": "{ipAddress4}"
    }
  }' \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  $ENDPOINT/entities | python -m json.tool

List monitoring zones#

Before creating a check for the new entity, choose which monitoring zones to run the check from. Cloud Monitoring is divided into different monitoring zones. You may want to have a single server monitored from several monitoring zones to reduce the risk of false alarms and check the response time from different locations around the world. To see which zones are available to you:

ReadOnlyCollectionPage<MonitoringZone, MonitoringZoneId> monitoringZones
      = await cloudMonitoringProvider.ListMonitoringZonesAsync(
              null,
              null,
              CancellationToken.None);
// Not currently supported by this SDK
// Not currently supported by this SDK
// Not currently supported by this SDK
$zones = $service->getMonitoringZones();
zones = cm.list_monitoring_zones()
@client.list_monitoring_zones.body['values']
$ curl -X GET $ENDPOINT/monitoring_zones \
  -H "X-Auth-Token: $TOKEN" \
  -H "Accept: application/json" | python -m json.tool

Delete entity#

To delete a monitoring entity:

await cloudMonitoringProvider.RemoveEntityAsync({entity_id}, CancellationToken.None);
// Not currently supported by this SDK
// Not currently supported by this SDK
// Not currently supported by this SDK
$entity->delete();
entity.delete()
entity.destroy
$ curl -X DELETE $ENDPOINT/entities/{entityId} \
  -H "X-Auth-Token: $TOKEN"

Note: you cannot delete a monitoring entity until you have removed all its checks and alarms have been removed.

Create check#

Any entity that you create can have many checks, each monitoring a different aspect of the entity:

CheckTypeId checkTypeId = CheckTypeId.RemoteHttp;
CheckDetails details = new HttpCheckDetails(
        url: new Uri("http://docs.rackspace.com", UriKind.Absolute),
        authUser: default(string),
        authPassword: default(string),
        body: default(string),
        bodyMatches: default(IDictionary<string, string>),
        followRedirects: default(bool?),
        headers: default(IDictionary<string, string>),
        method: default(HttpMethod?),
        payload: default(string));

IEnumerable<MonitoringZoneId> monitoringZonesPoll = new[] { "{zone_id}" };
TimeSpan? timeout = null;
TimeSpan? period = null;
string targetAlias = null;
string targetHostname = "www.example.com";
TargetResolverType resolverType = TargetResolverType.IPv4;
IDictionary<string, string> metadata = null;
NewCheckConfiguration checkConfiguration =
      new NewCheckConfiguration(
              "{check_label}",
              checkTypeId,
              details,
              monitoringZonesPoll,
              timeout,
              period,
              targetAlias,
              targetHostname,
              resolverType,
              metadata);
Check check = await cloudMonitoringProvider.CreateCheckAsync(
      {entity_id},
      {check_configuration},
      CancellationToken.None);
// Not currently supported by this SDK
// Not currently supported by this SDK
// Not currently supported by this SDK
$params = array(
    'type'   => 'remote.http',
    'details' => array(
        'url'    => 'http://example.com',
        'method' => 'GET'
    ),
    'monitoring_zones_poll' => array('mzlon'),
    'period' => '100',
    'timeout' => '30',
    'target_alias' => 'default',
    'label'  => 'Website check 1'
);

// Test your params first
$testResponse = $entity->testNewCheckParams($params);

$body      = $testResponse[0];
$timestamp = $body->timestamp; // When was it executed?
$available = $body->available; // Was it available?
$status    = $body->status;    // Status code

// Now create it
$entity->createCheck($params);
check = cm.create_check(entity, label="sample_check", check_type="remote.ping",
                        details={}, monitoring_zones_poll=["mzdfw", "mzlon", "mzsyd"],
                        target_hostname="sample.hostname.com")
# List available check types. Note the "id" of the one you want to use.
@client.check_types.all

# :type is the String ID of the check type you wish to create.
# :target_hostname is the host to be monitored. :target_alias can be specified instead, if you have ip addresses
#   configured in the entity.
# :monitoring_zones_poll is an Array listing the String ids of the monitoring zones from which this check should be
#   performed.
check = entity.checks.create(
  :type => 'remote.ping',
  :target_hostname => 'sample.hostname.com',
  :monitoring_zones_poll => ['{monitoringZoneId}']
)
$ curl -X POST -d \
  '{
    "label": "{checkLabel}",
    "type": "remote.http",
    "details": {
        "url": "{remoteUrl}",
        "method": "{httpMethod}"
    },
    "timeout": 30,
    "period": 100,
  }' \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  $ENDPOINT/entities/{entityId}/checks | python -m json.tool

List checks#

To list all the monitoring checks for a given entity:

ReadOnlyCollectionPage<Check, CheckId> checks =
      await cloudMonitoringProvider.ListChecksAsync(
              {entity_id},
              null,
              null,
              CancellationToken.None);
// Not currently supported by this SDK
// Not currently supported by this SDK
// Not currently supported by this SDK
$checks = $entity->getChecks();
entity.list_checks()
entity.checks.all
$ curl -X GET $ENDPOINT/entities/{entityId}/checks \
  -H "X-Auth-Token: $TOKEN" \
  -H "Accept: application/json" | python -m json.tool

Delete check#

To remove a check:

await cloudMonitoringProvider.RemoveCheckAsync({entity_id}, {check_id}, CancellationToken.None);
// Not currently supported by this SDK
// Not currently supported by this SDK
// Not currently supported by this SDK
$check->delete();
check.delete()
check.destroy
$ curl -X DELETE $ENDPOINT/entities/{entityId}/checks/{checkId} \
  -H "X-Auth-Token: $TOKEN"

Notifications and alarms#

In most cases you, and perhaps several people on your team, will be interested in multiple alerts. Cloud Monitoring lets you set up notification plans that can be shared between multiple alerts.

Create notification#

To create a notification plan:

NotificationTypeId notificationTypeId = NotificationTypeId.Webhook;
NotificationDetails notificationDetails = new WebhookNotificationDetails(
      new Uri("http://example.com"));
NewNotificationConfiguration configuration =
      new NewNotificationConfiguration(
              "{notification_label}",
              notificationTypeId,
              notificationDetails);
NotificationId notificationId =
      await cloudMonitoringProvider.CreateNotificationAsync(
              configuration,
              CancellationToken.None);
// Not currently supported by this SDK
// Not currently supported by this SDK
// Not currently supported by this SDK
$notification = $service->getNotification();

$params = array(
    'label' => 'My webhook #1',
    'type'  => 'webhook',
    'details' => array(
        'url' => 'http://example.com'
    )
);

// Test these params
$response = $notification->testParams($params);

$status = $response->status; // Was it successful?

// Now create the notification
$notification->create($params);
warning = cm.create_notification("email",
                                 label="Hey OPS, check this out.",
                                 details={"address": "{emailAddress}"})

critical = cm.create_notification("email",
                                  label="This is critical",
                                  details={"address": "{emailAddress}"})

plan = cm.create_notification_plan(label="default",
                                   warning_state=warning,
                                   critical_state=critical)
# :label is a String that's a friendly name for the notification.
# :type is one of 'webhook', 'email', or 'pagerduty'.
# :details is a :type-specific Hash of configuration options.
notification = @client.notifications.create(
  :label => 'tell the world',
  :type => 'email',
  :details => { :address => '{emailAddress}' }
)
$ curl -X POST -d \
  '{
    "label": "{webhookNotificationLabel}",
    "type": "webhook",
    "details": {
      "url": "{webhookUrl}"
    }
  }' \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  $ENDPOINT/notifications | python -m json.tool

Create alarm#

To create an alarm for an entity:

string alarmName = "{alarm_name}";
string criteria = null;
bool? enabled = null;
IDictionary<string, string> alarmMetadata = null;
NewAlarmConfiguration alarmConfiguration =
      new NewAlarmConfiguration(
              {check_id},
              {notification_plan_id},
              criteria,
              enabled,
              alarmName,
              alarmMetadata);
AlarmId alarmId =
      await cloudMonitoringProvider.CreateAlarmAsync(
              {entity_id},
              alarmConfiguration,
              CancellationToken.None);
// Not currently supported by this SDK
// Not currently supported by this SDK
// Not currently supported by this SDK
$alarm = $entity->getAlarm();
$alarm->create(array(
    'check_id' => '{checkId}',
    'criteria' => 'if (metric["duration"] >= 2) { return new AlarmStatus(OK); } return new AlarmStatus(CRITICAL);',
    'notification_plan_id' => '{notificationPlanId}'
));
alarm = cm.create_alarm(entity, check, plan,
                        ("if (rate(metric['average']) > 10) {"
                         " return new AlarmStatus(WARNING); "
                         "} return new AlarmStatus(OK);"))
# To list known notification plans:

@client.list_notification_plans.body['values']

alarm = entity.alarms.create(
  :check => check,
  :notification_plan_id => '{notificationPlanId}'
)
$ curl -X POST -d \
  '{
    "check_id": "{checkId}",
    "criteria": "{alarmCriteria}",
    "notification_plan_id": "{notificationPlanId}"
  }' \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  $ENDPOINT/entities/{entityId}/alarms | python -m json.tool

Delete alarm#

To delete an alarm:

await cloudMonitoringProvider.RemoveAlarmAsync({entity_id}, {alarm_id}, CancellationToken.None);
// Not currently supported by this SDK
// Not currently supported by this SDK
// Not currently supported by this SDK
$alarm->delete();
alarm.delete()
alarm.destroy
$ curl -X DELETE $ENDPOINT/entities/{entityId}/alarms/{alarmId} \
  -H "X-Auth-Token: $TOKEN"

More information#

This quickstart is intentionally brief, demonstrating only a few basic operations. To learn more about interacting with Rackspace cloud services, explore the following sites: