Managing Uptime Checks

Stackdriver can verify the availability of your service by accessing it from locations around the world. You can use the results from these uptime checks in your alerting policies, or you can directly monitor the results in the Stackdriver Monitoring uptime-check dashboards.

This page shows you how to do the following:

  • Create a new uptime check.
  • List your existing uptime checks.
  • Edit an uptime check.
  • Delete an uptime check.

To view the status of your uptime checks, or to get a list of the IP addresses that might be used to perform uptime checks, see the Using Uptime Checks page.

Before you begin

Your use of uptime checks is affected by your Stackdriver service tier and by any firewalls protecting your service.

Service tiers. Uptime checks are available to both Basic Tier and Premium Tier Stackdriver accounts, but uptime checks in Premium Tier accounts have some added information, including the Uptime Percentage value for individual checks. For more information about service tiers, see Stackdriver Pricing.

Firewalls. If the resource you are checking is not publicly available, you must configure the resource's firewall to permit incoming traffic from the uptime-check servers. See Getting IP addresses to download a list of the IP addresses.

Creating uptime checks

This section explains how to create and configure uptime checks.

Console

  1. In the Stackdriver Monitoring Console, go to Uptime Checks: for your

    Go to Uptime Checks

  2. Click Add Uptime Check in the top-right area of the page. You see the New Uptime Check panel:

    Create uptime check

  3. Fill in the basic information for the check, as described in Basic options on this page.

  4. Optionally click Advanced options at the bottom of the form. For details, see Advanced options on this page.

  5. Click Test. If your uptime check fails, see the Check failures section below, correct your configuration, and repeat the test.

  6. Click Save.

API

Call the projects.uptimeCheckConfigs.create method. Set the method's parameters as follows:

  • parent: Required. This must be the name of the project in which to create the uptime check. The format is:

    projects/[PROJECT_ID]
    
  • The request body must contain an UptimeCheckConfig object for the new new uptime check. The fields in the object are explained in the Basic options and Advanced options sections on this page.

    The name field of the configuration object should be left blank. It will be set in the returned configuration object.

The create method returns the UptimeCheckConfig object for the new configuration.

If the created uptime configuration does not work as expected, see the Check failures section on this page.

Node.js

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

// Imports the Google Cloud client library
const monitoring = require('@google-cloud/monitoring');

// Creates a client
const client = new monitoring.UptimeCheckServiceClient();

/**
 * TODO(developer): Uncomment and edit the following lines of code.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const gceInstanceId = 'my-instance';

const request = {
  // i.e. parent: 'projects/my-project-id'
  parent: client.projectPath(projectId),
  uptimeCheckConfig: {
    displayName: 'My GCE Instance Uptime Check',
    monitoredResource: {
      // See the Uptime Check docs for supported MonitoredResource types
      type: 'gce_instance',
      labels: {instance_id: gceInstanceId},
    },
    httpCheck: {path: '/', port: 80},
    timeout: {seconds: 10},
    period: {seconds: 300},
  },
};

// Creates an uptime check config for a GCE instance
client
  .createUptimeCheckConfig(request)
  .then(results => {
    const uptimeCheckConfig = results[0];

    console.log('Uptime check created:');
    console.log(`ID: ${uptimeCheckConfig.name}`);
    console.log(`Display Name: ${uptimeCheckConfig.displayName}`);
    console.log(`Resource: %j`, uptimeCheckConfig.monitoredResource);
    console.log(`Period: %j`, uptimeCheckConfig.period);
    console.log(`Timeout: %j`, uptimeCheckConfig.timeout);
    console.log(`Check type: ${uptimeCheckConfig.check_request_type}`);
    console.log(
      `Check: %j`,
      uptimeCheckConfig.httpCheck || uptimeCheckConfig.tcpCheck
    );
    console.log(
      `Content matchers: ${uptimeCheckConfig.contentMatchers
        .map(matcher => matcher.content)
        .join(', ')}`
    );
    console.log(`Regions: ${uptimeCheckConfig.selectedRegions.join(', ')}`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

There can be a delay of up to 25 minutes before the uptime check results start to flow into Stackdriver Monitoring. During that time, the uptime check dashboard reports the status as "no data available."

Basic options

To create a new uptime check, you specify values for the uptime check's configuration. When creating the uptime check in the Stackdriver Monitoring Console, you fill in a form. When creating the uptime check in the API, you supply the corresponding parameters to an UptimeCheckConfig object.

  1. Title: A name for your check. For example: Example.com uptime check.

  2. Check Type: Choose a protocol: HTTP, HTTPS, or TCP. For example, choose HTTP.

  3. Resource type: Choose one of the following resource types. For example: URL:

    • App Engine: Google App Engine applications (modules).
    • Elastic Load Balancer: AWS load balancer.
    • Instance: Compute Engine or AWS EC2 instances.
    • URL: Any hostname and path.
  4. Complete the connection information, depending on your check type and resource type:

    • Applies to (App Engine, ELB, or Instance): You can apply your uptime check to a single resource or to a group of resources, such as "All instances." If you choose a single resource, pick one from your existing resources as listed in the menu.

    • Module (App Engine): Specify your application module.

    • Hostname (All but App Engine): Specify your service's host name. For example, enter example.com.

    • Path (HTTP, HTTPS): Enter a path within your host or resource or use the default path. For example, leave this field blank.

    • Port (TCP): Choose a port for the connection.

    • Response content contains the text (TCP): Fill in a string whose presence in the check response indicates success.

  5. Check every: 1, 5, 10, or 15 minutes. For example, choose 5 minutes. Each geographic location attempts to reach your service every 5 minutes. Using the default six locations, your service would see an average of 1.2 requests per minute.

Advanced options

The Advanced options section applies to HTTP, HTTPS, and TCP check types. These settings are optional and vary by check type:

  • HTTP Host Header: Fill this in to check virtual hosts.

  • Port: Specify a port number.

  • Response content contains the text: Fill in a string whose presence in the check response indicates success. The HTTP status code is also used to determine success and failure.

  • Locations: Select the applicable geographic regions where your check receives requests. Enough regions need to be selected so that at least three locations are active. New checker locations in selected regions automatically send requests to the configured destinations. To always send requests from all available locations, select "Global," the default.

  • Custom Headers: Supply custom headers, and encrypt them if necessary. Encryption causes the headers' values to be hidden in the form. Use encryption for headers related to authentication that you do not want to be seen by other members of your team.

  • Healthcheck Timeout: Specify a timeout, from 1 to 60 seconds. Uptime checks that do not get a response within this period are considered failures.

  • Authentication: Provide a single username and password.

Check failures

When you create an uptime check in the Stackdriver Monitoring Console, you are given the option to test the configuration before you save it. Following are some possible causes of failure:

  • Connection Error - Refused: If you are using the default HTTP connection type, check that you have a web server installed that is responding to HTTP requests. This can happen on a new instance if you have not installed a web server; see the Quickstart. If you use an HTTPS connection type, you might have to perform additional configuration steps. For firewall issues, see Getting IP addresses.
  • Name or service not found: The host name might be incorrect.
  • 403 Forbidden: The service is returning an error code to the uptime checker. For example, the default Apache web server configuration returns this code under Amazon Linux, but it returns code 200 (Success) under some other Linux versions. See the LAMP tutorial for Amazon Linux or your web server's documentation.
  • 404 Not found: The path might be incorrect.
  • 408 Request timeout, or no response: The port number might be incorrect, the service might not be running, or the service might be inaccessible. Check that your firewall allows traffic from the uptime servers; see Getting IP addresses. The timeout limit is specified in the Healthcheck part of Advanced Options.

Listing uptime checks

To list your current uptime checks, do the following:

Console

The Uptime Checks Overview page provides a list of your uptime checks.

Clicking on one of the uptime checks will show more detail about the check.

API

To get a list of your uptime configurations, call the projects.uptimeCheckConfigs.list method. Specify the following parameters:

  • parent: The project whose uptime checks you want to list. The format is:

    projects/[PROJECT_ID]
    

To get a specific uptime check, call the projects.uptimeCheckConfigs.get method. Specify the following parameter:

  • name: The full name of the uptime check configuration.

    projects/[PROJECT_ID]/uptimeCheckConfigs/[UPTIME_CHECK_ID]
    

    You can get the [UPTIME_CHECK_ID] from the response of a create or list method. The ID is not shown in the Stackdriver Monitoring Console.

Node.js

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

// Imports the Google Cloud client library
const monitoring = require('@google-cloud/monitoring');

// Creates a client
const client = new monitoring.UptimeCheckServiceClient();

/**
 * TODO(developer): Uncomment and edit the following lines of code.
 */
// const projectId = 'YOUR_PROJECT_ID';

const request = {
  parent: client.projectPath(projectId),
};

// Retrieves an uptime check config
client
  .listUptimeCheckConfigs(request)
  .then(results => {
    const uptimeCheckConfigs = results[0];

    uptimeCheckConfigs.forEach(uptimeCheckConfig => {
      console.log(`ID: ${uptimeCheckConfig.name}`);
      console.log(`  Display Name: ${uptimeCheckConfig.displayName}`);
      console.log(`  Resource: %j`, uptimeCheckConfig.monitoredResource);
      console.log(`  Period: %j`, uptimeCheckConfig.period);
      console.log(`  Timeout: %j`, uptimeCheckConfig.timeout);
      console.log(`  Check type: ${uptimeCheckConfig.check_request_type}`);
      console.log(
        `  Check: %j`,
        uptimeCheckConfig.httpCheck || uptimeCheckConfig.tcpCheck
      );
      console.log(
        `  Content matchers: ${uptimeCheckConfig.contentMatchers
          .map(matcher => matcher.content)
          .join(', ')}`
      );
      console.log(
        `  Regions: ${uptimeCheckConfig.selectedRegions.join(', ')}`
      );
    });
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

You can also retrieve a single uptime check:

Node.js

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

// Imports the Google Cloud client library
const monitoring = require('@google-cloud/monitoring');

// Creates a client
const client = new monitoring.UptimeCheckServiceClient();

/**
 * TODO(developer): Uncomment and edit the following lines of code.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const uptimeCheckConfigId = 'YOUR_UPTIME_CHECK_CONFIG_ID';

const request = {
  // i.e. name: 'projects/my-project-id/uptimeCheckConfigs/My-Uptime-Check
  name: client.uptimeCheckConfigPath(projectId, uptimeCheckConfigId),
};

console.log(`Retrieving ${request.name}`);

// Retrieves an uptime check config
client
  .getUptimeCheckConfig(request)
  .then(results => {
    const uptimeCheckConfig = results[0];

    console.log(`ID: ${uptimeCheckConfig.name}`);
    console.log(`Display Name: ${uptimeCheckConfig.displayName}`);
    console.log(`Resource: %j`, uptimeCheckConfig.monitoredResource);
    console.log(`Period: %j`, uptimeCheckConfig.period);
    console.log(`Timeout: %j`, uptimeCheckConfig.timeout);
    console.log(`Check type: ${uptimeCheckConfig.check_request_type}`);
    console.log(
      `Check: %j`,
      uptimeCheckConfig.httpCheck || uptimeCheckConfig.tcpCheck
    );
    console.log(
      `Content matchers: ${uptimeCheckConfig.contentMatchers
        .map(matcher => matcher.content)
        .join(', ')}`
    );
    console.log(`Regions: ${uptimeCheckConfig.selectedRegions.join(', ')}`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

Editing uptime checks

To edit an uptime check, do the following:

Console

  1. In the Uptime Checks Overview, click Edit in the menu on the right side of your uptime check's summary.

    Alternatively, in the dashboard for your uptime check, choose Edit Uptime Check from the menu at the top-right of the page.

  2. Change the fields as needed. Click Test to see that the check works. If the test fails, see Check failures for possible causes.

  3. Click Save.

API

Call the projects.uptimeCheckConfigs.patch method. Set the parameters to the method as follows:

  • uptimeCheckConfig.name: Required. This is part of the REST URL. It is the resource name of the uptime check to edit:

    projects/[PROJECT_ID]/uptimeCheckConfigs/[UPTIME_CHECK_ID]
    

    You can get the [UPTIME_CHECK_ID] from the response of a create or list method. The ID is not shown in the Stackdriver Monitoring Console.

  • updateMask: Optional. This is a query parameter: ?updateMask=[FIELD_LIST]. [FIELD_LIST] is a comma-separated list of fields in the UptimeCheckConfig object that should be changed. For example:

    "resource.type,httpCheck.path"
    
  • The request body must contain an UptimeCheckConfig with the new field values.

If updateMask is set, then only the fields listed in updateMask replace the corresponding fields in the existing configuration.

If updateMask is not set, then the configuration in the request body replaces the entire existing configuration.

The patch method returns the UptimeCheckConfig object for the altered configuration.

There can be a delay of up to 25 minutes before you see the new uptime check results. During that time, the results of the former uptime check is displayed in the dashboards and is used in alerting policies.

Deleting uptime checks

Before deleting an uptime check, remove the check from any alerting policies that use it. If you do not remove the uptime check, the alerting policy ignores the missing uptime check. The policy does not create an incident for the missing check.

To delete an uptime check, do the following:

Console

In the Uptime Checks Overview, select Delete from the menu on the right side of your uptime check.

Alternatively, in the detail page for your uptime check, choose Delete Uptime Check from the menu at the top-right of the page.

API

Call the projects.uptimeCheckConfigs.delete method. Fill out the parameter as follows:

  • name: Required. This is the resource name of the uptime check configuration to delete:

    projects/[PROJECT_ID]/uptimeCheckConfigs/[UPTIME_CHECK_ID]
    

    You can get the [UPTIME_CHECK_ID] from the response of a create or list method. The ID is not shown in the Stackdriver Monitoring Console.

Node.js

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

// Imports the Google Cloud client library
const monitoring = require('@google-cloud/monitoring');

// Creates a client
const client = new monitoring.UptimeCheckServiceClient();

/**
 * TODO(developer): Uncomment and edit the following lines of code.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const uptimeCheckConfigId = 'YOUR_UPTIME_CHECK_CONFIG_ID';

const request = {
  // i.e. name: 'projects/my-project-id/uptimeCheckConfigs/My-Uptime-Check
  name: client.uptimeCheckConfigPath(projectId, uptimeCheckConfigId),
};

console.log(`Deleting ${request.name}`);

// Delete an uptime check config
client
  .deleteUptimeCheckConfig(request)
  .then(() => {
    console.log(`${request.name} deleted.`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Stackdriver Monitoring