Vercel Custom Metrics
Use Custom Metrics for numeric application and business measurements emitted by server-side code running in a Vercel Function. The workflow is emit a numeric sample with metric() → invoke the deployed function → discover and query the metric with vc metrics or Observability.
Emit a metric
Install or upgrade @vercel/functions, then import metric from its root entry point:
pnpm add @vercel/functions
import { metric } from '@vercel/functions';
export async function POST() {
const startedAt = performance.now();
try {
await createOrder();
metric('orders.created', 1, { outcome: 'success' });
return Response.json({ ok: true });
} catch (error) {
metric('orders.created', 1, { outcome: 'error' });
throw error;
} finally {
metric('orders.duration_ms', performance.now() - startedAt);
}
}
The signature is:
metric(name: string, value: number, tags?: Record<string, string>): void
name identifies one stable measurement, such as orders.created or orders.duration_ms.
value is the numeric sample. Emit 1 for an increment that will be summed; emit the observed value for a duration, size, or score.
tags are optional string attributes. After ingestion, discovered tag keys appear as dimensions for filtering and grouping.
metric() is synchronous and returns void; do not await it.
- The helper is a no-op when the runtime does not expose Custom Metrics support. Verify instrumentation through a deployed Vercel Function invocation, not local execution alone.
Model metrics for useful queries
- Prefer stable, dotted names with a unit suffix where useful:
checkout.completed, checkout.duration_ms, queue.batch_size.
- Do not use the reserved
vercel. prefix for application-defined names.
- Keep variable data in tags instead of metric names. Use
checkout.completed with { plan: 'pro' }, not checkout.completed.pro.
- Keep tag cardinality bounded. Good tags are
outcome, plan, provider, or a normalized route. Do not attach user IDs, request IDs, email addresses, raw URLs, or other unique or sensitive values.
- Emit one sample at the point where the outcome is known. For retryable or at-least-once work, decide whether attempts or successful logical operations are the intended measurement and name the metric accordingly.
Choose the query aggregation to match what was emitted:
| Measurement |
Emit |
Query |
| Occurrence or increment |
metric('checkout.completed', 1) |
sum or persecond |
| Duration or size |
metric('checkout.duration_ms', duration) |
avg, p75, p95, max |
| Sampled level |
metric('queue.batch_size', size) |
avg, min, max, percentiles |
Discover and query the metric
Run the deployed code at least once, then use the linked project and correct team scope:
vc metrics schema
vc metrics schema orders.duration_ms
vc metrics orders.created -a sum --group-by outcome --since 24h
vc metrics orders.duration_ms -a p95 --since 1h
vc metrics orders.duration_ms -a p95 --group-by outcome --since 24h --format=json
vc and vercel are equivalent. Always inspect the exact metric first with vc metrics schema <name> because the schema reports the available aggregations and discovered tag dimensions. Use -S <team> and -p <project> when the current link or scope is ambiguous; use --all only for a deliberate team-wide query.
Custom Metrics querying requires Observability Plus and availability for the selected team. If a metric is missing:
- Confirm the function was deployed to Vercel and the instrumented path actually ran.
- Confirm
@vercel/functions exports metric; upgrade it if necessary.
- Check
vc whoami, the selected team, and the linked project.
- Allow for ingestion delay, then rerun
vc metrics schema.
- Confirm Observability Plus and Custom Metrics are enabled for the team.
Use the right signal
- Use Custom Metrics for numeric values you want to aggregate, trend, and filter.
- Use Web Analytics custom events for user interaction and conversion events in Web Analytics.
- Use OpenTelemetry spans for traces, operation timing, and request causality.
- Use logs for detailed diagnostic context and individual records.
Do not encode detailed event payloads into metric tags. Pair a low-cardinality metric with structured logs or traces when investigation needs per-request detail.
1---2name: custom-metrics3description: Emit and query Vercel Custom Metrics. Use when instrumenting application or business measurements in Vercel Functions, using metric() from @vercel/functions, choosing metric names and attributes, or querying emitted values with vc metrics.4summary: Emit numeric measurements from Functions and query them with vc metrics5metadata:6 source: https://skillmd.com/skills/agents-store/custom-metrics7 priority: 98 docs:9 - "https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package"10 - "https://vercel.com/docs/cli/metrics"11 - "https://vercel.com/docs/observability/observability-plus"12 sitemap: "https://vercel.com/sitemap/docs.xml"13 pathPatterns: []14 bashPatterns:15 - '\b(?:vercel|vc)\s+metrics\s+(?!schema(?:\s|$)|vercel\.)[A-Za-z_][A-Za-z0-9_./-]*\b'16 - '\b(?:vercel|vc)\s+metrics\s+schema\s+(?!vercel\.)[A-Za-z_][A-Za-z0-9_./-]*\b'17 importPatterns: []18 promptSignals:19 phrases:20 - "custom metric"21 - "custom metrics"22 - "emit a metric"23 - "emit metrics"24 - "report a metric"25 - "report metrics"26 - "application metrics"27 - "business metrics"28 - "@vercel/functions metric"29 allOf:30 - [emit, metric]31 - [report, metric]32 - [instrument, metric]33 - [vercel, metric]34 anyOf:35 - "observability"36 - "instrumentation"37 - "duration"38 - "counter"39 - "percentile"40 noneOf:41 - "font metrics"42 - "core web vitals"43 minScore: 644retrieval:45 aliases:46 - Vercel application metrics47 - Vercel business metrics48 - function metrics49 - vc metrics50 intents:51 - emit a custom metric52 - instrument a Vercel Function53 - query a custom metric54 - measure application behavior55 entities:56 - metric57 - "@vercel/functions"58 - Vercel Custom Metrics59 - vc metrics60 - Observability Plus61 examples:62 - emit checkout duration as a custom metric63 - add a business counter to this Vercel Function64 - query my custom metric with vc metrics65 - group an application metric by outcome66---6768# Vercel Custom Metrics6970Use Custom Metrics for numeric application and business measurements emitted by server-side code running in a Vercel Function. The workflow is **emit a numeric sample with `metric()` → invoke the deployed function → discover and query the metric with `vc metrics` or Observability**.7172## Emit a metric7374Install or upgrade `@vercel/functions`, then import `metric` from its root entry point:7576```bash77pnpm add @vercel/functions78```7980```ts81import { metric } from '@vercel/functions';8283export async function POST() {84 const startedAt = performance.now();8586 try {87 await createOrder();88 metric('orders.created', 1, { outcome: 'success' });89 return Response.json({ ok: true });90 } catch (error) {91 metric('orders.created', 1, { outcome: 'error' });92 throw error;93 } finally {94 metric('orders.duration_ms', performance.now() - startedAt);95 }96}97```9899The signature is:100101```ts102metric(name: string, value: number, tags?: Record<string, string>): void103```104105- `name` identifies one stable measurement, such as `orders.created` or `orders.duration_ms`.106- `value` is the numeric sample. Emit `1` for an increment that will be summed; emit the observed value for a duration, size, or score.107- `tags` are optional string attributes. After ingestion, discovered tag keys appear as dimensions for filtering and grouping.108- `metric()` is synchronous and returns `void`; do not `await` it.109- The helper is a no-op when the runtime does not expose Custom Metrics support. Verify instrumentation through a deployed Vercel Function invocation, not local execution alone.110111## Model metrics for useful queries112113- Prefer stable, dotted names with a unit suffix where useful: `checkout.completed`, `checkout.duration_ms`, `queue.batch_size`.114- Do not use the reserved `vercel.` prefix for application-defined names.115- Keep variable data in tags instead of metric names. Use `checkout.completed` with `{ plan: 'pro' }`, not `checkout.completed.pro`.116- Keep tag cardinality bounded. Good tags are `outcome`, `plan`, `provider`, or a normalized route. Do not attach user IDs, request IDs, email addresses, raw URLs, or other unique or sensitive values.117- Emit one sample at the point where the outcome is known. For retryable or at-least-once work, decide whether attempts or successful logical operations are the intended measurement and name the metric accordingly.118119Choose the query aggregation to match what was emitted:120121| Measurement | Emit | Query |122| --- | --- | --- |123| Occurrence or increment | `metric('checkout.completed', 1)` | `sum` or `persecond` |124| Duration or size | `metric('checkout.duration_ms', duration)` | `avg`, `p75`, `p95`, `max` |125| Sampled level | `metric('queue.batch_size', size)` | `avg`, `min`, `max`, percentiles |126127## Discover and query the metric128129Run the deployed code at least once, then use the linked project and correct team scope:130131```bash132vc metrics schema133vc metrics schema orders.duration_ms134135vc metrics orders.created -a sum --group-by outcome --since 24h136vc metrics orders.duration_ms -a p95 --since 1h137vc metrics orders.duration_ms -a p95 --group-by outcome --since 24h --format=json138```139140`vc` and `vercel` are equivalent. Always inspect the exact metric first with `vc metrics schema <name>` because the schema reports the available aggregations and discovered tag dimensions. Use `-S <team>` and `-p <project>` when the current link or scope is ambiguous; use `--all` only for a deliberate team-wide query.141142Custom Metrics querying requires Observability Plus and availability for the selected team. If a metric is missing:1431441. Confirm the function was deployed to Vercel and the instrumented path actually ran.1452. Confirm `@vercel/functions` exports `metric`; upgrade it if necessary.1463. Check `vc whoami`, the selected team, and the linked project.1474. Allow for ingestion delay, then rerun `vc metrics schema`.1485. Confirm Observability Plus and Custom Metrics are enabled for the team.149150## Use the right signal151152- Use **Custom Metrics** for numeric values you want to aggregate, trend, and filter.153- Use **Web Analytics custom events** for user interaction and conversion events in Web Analytics.154- Use **OpenTelemetry spans** for traces, operation timing, and request causality.155- Use **logs** for detailed diagnostic context and individual records.156157Do not encode detailed event payloads into metric tags. Pair a low-cardinality metric with structured logs or traces when investigation needs per-request detail.