Console

Follow these steps to create a log-based counter metric in theGoogle Cloud console in your Google Cloud project:

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. ClickCreate Metric. TheCreate logs metric panel appears.

3. Set theMetric type: SelectDistribution.

4. Set the following fields in theDetails section:

   • Log metric name: Choose a name that is unique among thelog-based metrics in your Google Cloud project. Some namingrestrictions apply; seeTroubleshootingfor details.
   • Description: Enter a description for the metric.
   • Units: (Optional) For distribution metrics, you can optionallyenter units, such ass andms. For more information, see theunit field of theMetricDescriptor.

5. Define your metric filter in theFilter selection section.

   1. Use theSelect project or log bucket menu to select whether themetriccounts the log entries in your Google Cloud project or onlythose log entries in a specific log bucket.

   2. Create a filter that collects only the log entries that you want tocount in your metric using thelogging query language.You can also use regular expressions to create your metric'sfilters.

   3. Field name: Enter the log entry field that contains thedistribution's value. You are offered choices as you type. Forexample:

      protoPayload.latency

   4. Regular expression: (Optional) IfField name alwayscontains a numeric value convertible to typedouble, then you canleave this field empty. Otherwise, specify a regular expression thatextracts the numeric distribution value from the field value.

      Example. Suppose that yourlatency log entryfield contains a number followed byms for milliseconds. Thefollowing regexp chooses the number without the unit suffix:

      ([0-9.]+)

      The parentheses, known as a regexpcapture group, identifies thepart of the text match that will be extracted. Seeusing regular expressionsfor details.

   • Advanced (Histogram buckets): (Optional) ClickingAdvancedopens a section of the form you can use to specify custom bucketlayouts. If you don't specify your bucket layouts, a default bucketlayout is provided. For more information,seeHistogram buckets on this page.
   1. To see which log entries match your filter, clickPreview logs.

6. (Optional) Add a label in theLabels section. For instructions oncreating labels, seeCreate a label.

7. ClickCreate metric to create the metric.

gcloud

To create a distribution-type log-based metric,create a file that contains a representation of yourLogMetric definition inJSON or YAML format. Then use the following command to read theconfiguration from your file:

gcloud logging metrics createMETRIC_NAME --config-from-fileFILENAME

For information about describing the histogram buckets for a distribution,seeHistogram buckets.

API

To create a distribution metric, use theprojects.metrics.create methodof the Logging API. If you use the APIs Explorer pane on thereference page, then prepare the arguments as follows:

1. Set theparent field to the project or bucket in which the metric isto be created:

   • For a project-scoped log-based metric, specify the project:

   projects/PROJECT_ID

   • For a bucket-scoped log-based metric, specify the bucket:

   projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID

2. Set the request body to aLogMetric object. Following isa sampleobject for a distribution metric.

   {  name:        "my-metric"  description: "Description of my-metric."  filter:      "resource.type=gce_instance AND log_id(\"syslog\")",  valueExtractor: "REGEXP_EXTRACT(jsonPayload.latencyField, \"([0-9.]+)ms\")",  labelExtractors: {    "my-label-1":      "REGEXP_EXTRACT(jsonPayload.someField, \"before ([[:word:]]+) after\")",    "my-label-2":      "EXTRACT(jsonPayload.anotherField, \"before ([0-9]+) after\")",  },  bucketOptions: { [SEE_BELOW] },  metricDescriptor: {      metricKind: DELTA,      valueType: DISTRIBUTION,      unit: "ms",      labels: [        {          key: "my-label-1",          valueType: STRING,          description: "Description of string my-label-1.",        },        {          key: "my-label-2",          valueType: INT64,          description: "Description of integer my-label-2.",        }      ]  },}

Notes:

• Some naming restrictions apply; seeTroubleshootingfor details.

• metricDescriptor: aMetricDescriptor object.metricKind must beDELTA.valueType must beDISTRIBUTION.

Console

TheHistogram buckets submenu opens when you create a distributionmetric and you clickMore in theMetric editor form.The following subform is for theLinear bucket layout:

Linear buckets: Fill in the histogram bucket form as follows.

• Type:Linear
• Start value (a): The lower boundary of the first finite bucket.This value is calledoffset in the API.
• Number of buckets (N): The number of finite buckets. The valuemust be greater than or equal to 0.
• Bucket width (b): The difference between the upper bound and lowerbound in each finite bucket. The value must be greater than 0.

For example, if the start value is 5, the number of buckets is 4, andthe bucket width is 15, then the bucket ranges are as follows:

(-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

Explicit buckets:Fill in the histogram bucket form as follows:

• Type:Explicit
• Bounds (b): A comma-separated list of the boundary values of thefinite buckets. This also determines the number of buckets and theirwidths.

For example, if the list of boundaries is:

0, 1, 2, 5, 10, 20

then there are five finite buckets with the following ranges:

(-INF, 0), [0, 1), [1, 2), [2,5), [5, 10), [10, 20), [20, +INF)

Exponential buckets:Fill in the histogram bucket form as follows:

• Type:Exponential

• Number of buckets (N): The total number of finite buckets.The value must be greater than 0.

• Linear scale (a): The linear scale for the buckets.The value must be greater than 0.

• Exponential growth factor (b): The exponential growth factor forthe buckets. The value must be greater than 1.

For example, ifN=4,a=3, andb=2, then the bucket rangesare as follows:

(-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

For more information about the buckets, seeBucketOptions in theCloud Monitoring API.

API

The optional bucket layout is specified by thebucketOptions field intheLogMetric object supplied toprojects.metrics.create. For thecompleteLogMetric object,seeCreate a distribution metric on this page.The additions for bucket layouts are as shown:

Linear buckets:

{ # LogMetric object  ...  bucketOptions: {    linearBuckets: {      numFiniteBuckets: 4,      width: 15,      offset: 5    }  },  ...}

The previous sample creates the following buckets:

(-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

Explicit buckets: Boundaries are listed individually.

{ # LogMetric object  ...  bucketOptions: {    explicitBuckets: {      bounds: [0, 1, 2, 5, 10, 20 ]    }  },  ...}

The previous sample creates the following buckets:

(-INF, 0), [0, 1), [1, 2), [2, 5), [5, 10), [10, 20), [20, +INF)

Exponential buckets: Boundaries arescale *growthFactor ^i, fori=0,1,2, ...,numFiniteBuckets

{ # LogMetric object  ...  bucketOptions: {    exponentialBuckets: {      numFiniteBuckets: 4,      growthFactor: 2,      scale: 3    }  },  ...}

The previous sample creates the following buckets:

(-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

Console

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. In theUser-defined metrics pane, you see the user-definedlog-based metrics in the current Google Cloud project:

3. To view the data in a log-based metric, click themore_vertMenu inthe metric's row and selectView in Metrics Explorer.

gcloud

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

gcloud logging metrics list

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

gcloud logging metrics describeMETRIC_NAME

To get help, use the following command:

gcloud logging metrics --help

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

API

List metrics

To list the user-defined log-based metrics in a Google Cloud project, usetheprojects.metrics.list API method.Fill in the parameters to the method as follows:

• parent: The resource name of the Google Cloud project:projects/PROJECT_ID.
• pageSize: The maximum number of results.
• pageToken: Gets the next page of results. For informationabout using page tokens, seeprojects.metrics.list.

Retrieve metric definitions

To retrieve a single user-defined log-based metric, use theprojects.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

Read metric data

To read the time series data in a log-based metric, usetheprojects.timeseries.list in theCloud Monitoring API.For details on time series data, seeReading time series.

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

logging.googleapis.com/user/METRIC_ID

Console

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. ClickEdit metric in themore_vertMenufor the log-based metric that you want to modify.

3. Change the allowable items in the metric.

4. ClickUpdate metric.

gcloud

Use the Google Cloud CLI to change a counter metric's description, filterquery and bucket. You can update any or all of the fields at once.

gcloud logging updateMETRIC_NAME \  --description="METRIC_DESCRIPTION" \  --log-filter="FILTER" \  --bucket-name=BUCKET_NAME

If you change the bucket associated with a bucket-scoped metric, thenany metric data collected before the change no longer reflects thecurrent configuration. The metric data collected for the previous bucketis not removed.

To update distribution metrics or other counter metric fields, excluding theMETRIC_NAME, create a file that contains the revised specification ofyourLogMetric in JSON or YAML format. Then, update themetric by calling theupdate command with the --config-from-file field,replacingFILENAME with the name of your JSON or YAML file:

gcloud logging updateMETRIC_NAME --config-from-fileFILENAME

For more details, use the following command:

gcloud logging metrics update --help

API

To edit a log-based metric, use theprojects.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 aLogMetric object thatis exactly the same as the existing metric except for thechanges and additions you want to make.

Console

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. Select the metric you want to delete and clickDelete.

   Alternatively, clickDelete metric in themore_vertmenuof the log-based metric that you want to delete.

gcloud

Use the following command to delete a user-defined log-based metricin the current Google Cloud project:

gcloud logging metrics deleteMETRIC_NAME

For more details, use the following command:

gcloud logging metrics delete --help

API

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