Configure distribution metrics
https://www.gstatic.com/devrel-devsite/prod/vd185cef2092d5507cf5d5de6d49d6afd8eb38fe69b728d88979eb4a70550ff03/cloud/images/favicons/onecloud/favicon.ico
Google Cloud
This page explains how to create distribution-type log-based metrics using the Google Cloud console, the Logging API, and the Google Cloud CLI. For an overall view of log-based metrics, go to Overview of log-based metrics.

Overview

Distribution metrics require both a filter to select the relevant log entries and a value extractor to grab the numeric value for the distribution. The value extractor is the same kind as is used for user-defined labels.

A distribution metric records the statistical distribution of the extracted values in histogram buckets. The extracted values are not recorded individually, but their distribution across the configured buckets are recorded, along with the count, mean, and sum of squared deviation of the values. You can use the default layout of histogram buckets in your distribution or you can fine-tune the buckets' boundaries to approximately capture the values.

For more information on viewing and interpreting distribution metrics, see Distribution metrics.

Before you begin

To use log-based metrics, you must have a Google Cloud project with billing enabled:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Ensure that your Identity and Access Management role includes the permissions required to create and view log-based metrics, and to create alerting policies. For details, see Permissions for log-based metrics.

Create a distribution metric

The metric counts the log entries identified by a filter you provide. You can use regular expressions in your filter, and we recommend that you include a resource type. The length of a filter can't exceed 20,000 characters.

Don't put sensitive information in the filter. Filters are treated as service data.

Histogram buckets

Distribution metrics include a histogram that counts the number of values that fall in specified ranges (buckets). You can have up to 200 buckets in a distribution metric.

Each bucket has two boundary values, L and H, that define the lowest and highest values covered by the bucket. The width of the bucket is H - L. Since there cannot be gaps between buckets, the lower boundary of one bucket is the same as the higher boundary of the previous bucket, and so forth. So that the boundaries don't fall into more than one bucket, a bucket includes its lower boundary; its higher boundary belongs to the next bucket.

All bucket layouts can be specified by listing, in increasing order, the boundary values between individual buckets. The first bucket is the underflow bucket, which counts values less than the first boundary. The last bucket is the overflow bucket, which counts values greater than or equal to the last boundary. The other buckets count values greater than or equal to their lower boundary and less than their upper boundary. If there are n boundary values, then there are n+1 buckets. Excluding the underflow and overflow buckets, there are n-1 finite buckets.

There are three different ways to specify the boundaries between histogram buckets for distribution metrics. You either specify a formula for the boundary values, or you list the boundary values:

Linear(offset, width, i): Every bucket has the same width. The boundaries are offset + width * i, for i=0,1,2,...,N. For more information on linear buckets, see the API reference.

Exponential(scale, growth_factor, i): Bucket widths increase for higher values. The boundaries are scale * growth_factori, for i=0,1,2,...,N. For more information on exponential buckets, see the API reference.

Explicit: You list all the boundaries for the buckets in the bounds array. Bucket i has these boundaries:

Upper bound: bounds[*i*] for (0 <= *i* < *N*-1) Lower bound: bounds[*i* - 1] for (1 <= *i* < *N*)

For more information on explicit buckets, see the API reference.

How you specify your histogram buckets is explained in the following section:

New metric latency

Your new metric appears in the list of metrics and in the relevant Monitoring menus right away. However, it might take up to a minute for the metric to start collecting data for the matching log entries.

Inspect distribution metrics

To list the user-defined log-based metrics in your Google Cloud project or to inspect a particular metric in your Google Cloud project, do the following:

You can edit a user-defined log-based metric to change its description, filter, and the names of fields referenced in the metric. You can add new labels to the metric and you can change the regular expressions used to extract values for the metric and its labels. If you're using a bucket-scoped metric, you can also update the metric's bucket.

You can't change the names or types of user-defined log-based metrics or their labels, and you can't delete existing labels in a log-based metric.

To edit a log-based metric, do the following:

Delete distribution metrics

To delete a user-defined log-based metric, do the following: