Emit Custom Metrics from Vercel Functions
Custom metrics let you record application-specific numeric values from your Vercel Functions. Each call to metric() records a data point that you can query and chart in Observability.
For example, you could emit metrics to measure database queries latency, record the number of signups, or count the requests per second of a specific endpoint.
- Install the
@vercel/functionspackage:
pnpm i @vercel/functionsyarn add @vercel/functionsnpm i @vercel/functionsbun add @vercel/functions- Import
metricand call it from a Vercel Function with a metric name, numeric value, and optional attributes:
import { metric } from '@vercel/functions';
metric('query.duration_ms', 100, { plan: 'pro' });The example records a value of 100 for query.duration_ms and adds plan as an attribute. You can use attributes to filter and group the metric in Observability.
The metric() function accepts the following parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The custom metric name, such as query.duration_ms. |
value | number | Yes | The numeric value to record (64-bit floating-point). |
attributes | Record<string, string> | No | String attributes that you can use to filter and group the metric. |
Metric names, attribute names, and attribute values must be non-empty and shorter than 64 bytes. They can contain ASCII letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_), periods (.), and slashes (/). Unsupported characters are automatically replaced with an underscore (_). For example, data+summary is stored as data_summary.
For example, this data point is valid:
metric('query.duration_ms', 100, { data_summary: 'pro/v1' });- Each custom metric emission can include up to 50 user-supplied attributes.
- Each Vercel Function invocation can emit up to 100 custom metrics.
Vercel automatically attributes each custom metric data point with the following metadata. You don't need to include these fields in the attributes object:
| Field | Description |
|---|---|
deploymentId | Vercel deployment that emitted the metric. |
requestId | Request that emitted the metric. |
functionRegion | Region where the function emitted the metric. |
pathType | Execution path type that emitted the metric. |
edgeNetworkRegion | Vercel CDN region that handled the request. |
After you deploy and invoke the Vercel Function, you can access custom metrics data from the dashboard, the Query tab, or the Vercel CLI:
- Custom Metrics dashboard: From your project or team dashboard, select the Observability tab, then select Custom Metrics. Use this view to browse recently active metrics and configure how their values appear in charts.
- Query tab: From Observability, select the Query tab, then select a metric from the Custom Metrics group. Use this view to aggregate metric values and filter or group results by the attributes passed to
metric(). - Vercel CLI: Use the
vercel metricscommand to list and query custom metrics from your terminal.
List all available metrics:
vercel metrics schemaQuery a custom metric and filter it by an attribute:
vercel metrics database.duration_ms --filter "plan:pro"Each custom metric data point counts as one Observability event. Vercel charges $1.20 per 1 million Observability events.
For example, emitting one custom metric during each of 1 million function invocations records 1 million Observability events. To stop collecting custom metrics, remove the metric() calls from your application.
Was this helpful?