Using 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 Monitoring uptime-check dashboards.

This page shows you how to do the following:

• Review the status of your uptime checks.
• Use uptime checks in alerting policies.
• Get a list of IP addresses used by uptime checks.

To create, update, and delete your uptime checks, see the Managing Uptime Checks page. You can have up to 100 uptime checks per Stackdriver account.

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

Reviewing uptime checks

Monitoring has an overview page that displays all your uptime checks, and detailed dashboards for individual checks.

Overview

To see the overview, go to Uptime Checks > Uptime Checks Overview:

Go to Uptime Checks Overview

For each uptime check, you can see the last check result from each location, as shown in the following screenshot:

Note: It is normal for the dashboard to report "no data available" for newly-created uptime checks. This message goes away when the data arrives.

Dashboards

Beta

This is a Beta release of the Stackdriver Uptime Checks Dashboard. This feature is not covered by any SLA or deprecation policy and might be subject to backward-incompatible changes.

To get the detailed status of a single uptime check, click on any of the checks in the overview or in the list in the Uptime Checks menu in the left-side navigation. Following is a sample dashboard:

The Check config region includes a description of the uptime check, including the Check ID. This ID is assigned when the uptime check is created. The value corresponds to the [UPTIME_CHECK_ID] value in API calls.

API

Beta

This is a Beta release of the Uptime Config API. This feature is not covered by any SLA or deprecation policy and might be subject to backward-incompatible changes.

To retrieve your existing uptime check configurations, use projects.uptimeCheckConfigs.list.

In the API, uptime checks are identified by their [UPTIME_CHECK_ID], which is a respelling of the uptime check's name. For example, the dashboard check name "my uptime check" might become the ID "my-uptime-check", or the mapping might be more complicated.

You assign the display name that you see in the Uptime Overview in the Stackdriver Monitoring console.

Uptime percentage

The Uptime value is a percentage calculated as (S/T)*100, where S is the number of successful check responses and T is the total number of check responses, from all locations.

For group checks, the values of S and T are summed across all current group members.

For example, over a 25 minute period, an uptime check with a default configuration would get 25 requests from each of 6 locations, for a total of 150 requests. If the dashboard reports an 83.3% uptime, that means 25 of 150 requests failed.

Using uptime checks in alerting policies

For details about alerting policies, see Introduction to Alerting.

To create an alerting policy that will trigger when an uptime check fails, do the following:

1. Create the uptime check. For details, see Creating an uptime check.

2. Go to Alerting > Create a Policy:

   Go to Create New Alerting Policy

3. In the Conditions Section, choose the condition Basic Health > Uptime Check Health.

4. Choose the uptime check to use and supply any other needed information.

5. Complete the alerting policy.

Getting uptime-check IP addresses

If you are checking a service that is behind a firewall, you can configure your service's firewall to accept traffic from the current set of IP addresses used for uptime checking. To get the IP addresses, use the following instructions:

Console

1. Go to the Uptime Checks page for your project.

1. In the More menu next to Add Uptime Check, select Download Source IPs:

   

API

Beta

This is a Beta release of the Uptime Config API. This feature is not covered by any SLA or deprecation policy and might be subject to backward-incompatible changes.

1. Call the uptimeCheckIps.list method of the Monitoring API.

2. The method returns the following information for each IP address:

   • The region: USA, EUROPE, SOUTH_AMERICA, or ASIA_PACIFIC.
   • A more specific location within the region.
   • The IP address, not a range, in IPv4 or IPv6 format.

C#

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

View on GitHub Feedback

public static object ListUptimeCheckIps()
{
    var client = UptimeCheckServiceClient.Create();
    var ips = client.ListUptimeCheckIps(new ListUptimeCheckIpsRequest());
    foreach (UptimeCheckIp ip in ips)
    {
        Console.WriteLine("{0,20} {1}", ip.IpAddress, ip.Location);
    }
    return 0;
}

Java

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

View on GitHub Feedback

private static void listUptimeCheckIPs() throws IOException {
  try (UptimeCheckServiceClient client = UptimeCheckServiceClient.create()) {
    ListUptimeCheckIpsPagedResponse response =
        client.listUptimeCheckIps(ListUptimeCheckIpsRequest.newBuilder().build());
    for (UptimeCheckIp config : response.iterateAll()) {
      System.out.println(config.getRegion() + " - " + config.getIpAddress());
    }
  } catch (Exception e) {
    usage("Exception listing uptime IPs: " + e.toString());
    throw e;
  }
}

Go

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

View on GitHub Feedback

// listIPs is an example of listing uptime check IPs.
func listIPs(w io.Writer) error {
	ctx := context.Background()
	client, err := monitoring.NewUptimeCheckClient(ctx)
	if err != nil {
		return fmt.Errorf("NewUptimeCheckClient: %v", err)
	}
	defer client.Close()
	req := &monitoringpb.ListUptimeCheckIpsRequest{}
	it := client.ListUptimeCheckIps(ctx, req)
	for {
		config, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("ListUptimeCheckIps: %v", err)
		}
		fmt.Fprintln(w, config)
	}
	fmt.Fprintln(w, "Done listing uptime check IPs")
	return nil
}

Node.js

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

View on GitHub Feedback

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

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

// List uptime check IPs
client
  .listUptimeCheckIps()
  .then(results => {
    const uptimeCheckIps = results[0];
    uptimeCheckIps.forEach(uptimeCheckIp => {
      console.log(
        uptimeCheckIp.region,
        uptimeCheckIp.location,
        uptimeCheckIp.ipAddress
      );
    });
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

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

View on GitHub Feedback

use Google\Cloud\Monitoring\V3\UptimeCheckServiceClient;

/**
 * Example:
 * ```
 * list_uptime_check_ips($projectId);
 * ```
 */
function list_uptime_check_ips($projectId)
{
    $uptimeCheckClient = new UptimeCheckServiceClient([
        'projectId' => $projectId,
    ]);

    $pages = $uptimeCheckClient->listUptimeCheckIps();

    foreach ($pages->iteratePages() as $page) {
        $ips = $page->getResponseObject()->getUptimeCheckIps();
        foreach ($ips as $ip) {
            printf(
                'ip address: %s, region: %s, location: %s' . PHP_EOL,
                $ip->getIpAddress(),
                $ip->getRegion(),
                $ip->getLocation()
            );
        }
    }
}

Python

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

View on GitHub Feedback

def list_uptime_check_ips():
    client = monitoring_v3.UptimeCheckServiceClient()
    ips = client.list_uptime_check_ips()
    print(tabulate.tabulate(
        [(ip.region, ip.location, ip.ip_address) for ip in ips],
        ('region', 'location', 'ip_address')
    ))

Ruby

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

View on GitHub Feedback

def list_ips
  require "google/cloud/monitoring/v3"
  client = Google::Cloud::Monitoring::V3::UptimeCheck.new

  # Iterate over all results.
  client.list_uptime_check_ips.each do |element|
    puts "#{element.location} #{element.ip_address}"
  end
end

The returned information typically contains about 20 IP addresses. Uptime checks can come from any of the IP addresses, but only one address from each geographic location is used for each time interval. The geographic locations are listed in the uptime checks dashboard, shown in the previous section. You can also use free, web-based services to identify the registered locations of the IP addresses you downloaded.

The IP addresses used by uptime checking might change, but typically not more than once per quarter and not without an announcement.

Identifying uptime check traffic

You can identify requests from the uptime-check servers by the following information in your service's request logs:

• ip: The ip field contains one of the addresses used by the uptime-check servers. See Getting IP addresses.

• User-Agent: The User-Agent header value is always the following:

  GoogleStackdriverMonitoring-UptimeChecks(https://cloud.google.com/monitoring)
  

  Specifying a User-Agent custom header results in a form validation error and prevents the check configuration from being saved.