Index of every page on this site: llms.txt
All skills
vercel avatar

/custom-metrics

@250769d official
by vercelvercel/vercel-plugin340 stars
82
Run it yourself

Emit and query Vercel Custom Metrics. Use proactively whenever you write or change server code that runs as a Vercel Function (route handlers, API routes, server actions, webhooks, scheduled jobs, queue consumers, AI or external API calls) to record outcomes and latency with metric() from @vercel/functions, even when the user did not ask for metrics. Also use when choosing metric names and attributes or querying emitted values with vc metrics.

Use this Skill: https://skilld.dev/gh/vercel/vercel-plugin/custom-metrics

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈116 tokens for metadata: the name and description. ≈1.7k when used: this file.

Description uses 5.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈464 characters, or 5.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Add metrics proactively

Do not wait for the user to ask. When you create or meaningfully change server code that runs as a Vercel Function, add metric() calls in the same change if the code does work someone would want to watch in production:

  • Business events: signups, orders, payments, checkouts, invites, subscriptions.
  • Calls to slow or fallible dependencies: AI model calls, external APIs, databases, caches, queues. Record duration and outcome.
  • Background work: webhooks, scheduled jobs, queue consumers, workflow steps. Record processed counts, failures, and batch sizes.
  • AI features: token usage, model, latency, and tool-call outcomes.

Keep it small: usually one outcome counter and one duration per handler or dependency call, tagged with outcome and one or two other bounded attributes. Skip trivial handlers (health checks, static redirects, pure pass-through proxies), client components, and code that does not run in a Vercel Function.

metric() is safe to add by default once @vercel/functions is 3.9.0 or later; check the installed version and upgrade it in the same change if it is older. It is synchronous, does not need awaiting, and is a no-op when the runtime does not support Custom Metrics (for example local development or another host), so it does not break those environments.

Custom Metrics are available on Pro and Enterprise with Observability Plus, and each metric() call is billed as one Observability event ($1.20 per 1M). A function can call metric() at most 100 times per invocation. Emit once per logical operation, not inside tight loops or once per item of a large batch; record a batch total or size instead.

When you add metrics, say so in one line of your summary and list the metric names, so the user can find them with vc metrics schema or in Observability.

If the project already uses a third-party metrics SDK (Datadog, StatsD, Prometheus, OpenTelemetry metrics), do not remove it unasked. For new metrics in Vercel Functions, prefer metric() unless the user wants everything in the existing tool.

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 is 3.9.0 or later, the first version that 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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert2d3 checks · Risk SAFE
  • Gen Agent Trust Hub2d

    This skill facilitates the instrumentation and querying of Vercel Custom Metrics. It follows standard practices for the Vercel platform, including the use of official packages and CLI tools.

  • Socket2d

    No alerts

  • Snyk2d

    Risk: CRITICAL · 1 issue

Signed by skilld at 250769d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 5 days ago
Other metadata
summary
When writing Vercel Function code that does meaningful work, add a few low-cardinality metric() calls from @vercel/functions for outcomes and latency without being asked; query them with vc metrics
metadata
{
  "priority": 9,
  "docs": [
    "https://vercel.com/docs/observability/custom-metrics",
    "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",
      "add monitoring",
      "add instrumentation",
      "track latency",
      "statsd",
      "prometheus metrics",
      "datadog metrics"
    ],
    "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",
    "add monitoring to an API route",
    "replace a third-party metrics SDK in a Vercel Function"
  ],
  "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"
  ]
}

README badge

README badge for vercel/vercel-plugin/custom-metrics