Metrics for Workers: 2026 Developer Glossary & Guide

Serverless edge runtimes have changed how applications get built, but they have also changed what “monitoring” means. When someone searches for metrics for workers, they are almost always asking about Cloudflare Workers, Vercel edge functions, or similar short-lived, stateless runtimes. They want to know what data is available, what each metric actually measures, and how to go beyond the built-in dashboard.

This glossary exists because no single reference page covers all the terminology in one place. Documentation pages define individual metrics. Tutorials walk through specific integrations. But developers who are instrumenting workers for the first time (or expanding their observability beyond defaults) need a quick, scannable reference that defines terms, explains context, and flags gotchas.

If you want a broader primer on telemetry concepts including logs, metrics, traces, and events, read about serverless telemetry and MELT.

Get started with Distlang Metrics, an API-first metrics service built for serverless workers, with no agents or infrastructure to manage.

Why Metrics for Workers Are Different

Traditional server monitoring assumes a long-running process. An agent sits on the host, scrapes a /metrics endpoint every 15 seconds, and ships data to a time-series database. Workers break every one of those assumptions.

Workers run in V8 isolates, not on hosts you control. There is no persistent process, no filesystem to write to, no agent to install. Each invocation starts fresh with no memory of previous requests. And the runtime can terminate the moment your handler finishes, sometimes before buffered data gets sent.

Practitioners on the Prometheus developers mailing list have called out the core tension directly: the fundamental problem is the mismatch of Prometheus’ pull architecture and the serverless runtime, which doesn’t even allow you to see individual container instances. Another developer on the same thread put it more bluntly: the real issue is metrics aggregation for services that can’t easily track their own state across multiple requests.

This matters because 58% of serverless engineers say observability is their biggest challenge. The Baselime founder (whose company was later acquired by Cloudflare) was candid about it: observing serverless applications is a pain. Observability vendors will try to convince you it’s not, but it is.

Three things make metrics for workers fundamentally different from traditional server metrics:

  1. No pull model. You must push metrics out from the worker, not wait for something to scrape them.
  2. Flush timing is critical. If you don’t send data before the handler terminates, it is lost. Period.
  3. Statelessness. You cannot accumulate a counter across requests the way a long-running server can. Every invocation starts at zero.

Understanding these constraints is the foundation for everything else in this glossary.

Platform Metrics (Built-in)

These are the metrics available out of the box when you deploy a Cloudflare Worker. They appear in your Workers dashboard without any instrumentation code.

Request Count

Total incoming requests registered by a worker, broken down into successes, errors, and subrequests. This is the first number most developers check, and it is useful for understanding traffic volume and spotting sudden spikes or drops.

Watch out for: Request count alone tells you nothing about quality. A worker serving 10,000 requests per minute can look healthy while silently returning errors on 20% of them.

Error Rate and Invocation Status

Error rate is the percentage of requests returning a failure status. Cloudflare breaks invocation status into specific categories: Success, Script Threw Exception, Exceeded Resources, Internal Error, and Client Disconnected. Errors include requests that returned “Script Threw Exception,” “Exceeded Resources,” or “Internal Error” invocation statuses.

Why it matters: “Exceeded Resources” specifically means your worker hit a CPU time or memory limit, which is a billing and reliability signal, not just a code bug. Tracking invocation status by type (not just a single error percentage) gives you much better diagnostic power.

CPU Time

CPU time measures how long the Workers runtime actually executed your JavaScript code. It excludes time spent waiting on network calls, KV reads, or any other I/O. This is the billing metric on many Cloudflare plans, so it directly affects your costs.

Watch out for: A worker with low CPU time but high wall time is spending most of its life waiting on external services. That is normal, but if CPU time spikes, look at your computation-heavy code paths first.

Wall Time

Wall time represents the elapsed real-world time from the start of a worker invocation to when the runtime determines no more JavaScript needs to run. This includes I/O wait time and time spent executing code inside waitUntil() handlers.

Why it matters: Wall time is what your users experience. A worker with 2ms of CPU time but 800ms of wall time is spending nearly all its time blocked on upstream APIs. Wall time is the metric that maps to perceived latency.

Subrequest Count

Subrequests are requests triggered by calling fetch() from within a worker. Cloudflare breaks these into cached and uncached subrequests.

Why it matters: Uncached subrequests hit origin servers and add latency. A high ratio of uncached to cached subrequests suggests opportunities for caching improvements. Cloudflare also enforces subrequest limits per invocation, so tracking this prevents hitting hard caps.

Memory Usage

The memory usage chart shows how much V8 isolate memory your worker uses at the time of each invocation, broken down into P50, P90, P99, and P999 percentiles. Workers run in V8 isolates with a 128 MB memory limit.

Watch out for: Memory usage that creeps toward the limit across percentiles suggests a memory leak or unbounded data structure. Because isolates can be reused across invocations, a leak in one request can affect the next.

For a deeper walkthrough on instrumenting these metrics on Cloudflare, see this guide on instrumenting Cloudflare Workers.

Metric Types (Instrumentation Fundamentals)

When you go beyond built-in dashboard metrics and start writing custom instrumentation, you need to understand the four fundamental metric types. These are not interchangeable. Each one preserves a different shape of information, and choosing wrong means your dashboards and alerts will mislead you.

Counter

A counter is a cumulative metric that only goes up (or resets to zero on restart). Use counters for things that accumulate: total requests handled, errors thrown, events processed, bytes transferred.

In workers context: Because each invocation is stateless, you are typically incrementing a counter for a single request and then flushing it. The aggregation happens server-side, not in your worker.

Gauge

A gauge represents a single value that can go up or down. Think of it as a snapshot: current memory usage, active connections, queue depth, temperature.

In workers context: Gauges are less common in workers because there is no persistent state to measure between invocations. They are more relevant for tracking things like “how many items are in this queue” via an external system.

Histogram

A histogram counts observations by placing them into configurable buckets. It is essentially a bucketed counter. Histograms are the right choice for latency, duration, and response size tracking because they preserve the distribution shape.

Why it matters: If you track response time as an average (or even a gauge), you lose the distribution. A histogram lets you answer “what percentage of requests took longer than 200ms” directly.

To learn how to implement these in practice, read about counters and histograms in JavaScript.

Summary

A summary samples observations and calculates quantiles over a sliding time window, while also providing a total count and sum. Summaries are powerful but come with a significant limitation: summary quantiles are calculated before central aggregation, which means combining them across instances, regions, or tenants can be misleading or even impossible.

When to use which: Does the value only go up? Use a counter. Is it a current snapshot? Gauge. Do you need the distribution? Histogram. Do you need pre-calculated quantiles and won’t aggregate across instances? Summary.

Serverless-Specific Concepts

These terms show up constantly in discussions about metrics for workers but rarely get defined clearly in one place.

Flush Semantics

Flush semantics describe the mechanism by which buffered metrics are sent from a short-lived handler before it terminates. In traditional servers, a metrics library can batch data and send it every 10 or 30 seconds. In a worker, the handler might live for 5 milliseconds total.

Batched data is sent asynchronously, and Cloudflare Workers can terminate before it is sent, causing data loss. This is why several SDKs targeting workers use aggressive defaults. FlareLog’s SDK, for example, automatically applies worker-optimized settings with batchSize: 1 and flushIntervalMs: 0 to prevent log loss on short-lived executions.

For a detailed treatment of this topic, see flush strategies for edge functions.

ctx.waitUntil()

ctx.waitUntil() is the Cloudflare Workers API that extends the handler’s lifetime to allow async operations (like flushing metrics) to complete after the response has already been sent to the client. This does not block the response but ensures background work finishes before the isolate terminates.

PostHog’s Workers documentation demonstrates this pattern clearly: use ctx.waitUntil() with their capture method so the event is captured before the worker shuts down. As a framework-agnostic alternative, you can import waitUntil from cloudflare:workers and call it from anywhere in your code.

For implementation details, read about waitUntil semantics for Workers.

after()

Vercel’s after() function serves the same purpose as ctx.waitUntil() but for Vercel’s edge and serverless functions. It runs code after the response is sent, which is exactly the lifecycle hook you need for flushing metrics without adding latency to the user’s request. For a walkthrough, see using after() in Vercel.

Cold Start

Functions that have not been invoked recently take longer to start. This latency is invisible to the function itself (your code does not “see” the cold start) but is very visible to users as added latency on the first request.

Why it matters for metrics: Cold starts inflate wall time and P99 latency numbers. If you are tracking response times, you need to understand that outlier latency is often cold starts, not slow code. Cloudflare Workers generally have much lower cold start times than traditional Lambda-style functions because V8 isolates are lighter than full containers.

Head Sampling Rate

Controls what fraction of invocations produce detailed telemetry. A sampling rate of 0.01 keeps 1% of traces. Practitioners on observability forums report keeping logs at a rate of 1 (capturing everything) so they never miss an error, while setting traces at 0.01 to control costs.

The tradeoff is real: High sampling rates give better visibility but generate more data (and cost). Low rates save money but can miss rare errors. For workers handling thousands of requests per second, a 1% trace sample rate with 100% error logging is a common and sensible default.

Metric Set

A logical grouping of related metrics defined together for a particular application or service. For example, you might have one metric set for your API worker (tracking request counts, latency histograms, error counters) and another for your webhook processor (tracking events received, processing duration, retry counts).

Try the Distlang Metrics quickstart to create your first metric set and see data on a dashboard in minutes.

Custom Metrics and Cardinality

Built-in platform metrics tell you whether your worker is running and how much resources it consumes. They do not tell you anything about your application’s business logic. That is where custom metrics come in.

Custom Business Metrics

These track events specific to your application: signups, purchases, feature usage, API key consumption, cache hit rates for your own logic. You define what to record and attach high-cardinality dimensions like customer IDs or API keys.

The gap between built-in metrics and custom business metrics is where most developers struggle. Cloudflare’s built-in dashboard gives you runtime information, but for application-specific analytics, you need a separate solution.

Cardinality

Cardinality is the number of unique values a metric label can take. A label like status_code with values 200, 404, 500 has low cardinality (3 values). A label like user_id on a platform with 100,000 users has high cardinality.

In a traditional metrics system like Prometheus, every time you add a new label value, you are actually adding a new time series under the hood. This is why high-cardinality labels can blow up storage costs and query performance in systems like Prometheus or InfluxDB. Event-based approaches handle high cardinality better because they store individual data points rather than pre-aggregated series.

For guidance on keeping cardinality under control, read about label naming and low-cardinality strategies.

Workers Analytics Engine

Cloudflare’s Workers Analytics Engine provides unlimited-cardinality analytics at scale. It offers a built-in API to write data points from workers and a SQL API to query that data. The free tier includes 10 million writes per month, with additional writes costing $0.25 per million.

This is Cloudflare’s answer to the custom metrics problem, but it is Cloudflare-only and requires learning its specific query syntax.

API-First Metrics Services

An alternative to platform-specific solutions is using an API-first metrics service that works across runtimes. Instead of installing agents or configuring exporters, you send metrics over HTTP from your worker code. This approach fits naturally with the push-based model that serverless demands. Distlang Metrics takes this approach, offering a lightweight JavaScript client that works with both Cloudflare Workers and Vercel without requiring any infrastructure setup.

Observability Metric Categories

Not all metrics answer the same question. A useful mental model splits them into three categories.

Resource Metrics

Resource metrics track system-level performance: CPU utilization, memory usage, disk I/O, network throughput. In the workers context, CPU time and memory usage are your primary resource metrics. You do not control the underlying infrastructure, so these are the only resource signals you get.

Application Metrics

Application metrics measure how your software operates: request rates, response times, error rates, cache hit ratios. The P95 response time of your API endpoint is an application metric. So is the ratio of successful to failed authentication attempts.

Business Metrics

Business metrics focus on outcomes: active users, revenue per feature, conversion rates, customer retention. These are the metrics that product managers and founders care about most, and they are the hardest to get from built-in dashboards because they require custom instrumentation.

The three-category model helps you decide what to track. Start with application metrics (request rate, error rate, latency). Add resource metrics when you hit performance issues. Layer in business metrics as your product matures and you need to connect technical performance to user outcomes.

For a broader treatment of these categories, see metrics types, KPIs, and best practices.

Percentiles and Quantiles Quick Reference

Percentile breakdowns show the value below which a given percentage of observations fall. They are the standard way to understand the distribution of latency, CPU time, or any other duration-based metric.

P50 (median): Half of all observations are below this value. Useful as a baseline, but it hides tail latency completely. If your P50 response time is 12ms, that tells you nothing about the 5% of users waiting 500ms or more.

P90: 90% of observations fall below this value. A good general indicator of “most users’ experience.”

P99: 99% of observations fall below this value. This is the metric that matters most for SLO and SLA work. If your SLA promises 200ms response times, your P99 needs to be under 200ms, not your average.

P999: 99.9% of observations fall below this value. Relevant for high-traffic services where even 0.1% of requests represent thousands of users.

Cloudflare’s Workers dashboard reports memory usage in P50, P90, P99, and P999 percentiles by default. Worker metrics can be inspected for up to 3 months in the past. When you instrument custom metrics, histogram buckets give you the raw data to compute any percentile you need.

Vercel Edge Function Metrics

While most search results for metrics for workers focus on Cloudflare, Vercel’s edge functions have their own metrics vocabulary worth knowing.

Invocations: The total number of times an edge function was called. Analogous to Cloudflare’s request count.

Execution Units: Vercel bills edge functions in 50ms CPU time increments, which they call execution units. If your function uses 80ms of CPU time, that counts as 2 execution units. This billing model makes CPU time optimization directly tied to cost.

Fast Origin Transfer: A Vercel-specific optimization where requests are routed more efficiently to origin servers. Tracked as a separate metric in Vercel’s dashboard.

The key difference: Cloudflare gives you granular percentile breakdowns of memory and CPU in the dashboard. Vercel abstracts more aggressively into execution units. Both require the same flush-after-response pattern for custom metrics, just with different lifecycle hooks (ctx.waitUntil() vs. after()).

Tooling Comparison at a Glance

Developers tracking metrics for workers have several options. Here is how they compare on the dimensions that matter most.

Tool Best for Cardinality handling Cost model
Cloudflare Dashboard Quick built-in metrics overview N/A (fixed metrics) Free with Workers plan
Workers Analytics Engine Custom high-cardinality analytics Unlimited cardinality 10M writes/mo free, then $0.25/M
Workers Logs Detailed request-level debugging Event-based 20M events free on paid plan, $0.60/M after
Grafana Cloud Familiar dashboards, OTel integration Depends on backend $0.40/GB logs after 50 GB/mo free
Distlang Metrics API-first custom metrics, no infra Event-based Free tier with 500K rows/mo
Datadog/New Relic Full APM with traces and logs Varies by plan Per-host or per-event pricing

The main limitations of Cloudflare’s native tools are that the Query Builder is less flexible than dedicated observability platforms, and there is no built-in anomaly detection or sophisticated alerting beyond basic notifications. This is where third-party tools and API-first services fill the gap.

Putting It All Together

If you are just getting started with metrics for workers, focus on three things:

  1. Understand your built-in metrics. CPU time, wall time, error rate, and memory usage are available without writing any code. Learn what normal looks like for your worker before you start customizing.

  2. Get flush semantics right from day one. Use ctx.waitUntil() on Cloudflare or after() on Vercel. If you skip this step, you will lose data on short-lived invocations and spend hours debugging phantom gaps in your metrics.

  3. Add custom metrics when you need business answers. Built-in metrics tell you if your worker is healthy. Custom metrics tell you if your product is working. Start with a counter for your most important event and a histogram for your most important duration.

See an end-to-end example that takes you from application code to a working dashboard in minutes.

FAQ

What are metrics for workers in the context of Cloudflare?

Metrics for workers are the observability data points that track the performance, resource usage, and behavior of Cloudflare Workers. Built-in metrics include request count, CPU time, wall time, error rate, subrequest count, and memory usage. Custom metrics extend this to track application-specific events like signups or purchases.

Why can’t I use Prometheus to monitor Cloudflare Workers?

Prometheus uses a pull-based model where it scrapes a /metrics endpoint on a running server at regular intervals. Workers run in ephemeral V8 isolates with no persistent endpoint to scrape and no way to install an agent. You need to push metrics out from the worker, which requires a push-based service or an OpenTelemetry exporter configured for push.

What is the difference between CPU time and wall time in workers?

CPU time measures only the milliseconds your JavaScript code was actively executing on the CPU. Wall time measures the total elapsed time from invocation start to completion, including time spent waiting on network requests, KV reads, and waitUntil() handlers. A worker with 5ms CPU time and 300ms wall time is spending most of its life waiting on I/O.

How do I prevent metrics data loss in serverless workers?

Use ctx.waitUntil() on Cloudflare Workers or after() on Vercel to extend the handler’s lifetime after the response is sent. Configure aggressive flush settings (small batch sizes, zero-delay flush intervals) to ensure data is sent before the runtime terminates. Without these steps, buffered metrics will be silently dropped.

What is cardinality and why does it matter for worker metrics?

Cardinality is the number of unique values a metric label can take. A label like region might have 10 values (low cardinality), while user_id could have millions (high cardinality). Traditional time-series databases like Prometheus create a new series for every unique label combination, making high cardinality expensive. Event-based systems handle high cardinality more gracefully.

Should I use a histogram or a summary for tracking latency in workers?

Use a histogram. Histograms allow server-side aggregation across instances and regions, which is exactly what you need in a distributed, stateless environment. Summaries calculate quantiles client-side before aggregation, making it impossible to combine them meaningfully across multiple worker invocations or regions.

How long does Cloudflare retain worker metrics data?

Cloudflare retains worker metrics for up to 3 months in the dashboard. For custom metrics via Workers Analytics Engine or third-party tools, retention depends on your plan and provider. Workers Logs on the free plan retains 200,000 log events per day for 3 days.

What metrics should I track first when deploying a new worker?

Start with error rate and CPU time. Error rate tells you if things are broken. CPU time tells you if things are expensive. Add wall time to understand user-facing latency, then layer in custom business metrics (like conversion events or feature usage) once the worker is stable in production.