Logs-based Metric Labels

This page discusses logs-based metrics default labels and 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.

Overview

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 tells Stackdriver Logging how to extract the label's value from log entries. You can specify the value as either of the following:

  • The entire contents of a named field in the log entry.
  • A part of a named field that matches a regular expression.

You can extract labels from both built-in log entry fields, such as httpRequest.status, or from the payload fields textPayload, jsonPayload, or protoPayload.

Limitations of user-defined labels

Extracted label values should not be too long and there should not be too many different values for each label:

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

  • A label cannot be deleted after it is created.

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

    • You cannot 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 are 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 Stackdriver Pricing. For metric-related quotas and limits, see Quotas & Limits and Troubleshooting.

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.

Example

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.

      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. 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: {
    [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. One of the following:

    EXTRACT([FIELD])
    REGEXP_EXTRACT([FIELD], [REGEXP])
    

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.

Cloud SDK

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

Var denne side nyttig? Giv os en anmeldelse af den:

Send feedback om...

Stackdriver Logging