Configure labels on log-based metrics

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

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

Overview of labels for log-based metrics

Labels let log-based metrics contain multiple time series—one for eachcombination of label values. All log-based metrics come with somedefault labels.

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

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

You can extract labels from theLogEntry built-in fields, such ashttpRequest.status, or from one of the payload fieldstextPayload,jsonPayload, orprotoPayload. However, you can't extract the ID of anerror group from theerrorGroups field.

For information on regular expressions, seeRE2 Syntax.

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

Note: Create labels only when you need to identify values to categorize orsummarize your metric data. Don't use labels to give names to datafields.

Limitations of user-defined labels

The following limitations apply to user-defined labels:

Caution: Never extract a label value that is unique for each log entry, such asthe fullinsertId ortimestamp fields. You will have as many time series asthere are log entries, each containing one point.

If you have too many time series or too many data points, your costs will riseand your activity might be throttled. For more information on the cost oflog-based metrics, seeGoogle Cloud Observability pricing.For information on the limits that apply to log-based metrics, seeQuotas and limits: Log-based metrics andTroubleshoot log-based metrics.

Default labels

Most log-based metrics come with some predefined labels:

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

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

  • log: This label holds the value of theLOG_ID portion of thelogName field in log entries.

  • severity: This label holds the value of theseverity field in logentries. The severity label is provided by default only insystem log-based metrics.

View labels by using the Metrics Explorer

To view the labels on a time series generated for a log-based metric,do the following:

  1. In the Google Cloud console, go to theLog-based Metrics page:

    Go toLog-based Metrics

    If you use the search bar to find this page, then select the result whose subheading isLogging.

  2. Find the metric you want to view, and then selectView in Metrics Explorer from the metric'sMoremenu.

    Before proceeding, wait until the chart displays data, which might takeseveral minutes when you've created a log-based metric.

  3. To view the available labels, expand theFilter field.You might see resource labels and metric labels. The list of labelsis specific to the resource type and the metric type. For example:

    • Thegce_instance resource type has threeresource labels:project_id,instance_id, andzone.

    • Thelogging/log_entry_count metric type has twometric labels:log andseverity. Your user-defined labels also appear in thissection.

  4. To verify that a user-defined label is extracting the correct data fromyour log entries, do the following:

    1. Change theAggregation element toUnaggregated.

    2. In the chart, select eitherTable orBoth.

    3. In the toolbar, selectColumn display menu,and then select your labels. This menu displays all labels for whichthere is data.

      If you don't see a label you created, then verify the field name and theextractor expression.

Create a label

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

To create a label, you specify the field in the log entry, and then youdefine an expression that extracts a value from the specified field.

Console

  1. When youcreate a log-based metric,theCreate log-based metric panel includes an option to add labels.

  2. ClickAdd label.

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

    1. In theFilter selection section, clickPreview logs.
    2. In theView logs pane, choose a log entry and click theexpandernext to it.
    3. ClickExpand nested fields.

  3. Set the following fields in theLabels 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 aspossible about the format of expected logs values. For example,Instance number.

    3. Label type: ChooseSTRING,BOOLEAN, orINTEGER.

      For more information about the various types of data that can beused to create log-based metrics, seeData types for log-based metrics.

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

      labels."compute.googleapis.com/resource_id"

    5. Regular expression: If your label's value consists ofthe field's entire contents, then you can leave this field empty.Otherwise, specify a regexpcapture group that extracts thelabel value from the field value.

      For example, suppose the field typically contains text like thefollowing:

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

      If you want the label value to be the instance number, there aremany regular expressions that will extract the correct number.For example, in the following expression, the parentheses are acapture group identifying the part of the text that will beextracted:

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

      For more informationabout regular expressions, seeRE2 Syntax.

  4. ClickDone to create the label. You can add more labels byrepeating these steps.

  5. To finish creating the metric, clickCreate metric.

gcloud

To create a log-based metric with custom labels, you must create a file thatcontains a representation of yourLogMetric definition inJSON or YAML format, including the custom labels. Then, create the metricby calling thecreate command with the--config-from-file flag,replacingFILENAME with the name of your JSON or YAML file:

gcloud logging metrics createMETRIC_NAME --config-from-fileFILENAME

For more information, seegcloud logging metrics create.

API

Labels are specified as part of theLogMetric objectin the request bodyof calls to theprojects.metrics.create methodof the Logging API. For information about the full method calls,seeCreating counter metricsorCreating distribution metrics.

For each label, you must add a segment to both themetricDescriptor andthelabelExtractors fields in theLogMetric.

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, orINT64.
  • LABEL_DESCRIPTION: A description of the label.

  • EXTRACTOR_EXPRESSION: A string that combines the log entryfield name with an optional regular expression. The extractor expressioncan be one of the following:

    EXTRACT(FIELD)
    REGEXP_EXTRACT(FIELD,REGEXP)

For more information on regular expressions, seeRE2 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 theLogMetric type.

Examples

This section provides a few examples that might help you get started withcreating labels on your user-defined log-based metrics. After you createa label, we recommend that youverify the labels by using the Metrics Explorer.

Tips:

  • You must use a capture group when you specify an extractor expression.
  • If you don't specify an extractor expression, then the entire value of thefield is extracted.

  • Ensure that the set of possible values for any label is constrained. A smallset of discrete values (like "red", "green", and "blue") is the preferredapproach. If, for example, you extract the 8-bit RGB values for a color label,you can have over 16 million different values. This means that you could haveover 16 million time series.

    Don't extract high-resolution values like timestamps, any kind of uniqueidentifier, user IDs, IP addresses, unparameterized URLs, and so forth.

Extract the status code from an audit log

If a field doesn't contain any special characters, then you can use thefield name in the label for the log-based metric.

For example, for audit logs, theprotoPayload fieldconforms to theAuditLog structure. Therefore,to extract thestatus field from an audit log, you can set the field name toprotoPayload.status.code and leave the extractor expression empty.

If you only want to extract the first digit of the error code,the you might set the extractor expression to(\d)\d\d.

Extract value from a field with special characters

If a field in a log entry contains special characters, then wrap the fieldwith double quotes.

For example, to extract the entire value of thek8s-pod/k8s-app label,set the field name tolabels."k8s-pod/k8s-app" and leave the expression empty.

Extract a value from a text payload

Note: To ensure that the set of possible values for the label is constrained,always specify an extractor expression for text payload fields.

Consider a log entry that has the following format:

textPayload: "unfinished_task_instance_count.py:61 Unfinished task instance count metric value 0 for state: deferred"

To extract the value for the state, such asdeferred from log entrieswith the previous format, you might do something like:

  • Field name:textPayload
  • Extractor expression:^unfinished.*state: ([a-z]+)

Extract value from a repeated field

A log entry might contain a field with repeated fields. In JSON, these fieldsare displayed using square brackets ([]). From the perspective of labels,consider the repeated fields as a set and the label extractor as an iterator.You provide the criteria for the match when you define the label, and theextractor iterates over the set until a match is found. The first match isalways returned, even when multiple members of the set match the criteria.

You decide to create a log-based metric that counts audit logs. Beforeconfiguring your label, you review several audit logs and notice that theformat of theprotoPayload conforms to theAuditLogstructure. The following illustrates a portion of an audit log entry.

{  ...  protoPayload: {    @type: "type.googleapis.com/google.cloud.audit.AuditLog"    authenticationInfo: {1}    authorizationInfo: [      0: {        granted: true        permission: "io.k8s.coordination.v1.leases.get"        resource: "coordination.k8s.io/v1/namespaces/kube-system/leases/maintenance-controller"      }    ]    requestMetadata: {2}    status: {1}    ...  }  ...}

You decide to create a label for your log-based metric that stores informationfrom thepermission field. You notice that these fields are formattedlikeio.k8s.xyz, wherexyz is a string that provides moredetail about the request. This string might have a value likeget, or itmight have more complex formatting likeio.k8s.coordination.v1.leases.get.

To minimize the number of label values, you don't want to extract thedetailed information. You only want to storevalues likeget orcoordination in the label. Also, you decide that youdon't want to include the common prefix,io.k8s., in the label value.

Next, you configure the label. Because thepermission field is arepeated field, with the parent being theauthorizationInfo field,you set the field name as follows:

protoPayload.authorizationInfo.permission

Lastly, you create the following regular expression:

io.k8s.([a-z]+).*

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.