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, including troubleshooting information, go to Overview of logs-based metrics.

Creating a counter metric

Logging Console

Follow these steps to create a logs-based counter metric in the Cloud Console:

Click on Stackdriver Logging > Logs-based Metrics in the left-side navigation list in the Cloud Console, or click the following button:

Go to Logs-Based Metrics
Use the drop-down menu at the top of the page to select a project.
Click Create Metric at the top of the page. You see the Metric Editor at the right side of the page and the viewer panel showing your logs on the left side:
In the viewer panel, create a query that shows only the log entries that you want to count in your metric.

The basic query is available in the drop-down menus above the log entries. Alternatively, you can access the advanced query interface by clicking on the drop-down menu in the right-hand side of the search bar and selecting Convert to advanced filter.

For more information, see the Logs Viewer.
In the Metric Editor panel, set the following fields:
- Name: Choose a name that is unique among logs-based metrics in your project. Some naming restrictions apply; see Troubleshooting for details.
- Description: Describe the metric.
- Labels: (Optional) Add labels by clicking Add Item for each label. For details about defining labels, see Logs-based Metric Labels.
- Units: For counter metrics, leave this blank or insert the digit 1.
- Type: Counter.
Click Create Metric to create the metric.

Logging 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 Metric Labels for an introduction to labels and details about creating them in the API,

For more details, see the LogMetric type.

Cloud SDK

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 project. Some naming restrictions apply; see Troubleshooting for details.

New metric latency

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

Inspecting counter metrics

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

Logging Console

Go to the Logs-Based Metrics page, which lists all of the logs-based metrics in the current project, by clicking the following button:

Go to Logs-based Metrics

To view the data in a logs-based metric, select View in Metrics Explorer from the overflow menu at the right side of the metric's listing.

Logging API

Listing metrics

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

parent: The resource name of the project: projects/[PROJECT_ID].
pageSize: The maximum number of results.
pageToken: Gets the next page of results. 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 Stackdriver Monitoring API. For details, see Reading Time Series. Here is the information you need for logs-based metrics:

The metric type is logging.googleapis.com/user/[METRIC_ID].

Cloud SDK

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

gcloud logging metrics list

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

gcloud logging metrics describe [METRIC_NAME]

For more details, use the following command:

gcloud logging metrics --help

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

Updating counter metrics

You can update a logs-based metric to change the description, queries, 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 cannot change the names or types of logs-based metrics or their labels, and you cannot delete existing labels in a logs-based metric.

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

Logging Console

Go to the Logs-Based Metrics page:

Go to Logs-based Metrics
Click Edit metric in the menu at the right side of the logs-based metric that you want to edit.
Change only the allowable items in the metric.

Caution: The UI lets you edit the name of a logs-based metric, but this does not rename the metric. Instead, it creates a new logs-based metric. The data remains associated with the original, and there is no data associated with the new logs-based metric. The UI does not tell you this has occurred.
Click Done.

Logging API

To edit or update 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.

Cloud SDK

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

Deleting counter metrics

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

Logging Console

Go to the Logs-Based Metrics page:

Go to Logs-based Metrics
Select the metrics you want to delete and Click Delete at the top of the page.

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

Logging API

Use the projects.metrics.delete method in the API.

Cloud SDK

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

gcloud logging metrics delete [METRIC_NAME]

For more details, use the following command:

gcloud logging metrics delete --help