Overview of logs-based metrics

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

Logs-based metrics are Cloud Monitoring metrics that are based on 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 logs-based metrics in Cloud Monitoring charts and alerting policies. Logs-based metrics are calculated from both included and excluded logs.

Logs-based metrics apply only to a single Google Cloud project. You cannot create them for logs buckets or for other Google Cloud resources such as Cloud Billing accounts or organizations.

To use logs-based metrics, you must have a Cloud project with billing enabled.

System (logs-based) metrics are predefined by Logging. These metrics record the number of logging events that occurred within a specific time period. These metrics are free of charge and available to all Google Cloud projects. For a list of these metrics, see Google Cloud metrics: logging.

User-defined (logs-based) metrics are created by a user on a Google Cloud project. They count the number of log entries that match a given query, or keep track of particular values within the matching log entries. When filtering for the log entries that you want to count in your metric, you can use regular expressions.

Logging accumulates information for logs-based metrics each time it receives a matching log entry. Logs-based metrics are calculated from both included and excluded logs. 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.

The data for logs-based metrics comes from log entries received after the metrics are created. The metrics aren't populated with data from log entries that are already in Logging.

Getting started

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

  1. Go to the Google Cloud's operations suite Logging > Logs-based metrics page in the Cloud Console:

    Go to the Logs-based metrics page

  2. Select an existing Cloud project at the top of the page. The lists of logs-based metrics in your Cloud project appear:

The user interface showing the logs-based metrics lists.

To configure a Cloud Monitoring Workspace for your project, do the following:
  1. In the Cloud Console, select your Google Cloud project.
    Go to Cloud Console
  2. In the navigation pane, select Monitoring.

    If you have never used Cloud Monitoring, then on your first access of Monitoring in the Google Cloud Console, a Workspace is automatically created and your project is associated with that Workspace. Otherwise, if your project isn't associated with a Workspace, then a dialog appears and you can either create a Workspace or add your project to an existing Workspace. We recommend that you create a Workspace. After you make your selection, click Add.

Access control

Identity and Access Management roles and permissions govern access to Google Cloud data. Following is a summary of the common roles and permissions a Cloud project member needs to access logs-based metrics:

  • Logging/Logs Configuration Writer (roles/logging.configWriter) lets you list, create, get, update, and delete logs-based metrics.

  • Logging/Logs Viewer (roles/logging.viewer) lets you view existing metrics. You can also add the logging.logMetrics.get and logging.logMetrics.list permissions to a custom role.

  • Monitoring Viewer (roles/monitoring.viewer) lets you read the timeseries that the logs-based metric contains. You can also add the monitoring.timeSeries.list permission to a custom role.

  • Logging Admin (roles/logging.admin), Editor (roles/editor), and Owner (roles/owner) are broad-level roles that contain the permission to create logs-based metrics (logging.logMetrics.create).

For more information, go to Logging: Access control.

Logs-based metrics interface

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

Both areas contain a table summary of the metrics. Each table row has a menu that features the following options:

The logs-based metrics lists showing the overflow menu.

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

    You can use the 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 your logs-based metric.

    Selecting this option opens the Cloud Monitoring console, where you can create, edit, and manage alerting policies. For details, read Creating an alerting policy.

User-defined metrics interface

The User-defined metrics area of the Logs-based metrics interface has several additional features to help you manage the user-defined metrics on a project:

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

  • The Filter Metrics box lets you filter your metric list by text search or metric Name, Description, and Filter:

The logs-based metrics lists showing the filtering options.

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

  • You can Edit metric and Delete metric using the menu at the end of a table row.

In addition, clicking on any of the column names lets you sort data in ascending or descending order. At the bottom of the table, you can also select the number of rows that you wish to display.

For more information on managing your user-defined metrics using the Cloud Console, read Creating counter metrics and Creating distribution metrics.

Overview of logs-based metric types

Logging logs-based metrics can be one of two metric types: counter or distribution. All system logs-based metrics are the counter type. User-defined logs-based metrics can be either the counter type or the distribution type.

Each data point in a logs-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 an advanced logs query. For example, you can do the following:

  • Create a metric that counts log entries containing a certain specific error message.
  • Count the number of times each user invokes an operation, by looking for log messages like this:

    ... 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, go to Creating counter metrics.

Distribution metrics

Distribution metrics accumulate numeric data from log entries matching a query. 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 more information, go to Creating distribution metrics.


Logs-based metrics can optionally have labels, which allow a single metric to hold multiple time series. Values for the labels are extracted from fields in the matching log entries. Logging records separate time series for each different value of your label.

The system logs-based metrics have predefined labels. You can define your own labels for your user-defined metrics. For more information, read Logs-based metric labels.

System logs-based metrics

Logging provides some predefined counter metrics that track the number and volume of log entries received. The metrics have labels that record the counts by log name and severity level. The following table lists the metrics:

Metric name and description Type Value Labels

The total number of log entries received.

delta int64 log: The name of the log. Example: "appengine.googleapis.com/request_log".

severity: The severity of the log entries. Example: "ERROR".


The total number of bytes received in log entries.

delta int64 log: The name of the log. Example: "appengine.googleapis.com/request_log".

The total number of log entries that were excluded.

delta int64

The total number of bytes in log entries that were excluded.

delta int64

The total number of log entries that were exported using sinks.

delta int64

The total number of bytes in log entries that were exported using sinks.

delta int64

The total number of log entries that weren't exported due to export configuration errors.

delta int64

The number of late-arriving log entries. 1

delta int64 log: The name of the log. Example: "appengine.googleapis.com/request_log".

1 Log entries arriving later than 24 hours or earlier than 10 minutes aren't included in log_entry_count or byte_count metrics.

For a full list of system logs-based metrics, go to Logging metrics.

Cloud Monitoring

You can use both system and user-defined logs-based metrics in Cloud Monitoring to create charts and alerting policies. Your user-defined logs-based metric names are prefixed by user/; the system logs-based metrics are not.

If you're using the Cloud Monitoring API, the logs-based metrics names are as follows:


For more information, go to Creating charts and alerts.


If you encounter issues when using logs-based metrics, go to Troubleshooting.