Configure labels on log-based metrics

This document discusses log-based metrics labels, and explains how to create and use labels on log metrics.

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

Overview of labels for log-based metrics

Labels let log-based metrics contain multiple time series—one for each combination of label values. All log-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 information on regular expressions, see RE2 Syntax.

Don't put sensitive information in the extractor expression and don't extract sensitive data into labels. These are treated as service data.

Note: Create labels only when you need to identify values to categorize or summarize your metric data. Don't use labels to simply give names to data fields.

Limitations of user-defined labels

The following limitations apply to user-defined labels:

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

• After you create a label, you can't delete it.

  • 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 log-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.

Caution: Never extract a label value that is unique for each log entry, such as the full insertId or timestamp fields. You will have as many time series as there are log entries, each containing one point.

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 log-based metrics, see Cloud Monitoring pricing: Chargeable metrics. For information on the limits that apply to log-based metrics, see Quotas and limits: Log-based metrics and Troubleshoot log-based metrics.

Default labels

All log-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 severity label is provided by default only in system log-based metrics.

Example: Use the Metrics Explorer

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

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 log-based metrics.

Console

1. When you create a log-based metric, 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. Label name: Enter 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:

      labels."compute.googleapis.com/resource_id"
      

   5. Regular expression: If your label's value consists of the field's entire contents, then you can leave this field empty. Otherwise, specify a regexp capture group 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. For example, in the following expression, the parentheses are a capture group identifying the part of the text that will be extracted:

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

      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.

5. To finish creating the metric, click Create metric.

gcloud

To create a log-based metric with custom labels, you must create a file that contains a representation of your LogMetric definition in JSON or YAML format, including the custom labels. Then, create the metric by calling the create command with the --config-from-file flag, replacing FILENAME with the name of your JSON or YAML file:

gcloud logging metrics create METRIC_NAME --config-from-file FILENAME

For more information, see gcloud logging metrics create.

API

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: {
    LABEL_NAME: EXTRACTOR_EXPRESSION,
    ...
  },
}

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. The extractor expression can be one of the following:

  EXTRACT(FIELD)
  

  REGEXP_EXTRACT(FIELD, REGEXP)
  

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: {
    "label_name_a":
      "REGEXP_EXTRACT(jsonPayload.field_a, \"before ([a-zA-Z ]+) after\")",
    "label_name_b": "EXTRACT(jsonPayload.field_b)",
  },
}

For more details, see the LogMetric type.