GCP Log-Based Metrics Explained: Counters, Distributions, Alerts

Simple explanation

Cloud Logging receives log entries from your services. Cloud Monitoring stores numeric time-series data. These two systems work together but serve different purposes: logs are events, metrics are numbers over time.

Log-based metrics bridge the two. You write a Logging Query Language filter that matches specific log entries, for example every ERROR log from your payment service. Cloud Logging applies that filter as entries arrive, increments a counter (or extracts a value), and sends the result to Cloud Monitoring as a time-series metric. From that point, it behaves exactly like any other GCP metric: you can chart it, set thresholds, and attach alerts.

The key insight: your application does not need to know this metric exists. If the signal is already in your logs, you can make it observable without touching your code.

Why teams use log-based metrics

• Count recurring errors. You know your service logs a specific error message when a downstream call fails. A counter metric lets you alert when that error appears more than N times per minute.
• Track latency from structured logs. If your service emits structured JSON logs with a duration_ms field, a distribution metric lets you chart p99 latency without adding an instrumentation library.
• Monitor business events in logs. Order placed, payment declined, user signup. These signals may already be in your application logs. Log-based metrics expose them to Cloud Monitoring dashboards without new instrumentation.
• Alert on patterns without adding code. A third-party library you cannot modify logs a deprecation warning. A log-based counter lets you alert when that warning appears, without touching the library.
• Get visibility faster. Deploying a new metric instrumentation library takes days. Writing a log-based metric filter takes minutes. For rapid incident investigation or short-lived signals, log-based metrics are often the fastest path.

How log-based metrics work

The flow has five steps:

1. Logs arrive in Cloud Logging. Your services, infrastructure, and GCP-managed resources write log entries continuously.
2. A filter selects matching entries. You define a Logging Query Language (LQL) filter that matches the entries you care about. This is the same filter syntax used in Logs Explorer.
3. Cloud Logging converts matches into a metric. For each matching entry, Cloud Logging either increments a counter or extracts a numeric value, depending on the metric type you chose.
4. Cloud Monitoring stores the time series. The resulting metric data lands in Cloud Monitoring under the logging.googleapis.com/user/ namespace.
5. You chart, alert, and investigate. The metric is now available in Metrics Explorer, dashboards, and alerting policies.

Counter metrics vs distribution metrics

Log-based metrics come in two types. Choosing the right one depends on the question you are trying to answer.

Counter metrics

A counter metric increments by 1 for each log entry that matches the filter. Use counters when you care about frequency: how many errors, how many retries, how many auth failures. Counter metrics are cumulative, meaning the value only goes up. In Metrics Explorer, apply a rate alignment to see counts per minute or per second rather than a monotonically increasing total.

Distribution metrics

A distribution metric extracts a numeric value from a specified field in each matching log entry and records the statistical distribution of those values over each time window. You define a value extractor that points to the field, for example EXTRACT(jsonPayload.duration_ms).

Use distribution metrics when you care about the spread: p99 latency from HTTP access logs, the distribution of order amounts from a payment service, or the range of database query durations from a slow query log. You need structured logs with numeric fields to use distribution metrics effectively.

Log-based metrics vs log-based alerts vs custom application metrics

These three approaches sound similar but are different tools. Here is how to choose between them.

Use a log-based metric when you want to chart trends over time, set threshold-based alerts with duration conditions, or combine the signal with other metrics on a dashboard. Use a log-based alert when you want an immediate notification on a specific log entry and do not need time-series history. Use custom application metrics when the signal does not appear in logs at all.

Project-scoped vs bucket-scoped log-based metrics

Log-based metrics come in two scopes that determine which log entries they can filter against.

Project-scoped metrics (the default)

A project-scoped log-based metric filters across all log entries in the project’s _Default log bucket. This is the standard type. When you create a metric through the console or with gcloud logging metrics create without specifying a bucket, you get a project-scoped metric.

Bucket-scoped metrics

A bucket-scoped log-based metric filters against log entries in a specific named log bucket. This matters when your organization routes logs to non-default buckets, such as a dedicated analytics bucket, a bucket in a centralized logging project, or a bucket with a custom retention policy.

If your organization routes application logs to a bucket named app-logs in a separate logging project, a project-scoped metric in the originating project will not see those routed entries. A bucket-scoped metric targeting app-logs will. You create bucket-scoped metrics through the Cloud Logging API or the Log-based Metrics page in the console by specifying the full bucket resource path.

Prerequisites and limitations

• Permissions. Creating log-based metrics requires the logging.logMetrics.create permission. The roles/logging.admin role includes this. If you get a permission error, check with your project owner.
• No historical backfill. Metrics only capture data from the moment of creation. Past log entries are not processed.
• Label cardinality. Each unique combination of label values creates a separate time series. High-cardinality labels like user IDs or request IDs create enormous numbers of time series, increasing cost and degrading query performance.
• Filter uses Logging Query Language. The filter is LQL, the same syntax used in Logs Explorer, not SQL. The : operator is a substring match; =~ is regex.
• Data delay. After creating a metric, expect a few minutes before data appears in Cloud Monitoring. This is normal propagation delay.
• Distribution metrics require numeric fields. The target field must be a number in the log payload. You cannot extract a string field as a distribution value.

Create a log-based metric in the console

The console is the easiest starting point, especially when building your filter iteratively.

1. Open Cloud Logging in the GCP Console and go to Log-based Metrics in the left sidebar.
2. Click Create Metric and choose Counter or Distribution.
3. Give the metric a name and description. Names must be unique within the project.
4. Write your filter in the Build filter box. Test the filter in Logs Explorer first to confirm it matches the right entries before saving.
5. For distribution metrics, specify the value extractor field path, for example jsonPayload.duration_ms.
6. Optionally add labels by specifying field paths and extractor expressions.
7. Click Create Metric. Data will begin appearing in Cloud Monitoring within a few minutes.

Once created, view the metric in Metrics Explorer by searching for its name under the logging.googleapis.com/user/ namespace.

Create a log-based metric with gcloud

The gcloud logging metrics create command handles both counters and distribution metrics. Use this for scripting metric setup as part of infrastructure provisioning.

Counter metric

# Count ERROR logs from a specific Cloud Run service
gcloud logging metrics create api-error-count \
  --description="Count of error log entries from api-service" \
  --log-filter='severity>=ERROR
    resource.type="cloud_run_revision"
    resource.labels.service_name="api-service"'

Distribution metric

# Distribution of request durations extracted from structured logs
gcloud logging metrics create api-request-duration \
  --description="Distribution of request durations in milliseconds" \
  --log-filter='resource.type="cloud_run_revision"
    resource.labels.service_name="api-service"
    jsonPayload.message="Request completed"' \
  --value-extractor='EXTRACT(jsonPayload.duration_ms)'

The structured log entry this reads from would look like:

{
  "severity": "INFO",
  "message": "Request completed",
  "duration_ms": 142,
  "endpoint": "/api/orders",
  "status_code": 200
}

Common operations

# List all log-based metrics in a project
gcloud logging metrics list --project=my-project

# Describe a specific metric
gcloud logging metrics describe api-error-count --project=my-project

# Delete a metric
gcloud logging metrics delete api-error-count --project=my-project

Add labels carefully

Labels let you break a metric into dimensions. A request duration metric labeled by endpoint gives you a separate time series per API path, so you can compare p99 latency for /api/orders vs /api/users. This is powerful, and it is also where most teams accidentally create expensive problems.

Low-cardinality vs high-cardinality

Low-cardinality labels have a small, bounded set of possible values: HTTP method (GET, POST, DELETE: five values at most), status code category (2xx, 4xx, 5xx: three values), environment (prod, staging: two values). Each unique label value adds one time series per metric. A label with five possible values adds five time series. That is fine.

High-cardinality labels have unbounded or very large value sets: user ID, request ID, session token, IP address, order ID. If your service handles 100,000 unique users, extracting jsonPayload.user_id as a label creates 100,000 time series. This inflates Cloud Monitoring costs, degrades query performance, and can trigger quota limits. See Metrics in GCP for a deeper explanation of how label cardinality affects time-series storage.

# Safe: low-cardinality label (bounded set of HTTP methods)
gcloud logging metrics create request-count-by-method \
  --description="Request count by HTTP method" \
  --log-filter='resource.type="cloud_run_revision"
    resource.labels.service_name="api-service"' \
  --label-extractors='http_method=EXTRACT(jsonPayload.method)'

# Avoid: high-cardinality label (unique per request, creates millions of time series)
# --label-extractors='request_id=EXTRACT(jsonPayload.request_id)'

Use log-based metrics in dashboards and alerts

Once created, log-based metrics appear in Cloud Monitoring under the logging.googleapis.com/user/ namespace and behave like any other metric in the platform.

Metrics Explorer and dashboards

Open Metrics Explorer, search for your metric by name under the logging.googleapis.com/user/ namespace, and add it to a chart. From there, add the chart to a Cloud Monitoring dashboard. Counter metrics are cumulative, so apply a rate alignment to see per-minute counts rather than a monotonically increasing total.

Alerting policies

Log-based metrics work as conditions in alerting policies. Create an alerting policy, add a metric-threshold condition, and select your log-based metric. You can alert when an error count exceeds a threshold per minute, when p99 latency from a distribution metric goes above a value, or when a counter drops to zero (metric absence).

Log-based metrics are especially useful during production debugging because they let you slice a signal by log field values rather than just by resource or service. An error count labeled by endpoint tells you which path is failing. Without the label, you only know something is wrong.

When to use log-based metrics

• Your application already emits structured logs with numeric fields, and you want those as metrics without code changes.
• You need to count occurrences of a specific error message, warning, or business event that appears in logs.
• You are monitoring a service you cannot modify: a third-party component, a managed GCP service with limited metric output, or a legacy system.
• You need a quick signal during an ongoing incident, faster than deploying new instrumentation.
• You are monitoring Cloud Run or monitoring GKE workloads that already produce structured log output.
• You want to monitor a log-defined condition over time with threshold alerting, not just receive a one-time notification.

When not to use log-based metrics

• The signal is not in your logs. Log-based metrics cannot measure something your application does not log. For signals that require code instrumentation, use custom metrics via OpenTelemetry or the Cloud Monitoring API.
• You need sub-minute resolution. Log-based metrics aggregate over time windows. If you need second-by-second visibility, application-level metrics are more appropriate.
• A built-in metric already exists. Cloud Run, GKE, Cloud SQL, and most GCP services emit rich built-in metrics. Check what is available before building a log-based metric for something already measured.
• You need historical data from before today. If you need to analyze logs retrospectively, use Logs Explorer or export to BigQuery. Log-based metrics only go back to when the metric was created.
• Your log volume is extremely high and the filter is broad. Very high-volume log streams with broad filters have cardinality and cost implications. Consider log sampling or BigQuery exports for batch analysis instead.