Logs-based Metric Labels

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

If you are already familiar with labels, you can go directly to Creating a label on this page.


Labels allow logs-based metrics to 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 is required for each configured label to tell Stackdriver Logging how to extract values from logs and place it as the labels' value. The extractor can specify a field name in the LogEntry if the full value of the field is to be placed in the label. Additionally, a regular expression can also be specified to capture some portion of the field's value in the metric label.

Default labels

All logs-based metrics, including system logging 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, CloudSQL databases, load balancers, etc.

    The resource and its labels are listed separately from other metric labels in Stackdriver 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.

Creating a label

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

Logging Console

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

    Label menu

  2. Click Add item. You see the following form—this one is already filled in—to describe your label:

    Create label

    Tip: To see all the fields and values inside your log entries, choose a log entry, click the expander icon next to it, and click Expand all.

  3. Fill in the following fields in the Label form:

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

    2. Description: Describe the label. 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.

Logging API

Labels are specified as part of the LogMetric object in the request body of calls to the projects.metrics.create method of the Stackdriver 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:


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.

Cloud SDK

The gcloud logging command presently does not support creating logs-based metrics with labels.

Send feedback about...

Stackdriver Logging