/custom-metrics

name: custom-metrics
description: 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.
summary: Emit numeric measurements from Functions and query them with vc metrics
metadata:
  priority: 9
  docs:
    - "https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package"
    - "https://vercel.com/docs/cli/metrics"
    - "https://vercel.com/docs/observability/observability-plus"
  sitemap: "https://vercel.com/sitemap/docs.xml"
  pathPatterns: []
  bashPatterns:
    - '\b(?:vercel|vc)\s+metrics\s+(?!schema(?:\s|$)|vercel\.)[A-Za-z_][A-Za-z0-9_./-]*\b'
    - '\b(?:vercel|vc)\s+metrics\s+schema\s+(?!vercel\.)[A-Za-z_][A-Za-z0-9_./-]*\b'
  importPatterns: []
  promptSignals:
    phrases:
      - "custom metric"
      - "custom metrics"
      - "emit a metric"
      - "emit metrics"
      - "report a metric"
      - "report metrics"
      - "application metrics"
      - "business metrics"
      - "@vercel/functions metric"
    allOf:
      - [emit, metric]
      - [report, metric]
      - [instrument, metric]
      - [vercel, metric]
    anyOf:
      - "observability"
      - "instrumentation"
      - "duration"
      - "counter"
      - "percentile"
    noneOf:
      - "font metrics"
      - "core web vitals"
    minScore: 6
retrieval:
  aliases:
    - Vercel application metrics
    - Vercel business metrics
    - function metrics
    - vc metrics
  intents:
    - emit a custom metric
    - instrument a Vercel Function
    - query a custom metric
    - measure application behavior
  entities:
    - metric
    - "@vercel/functions"
    - Vercel Custom Metrics
    - vc metrics
    - Observability Plus
  examples:
    - emit checkout duration as a custom metric
    - add a business counter to this Vercel Function
    - query my custom metric with vc metrics
    - group an application metric by outcome

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 --aggregation sum --group-by outcome --since 24h
vc metrics orders.duration_ms --aggregation p95 --since 1h
vc metrics orders.duration_ms --aggregation p95 --group-by outcome --since 24h --json

`vc` and `vercel` are equivalent. Use `--aggregation`; `-a` still works but is a deprecated shorthand. Use `--json` for machine-readable output (CLI 58.1+; older CLIs use `--format=json`). 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