custom-metrics

# 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: ```bash pnpm add @vercel/functions ``` ```ts 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: ```ts 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: ```bash 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: 1. Confirm the function was deployed to Vercel and the instrumented path actually ran. 2. Confirm `@vercel/functions` exports `metric`; upgrade it if necessary. 3. Check `vc whoami`, the selected team, and the linked project. 4. Allow for ingestion delay, then rerun `vc metrics schema`. 5. 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.