Creating counter metrics

This page explains how to create counter-type logs-based metrics using the Cloud Console, the Logging API, and the gcloud command-line tool.

For an overall view of logs-based metrics, go to Overview of logs-based metrics.

Creating a counter metric

When you create a filter for the log entries that you want to count in your metric, you can use regular expressions.

Console

Follow these steps to create a counter metric in the Cloud Console in your Google Cloud project:

Go to the Logging > Logs-based Metrics page:

Go to Logs-Based Metrics
Click Create metric. The Create logs metric panel appears.
Set the Metric type: Select Counter.
Set the following fields in the Details section:
- Log metric name: Choose a name that is unique among the logs-based metrics in your Cloud project. Some naming restrictions apply; see Troubleshooting for details.
- Description: Enter a description for the metric.
- Units: Leave this blank or insert the digit 1.
Define your metric filter in the Filter selection section.

Create a filter that collects only the log entries that you want to count in your metric using the logging query language. You can also use regular expressions to create your metric's filters.

Click Preview logs to open a panel showing you the log entries that match your filter.
(Optional) Add a label in the Labels section. For instructions on creating labels, see Creating a label.
Click Create metric to create the metric.

Command-line

The gcloud command-line tool supports counter-type logs-based metrics without labels. The command for creating a logs-based metric is:

gcloud logging metrics create [METRIC_NAME] [METRIC_DESCRIPTION] [FILTER]

For example, the following command creates a logs-based counter metric called error_count.

gcloud logging metrics create error_count \
    --description "Errors in syslog." \
    --log-filter "resource.type=gce_instance AND logName:logs/syslog AND severity>=ERROR"

Choose a metric name that is unique among logs-based metrics in your Cloud project. Some naming restrictions apply; see Troubleshooting for details.

API

To create a counter metric, use the projects.metrics.create method of the Logging API. You can try out the method in the APIs Explorer. Prepare the arguments to the method as follows:

Set the parent field to the project in which the metric is to be created:
```
projects/[PROJECT_ID]
```

Set the request body to a LogMetric object. Following is an example of the object:

{
  name:        "my-metric"
  description: "This is my metric."
  filter:      "resource.type=gce_instance AND logName:\"logs/syslog\"",
  metricDescriptor: {
      labels: [
        {
          key: "my-label",
          valueType: STRING,
          description: "This is my label.",
        }
      ]
  },
  labelExtractors: {
    "my-label":
      "REGEXP_EXTRACT(jsonPayload.someField, \"before ([0-9]+) after\")",
    ...
  },
}

Notes:

Choose a metric name that is unique among logs-based metrics in your project. Some naming restrictions apply; see Troubleshooting for details.
For counter metrics, the LogMetric fields valueExtractor and bucketOptions have no purpose and are omitted.
If your metric has no labels, you can omit the metricDescriptor and labelExtractors fields. If your metric does have labels, then see Logs-based metrics labels for an introduction to labels and details about creating them in the API.

For more details, see the LogMetric type.

New metric latency

Your new metric appears in the Legacy Logs Viewer's list of metrics and in the relevant Monitoring menus right away. Data is usually available in less than a minute.

Inspecting counter metrics

To list the user-defined logs-based metrics in your Google Cloud project or to inspect a particular metric in your Cloud project, do the following:

Console

Go to the Logs-Based Metrics page:

Go to Logs-based Metrics

In the User-defined metrics pane, you see the user-defined logs-based metrics in the current Cloud project:

To view the data in a logs-based metric, click the menu in the metric's row and select View in Metrics Explorer.

Command-line

To list the user-defined logs-based metrics in your Cloud project, use the following command:

gcloud logging metrics list

To display a user-defined logs-based metric in your Cloud project, use the following command:

gcloud logging metrics describe [METRIC_NAME]

To get help, use the following command:

gcloud logging metrics --help

You can't read a metric's time series data from the Cloud SDK.

API

Listing metrics

To list the user-defined logs-based metrics in a Cloud project, use the projects.metrics.list API method. Fill in the parameters to the method as follows:

parent: The resource name of the Cloud project: projects/[PROJECT_ID].
pageSize: The maximum number of results.
pageToken: Gets the next page of results. For information about using page tokens, see projects.metrics.list.

Retrieving metric definitions

To retrieve a single user-defined logs-based metric, use the projects.metrics.get API method. Fill in the parameters to the method as follows:

metricName: The resource name of the metric:
```
projects/[PROJECT_ID]/metrics/[METRIC_ID]
```

Reading metric data

To read the time series data in a logs-based metric, use the projects.timeseries.list in the Cloud Monitoring API. For details on time series data, see Reading time series.

To read a single user-defined logs-based metric, fill in the method's parameters with this metric type and identifier:

logging.googleapis.com/user/[METRIC_ID]

Updating counter metrics

You can edit a user-defined logs-based metric to change its description, filter, and the names of fields referenced in the metric. You can add new labels to the metric and you can change the regular expressions used to extract values for the metric and its labels.

You can't change the names or types of user-defined logs-based metrics or their labels, and you can't delete existing labels in a logs-based metric.

To edit a logs-based metric, do the following:

Console

Go to the Logs-Based Metrics page:

Go to Logs-based Metrics
Click Edit metric in the menu for the logs-based metric that you want to modify.
Change the allowable items in the metric.
Click Update metric.

Command-line

You can only change the description and the query for an existing metric using the Cloud SDK.

To update a logs-based metric, use the following command. You can specify either or both of the flags:

gcloud logging metrics update [METRIC_NAME] --description=[DESCRIPTION] --log-filter=[FILTER]

For more details, use the following command:

gcloud logging metrics update --help

API

To edit a logs-based metric, use the projects.metrics.update method in the API. Set the fields as follows:

metricName: The full resource name of the metric:

projects/[PROJECT_ID]/metrics/[METRIC_ID]

For example:

projects/my-gcp-project/metrics/my-error-metric

In the request body, include a LogMetric object that is exactly the same as the existing metric except for the changes and additions you want to make.

Deleting counter metrics

To delete a user-defined logs-based metric, do the following:

Console

Go to the Logs-Based Metrics page:

Go to Logs-based Metrics
Select the metric you want to delete and click Delete.

Alternatively, click Delete metric in the menu of the logs-based metric that you want to delete.

Command-line

Use the following command to delete a user-defined logs-based metric in the current Cloud project:

gcloud logging metrics delete [METRIC_NAME]

For more details, use the following command:

gcloud logging metrics delete --help

API

To delete a user-defined logs-based metric, use the projects.metrics.delete method in the API.

In addition, in the Google Cloud Console Logs-based metric page, the User-defined metrics pane of the logs-based metrics interface provides more features to help you manage the user-defined metrics on your Cloud project. See User-defined metrics pane for details.