Log-based metrics overview

This page provides a conceptual overview of log-based metrics.

Log-based metrics derive metric data from the content of log entries. For example, the metrics can record the number of log entries containing particular messages, or they can extract latency information reported in log entries. You can use log-based metrics in Cloud Monitoring charts and alerting policies.

There are two kinds of log-based metrics:

  • System-defined log-based metrics, provided by Cloud Logging for use by all Google Cloud projects.

    System-defined log-based metrics are calculated only from logs that have been ingested by Logging. If a log has been explicitly excluded from ingestion by Logging, it isn't included in these metrics.

  • User-defined log-based metrics, created by you to track things in your Google Cloud project that are of particular interest to you. For example, you might create a log-based metric to count the number of log entries that match a given filter.

    • By default, user-defined log-based metrics are calculated from all logs received by the Logging API for the Cloud project, regardless of any inclusion filters or exclusion filters that might apply to the Cloud project.

    • Preview: You can also create user-defined log-based metrics for a specific log bucket in a Cloud project. Bucket-level log-based metrics are calculated from all logs destined for the bucket, regardless of where they originated. For more information see Log-based metrics on log buckets.

Log-based metrics apply only within a single Google Cloud project. You can't create log-based metrics for other Google Cloud resources such as Cloud Billing accounts or organizations.

Before you begin

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

  1. In the Google Cloud console, go to the project selector page.

    Go to project selector

  2. To begin creating a Google Cloud project, click Create project.

  3. Name your project. Make a note of your generated project ID.

  4. Edit the other fields as needed.

  5. To create the project, click Create.

Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

To verify that you have the correct permissions to use log-based metrics for the Cloud project, see Access control with IAM Log-based metrics.

Visibility to metrics scopes

Log-based metrics are ingested by Cloud Monitoring, and the visibility of metric data to a Cloud project is determined by a metrics scope. A metrics scope is a list of projects that are monitored by the project that hosts the metrics scope; the hosting project is called a scoping project.

By default, each project hosts a metrics scope that includes only itself, so a project is a scoping project for itself. Therefore, your metrics, including log-based metrics, are visible only to your Cloud project.

You can also create a multi-project metrics scope for the scoping project. With a multi-project metrics scope, the scoping project can see the metrics from all the projects in the metrics scope. What is visible to the individual projects in a multi-project metrics scope is determined by the metrics scope hosted by each of those projects. The fact that two projects are in a multi-project metrics scope does not mean that each project has access to the metric or configuration data in the other project.

A single project can also appear in multiple metrics scopes. The metrics from such a project are visible to the scoping projects of each of those metrics scopes.

Metrics, including log-based metrics, are defined within a specific project. When that project appears in multiple metrics scopes, the metrics are visible to projects other than the one in which they are defined.

For more information about metrics scopes, including multi-project metrics scopes, and about scoping projects, see the following:

View your log-based metrics

Use the Logs-based metrics page in the Google Cloud console to view the project-level log-based metrics in your Cloud project. You use the same page to create and modify user-defined log-based metrics.

To view a list of log-based metrics for your Google Cloud project, do the following:

  1. Go to the Logs-based metrics page in the console:

    Go to Log-based metrics

  2. Select an existing Cloud project. The lists of log-based metrics in your Cloud project appear.

The log-based metrics interface is divided into two metric-type panes: System metrics and User-defined metrics.

Each pane contains a table summary of the metrics. Each metric's row has a menu that features the following options:

  • View in Metrics Explorer lets you view the data for a system log-based metric by opening Metrics Explorer in Cloud Monitoring.

    You can use Metrics Explorer to specify a target metric for an alerting policy. The chart next to the Target region gives you visual feedback on the data being captured by the target metric.

  • Create alert from metric lets you create an alerting policy based on the log-based metric.

    Selecting this option opens the Cloud Monitoring console, where you can create, edit, and manage alerting policies. For details on creating alerting policies for your log-based metrics, read Creating an alerting policy.

User-defined metrics pane

The User-defined metrics pane of the log-based metrics interface has several features to help you manage the user-defined metrics on your Cloud project:

  • The user-defined metrics table includes Name, Description, Type, and Filter columns. These are specified when you create the metric.

  • The Filter user-defined metrics pane lets you filter your metric list by text search or metric Name, Description, and Filter.

  • The user-defined metrics table includes columns for Previous month usage and Month-to-date usage (MTD). This usage data is useful, for example, if you want to determine which metrics ingest the most data or to estimate your bills.

Clicking on any of the column names lets you sort data in ascending or descending order.

The menu for each metric in your user-defined metrics pane contains additional features for managing your metrics:

The user-defined log-based metrics pane overflow menu options.

  • View metric details: Shows you the metric's Name, Type, Description, Filter, Units, and Labels, if defined.
  • Edit metric: Lets you edit certain fields for the metric.
  • Disable metric: Lets you stops the metric from being calculated. You can re-enable a disabled metric from the same menu.
  • Delete metric: Lets you delete the metric.
  • View logs for metric: Takes you to the Logs Explorer and populates the metric's filter in the Query builder and runs the query.

Overview of log-based metric types

Log-based metrics can extract data from logs to create metrics of the following types:

  • Counters: these metrics count the number of log entries that match a specified filter. Counters are useful for keeping track of the number of times a value or string appears in your logs.
  • Distribution: these metrics also count values, but they collect the counts into ranges of values (histogram buckets). Distributions are useful for tracking values like latencies.
  • Boolean: these metrics capture whether or not a log entry matches a specified filter.

User-defined log-based metrics can be of the counter or distribution metric types. Most system-defined log-based metrics are counters, but some are of the boolean type. The characteristics of counters and distributions are described in more detail in subsequent sections.

The data for a user-defined log-based metric comes only from log entries received after the metric is created. A metric isn't retroactively populated with data from log entries that are already in Logging.

System log-based metrics are calculated from included logs only. User-defined log-based metrics are calculated from both included and excluded logs.

Logging accumulates information for a log-based metric each time it receives a matching log entry. Logging writes a new data point to the metric's time series at the rate of 1 datapoint per minute, making the data available to Cloud Monitoring.

Each data point in a log-based metric's time series represents only the additional information (the delta) received since the previous data point.

The following sections describe the characteristics of counter-type and distribution-type metrics.

Counter metrics

Counter metrics count the number of log entries matching a given filter. For example, you can do the following:

  • Count the log entries that contain a certain specific error message.
  • Count the number of times each user invokes an operation, by looking for log messages that match this pattern:

    ... user USERNAME called OPERATION ...

    By extracting USERNAME and OPERATION and using them as values for two labels, you can later ask, "How many times did sally call the update operation?", "How many people called the read operation?", "How many times did george call an operation?", and so on.

For more information, see Configure counter metrics.

Distribution metrics

Distribution metrics accumulate numeric data from log entries matching a filter. The metrics contain a time series of distribution objects, each of which contains the following:

  • A count of the number of values in the distribution.
  • The mean of the values.
  • The sum of squared deviations: Sumi=1..n(xi–mean)2
  • A set of histogram buckets with the count of values in each bucket. You can use the default bucket layout or choose your own.

A common use for distribution metrics is to track latencies. As each log entry is received, a latency value is extracted from somewhere in the log entry and is added to the distribution. At regular intervals, the accumulated distribution is written to Cloud Monitoring.

For information about distributions, including their format within a time series and how they are visualized, see Charting distribution metrics.

For information about creating distribution log-based metrics, see Configure distribution metrics.


Log-based metrics can have labels, which allow multiple time series to be collected for the metric. Values for the labels are extracted from fields in the matching log entries. Logging records separate time series for each combination of label values.

The system log-based metrics have predefined labels. You can define the labels for user-defined metrics. For more information, see Log-based metric labels.

User-defined log-based metrics

User-defined log-based metrics are created by a user for a Google Cloud project. These metrics count the number of log entries that match a given filter or record particular values within the matching log entries.

For information about creating and managing your project-level user-defined metrics, see Configure counter metrics and Configure distribution metrics.

For information about creating log-based metrics that operate on a specific log bucket in your Cloud project, see Log-based metrics on log buckets.


All user-defined log-based metrics are a class of Cloud Monitoring custom metrics and are chargeable. For pricing information, see Cloud Logging pricing: Log-based metrics.


For information about the quotas and limits associated with user-defined log-based metrics, see Quotas and limits.

System log-based metrics

Logging provides a set of metrics that includes counters. The counter metrics record the number of logging events that occurred within a specific time period. The metrics have labels that record the counts by log name and severity level.

For a list of these metrics, see Google Cloud metrics: logging.

Cloud Monitoring

You can use both system and user-defined log-based metrics in Cloud Monitoring to create charts and alerting policies. For more information, see Configure charts and alerts.

In Cloud Monitoring, log-based metrics use the following naming patterns:

  • System: logging.googleapis.com/SYSTEM_METRIC_NAME
  • User-defined: logging.googleapis.com/user/USER_METRIC_NAME

Note that user-defined log-based metrics include the string user.


If you encounter issues when using log-based metrics, see Troubleshoot log-based metrics.