custom-metrics

Vercel Custom Metrics

使用 Custom Metrics 记录由 Vercel Function 中运行的服务端代码发出的应用和业务数值指标。工作流为：使用 metric() 发出数值样本 → 调用已部署的函数 → 使用 vc metrics 或 Observability 发现并查询指标。

发出指标

安装或升级 @vercel/functions，然后从其根入口导入 metric：

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);
  }
}

签名如下：

metric(name: string, value: number, tags?: Record<string, string>): void

• name 用于标识一项稳定的度量，例如 orders.created 或 orders.duration_ms。
• value 是数值样本。对于要累加的增量，发出 1；对于持续时间、大小或评分，则发出观测值。
• tags 是可选的字符串属性。摄取后，发现的标签键会作为维度显示，可用于筛选和分组。
• metric() 是同步函数，返回 void；不要对它使用 await。
• 如果运行时不支持 Custom Metrics，此辅助函数会成为空操作。请通过调用已部署的 Vercel Function 验证埋点，而不要只在本地执行。

为实用查询设计指标

• 优先使用稳定的点分隔名称，并在适用时添加单位后缀：checkout.completed、checkout.duration_ms、queue.batch_size。
• 应用自定义名称时，不要使用保留前缀 vercel.。
• 将可变数据放在标签中，而不是指标名称中。使用 checkout.completed 和 { plan: 'pro' }，而不要使用 checkout.completed.pro。
• 限制标签的基数。适用的标签包括 outcome、plan、provider 或规范化后的路由。不要附加用户 ID、请求 ID、电子邮件地址、原始 URL 或其他唯一或敏感值。
• 在结果确定时发出一个样本。对于可重试或至少一次执行的工作，请确定要衡量的是尝试次数还是成功的逻辑操作，并据此命名指标。

选择与发出内容相匹配的查询聚合方式：

度量	发出方式	查询方式
发生次数或增量	metric('checkout.completed', 1)	sum 或 persecond
持续时间或大小	metric('checkout.duration_ms', duration)	avg、p75、p95、max
采样值	metric('queue.batch_size', size)	avg、min、max、百分位数

发现并查询指标

至少运行一次已部署的代码，然后使用已关联的项目和正确的团队范围：

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 和 vercel 等效。始终先使用 vc metrics schema <name> 检查具体指标，因为架构会报告可用的聚合方式和已发现的标签维度。当前关联或范围不明确时，使用 -S <team> 和 -p <project>；只有在有意进行团队范围查询时才使用 --all。

查询 Custom Metrics 需要 Observability Plus，且所选团队必须支持该功能。如果未找到指标：

1. 确认函数已部署到 Vercel，且实际运行了已埋点的代码路径。
2. 确认 @vercel/functions 导出了 metric；如有必要，请升级。
3. 检查 vc whoami、所选团队和已关联的项目。
4. 等待数据摄取完成，然后重新运行 vc metrics schema。
5. 确认团队已启用 Observability Plus 和 Custom Metrics。

使用恰当的信号

• 使用 Custom Metrics 记录要聚合、跟踪趋势和筛选的数值。
• 使用 Web Analytics 自定义事件记录 Web Analytics 中的用户交互和转化事件。
• 使用 OpenTelemetry spans 记录跟踪信息、操作耗时和请求因果关系。
• 使用 日志记录详细的诊断上下文和单条记录。

不要将详细的事件负载编码到指标标签中。如果排查问题需要查看单个请求的详细信息，请将低基数指标与结构化日志或跟踪信息结合使用。