Logs-based metrics labels

This page discusses logs-based metrics default labels and explains how to create and use labels on logs-based metrics.

If you're familiar with labels, you can go directly to Create a label on this page.


Labels let logs-based metrics contain multiple time series—one for each label value. All logs-based metrics come with some default labels.

You can create additional user-defined labels in both counter-type and distribution-type metrics by specifying extractor expressions. An extractor expression tells Cloud Logging how to extract the label's value from log entries. You can specify the label's value as either of the following:

  • The entire contents of a named field in the LogEntry object.
  • A part of a named field that matches a regular expression (regexp).

You can extract labels from the LogEntry built-in fields, such as httpRequest.status, or from one of the payload fields textPayload, jsonPayload, or protoPayload.

For more information on regular expressions, see RE2 Syntax.

Limitations of user-defined labels

The following limitations apply to user-defined labels:

  • You can create up to 10 user-defined labels per metric.

  • A label can't be deleted after it is created.

    • You can modify the extractor expression and description of the label you have already created.

    • You can't change the name or value type of a label you have already created.

  • Only the first 1,024 characters of a label value are kept.

  • Each logs-based metric is limited to about 30,000 active time series, which is dependent upon the number of possible values for each label, including default labels.

    For example, if your log entries come from 100 resources such as VM instances, and you define a label with 20 possible values, then you can have up to 2,000 time series for your metric.

If you have too many time series or too many data points, your costs will rise and your activity might be throttled. For more information on the cost of logs-based metrics, see Cloud Monitoring pricing: Chargeable metrics. For information on the limits that apply to log-based metrics, see Quotas and limits: Logs-based metrics and Troubleshoot log-based metrics.

Default labels

All logs-based metrics come with some predefined labels:

  • Resource labels: All metrics use a monitored resource object to identify the source of time series data. Each resource type includes a type name and one or more labels. Examples of types of resources include VM instances, Cloud SQL databases, load balancers, etc.

    The resource and its labels are listed separately from other metric labels in Cloud Monitoring, but they have the same effect: they create additional time series in the metric. For more information, see Metrics, Time Series, and Resources.

  • log: This label holds the value of the LOG_ID portion of the logName field in log entries.

  • severity: This label holds the value of the severity field in log entries.


The following screenshot from the Metrics Explorer shows the labels on one of the system logs-based metrics. You get the label list by clicking inside the Filter text box:

Metrics Explorer

The screenshot shows the following information:

  • The Metrics Explorer is using time series from the logging/log_entry_count metric and the gce_instance resource type—Compute Engine VM instances.

    This metric contains time series from other resource types as well, but Metrics Explorer lets you look at only one resource type at a time.

  • The gce_instance resource type has three resource labels: project_id, instance_id, and zone.

  • The metric has two metric labels: log and severity. Your user-defined labels also appear in this section.

Create a label

You create user-defined labels when you create the metric. Both counter metrics and distribution metrics can have labels. You can't add labels to the system logs-based metrics.


  1. When creating a logs-based metric, part of the Create logs metric panel includes an option to add labels.

  2. Click Add label.

    Tip: To see the fields and values inside a log entry, do the following:

    1. In the Filter selection section, click Preview logs.
    2. In the View logs pane, choose a log entry and click the expander next to it.
    3. Click Expand nested fields.
  3. Set the following fields in the Labels section:

    1. Name: Choose a name for the label. For example, ID.

      The name must meet the following criteria:

      • Be no more than 100 characters in length.
      • Match the regular expression [a-zA-Z][a-zA-Z0-9_]*.
      • Consist of more than just the string "log".
    2. Description: Describe the label. Try to be as specific as possible about the format of expected logs values. For example, Instance number.

    3. Label type: Choose String, Boolean, or Integer.

    4. Field name: Enter the name of the log entry field that contains the label's value. You are offered choices as you type. In this sample, the field is:

    5. Extraction regular expression: If your label's value consists of the field's entire contents, then you can leave this field empty. Otherwise, specify a regular expression (regexp) that extracts the label value from the field value. For example, suppose the field typically contains text like the following:

      The instance number is 0123456789; the ID is my-test-instance22

      If you want the label value to be the instance number, there are many regular expressions that will extract the correct number. Here's one:

      The instance number is ([0-9]+); .*

      The parentheses, known as a regexp capture group, identifies the part of the text match that will be extracted. For more information on regular expressions, see RE2 Syntax.

  4. Click Done to create the label. You can add more labels by repeating these steps.


For instructions on creating a logs-based metric with labels using gcloud command-line tool, go to gcloud logging metrics create.


Labels are specified as part of the LogMetric object in the request body of calls to the projects.metrics.create method of the Logging API. For information about the full method calls, see Creating counter metrics or Creating distribution metrics.

For each label, you must add a segment to both the metricDescriptor and the labelExtractors fields in the LogMetric.

The syntax is the following:

  metricDescriptor: {
      labels: [
        { key: LABEL_NAME, valueType: LABEL_TYPE,
          description: LABEL_DESCRIPTION },
  labelExtractors: {

The syntax elements have the following meaning:

  • LABEL_NAME: The name of the label as a string.
  • VALUE_TYPE: The type of the label: STRING, BOOL, or INT64.
  • LABEL_DESCRIPTION: A description of the label.
  • EXTRACTOR_EXPRESSION: A string that combines the log entry field name with an optional regular expression. One of the following:


For more information on regular expressions, see RE2 Syntax.

Following is an example with two labels:

  metricDescriptor: {
      labels: [
        { key: "label_name_a", valueType: STRING },
        { key: "label_name_b", valueType: INT64 },
  labelExtractors: {
      "REGEXP_EXTRACT(jsonPayload.field_a, \"before ([a-zA-Z ]+) after\"",
    "label_name_b": "EXTRACT(jsonPayload.field_b)",

For more details, see the LogMetric type.