From e6cbaf4d1d201a67aebd9903893f475a202c0f2e Mon Sep 17 00:00:00 2001 From: Julia Shi Date: Wed, 6 May 2026 13:06:34 +0100 Subject: [PATCH] Add Vercel metrics CLI guidance --- .claude-plugin/plugin.json | 2 +- .cursor-plugin/plugin.json | 2 +- .plugin/plugin.json | 2 +- commands/status.md | 7 +++++-- commands/status.md.tmpl | 7 +++++-- generated/skill-manifest.json | 8 +++++++- package.json | 2 +- skills/vercel-cli/SKILL.md | 7 +++++-- skills/vercel-cli/overlay.yaml | 6 ++++-- .../references/monitoring-and-debugging.md | 14 ++++++++++++++ skills/vercel-cli/upstream/SKILL.md | 2 +- .../references/monitoring-and-debugging.md | 14 ++++++++++++++ 12 files changed, 59 insertions(+), 14 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 9268daa..1709634 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "vercel", - "version": "0.42.0", + "version": "0.42.1", "description": "Build and deploy web apps and agents", "author": { "name": "Vercel", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 57ae3ba..f9b6e9d 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "vercel", - "version": "0.42.0", + "version": "0.42.1", "description": "Build and deploy web apps and agents", "author": { "name": "Vercel", diff --git a/.plugin/plugin.json b/.plugin/plugin.json index 4b18db1..d28d14f 100644 --- a/.plugin/plugin.json +++ b/.plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "vercel-plugin", - "version": "0.42.0", + "version": "0.42.1", "description": "Comprehensive Vercel ecosystem plugin — relational knowledge graph, skills for every major product, specialized agents, and Vercel conventions. Turns any AI agent into a Vercel expert.", "author": { "name": "Vercel", diff --git a/commands/status.md b/commands/status.md index 26fbf10..62cf602 100644 --- a/commands/status.md +++ b/commands/status.md @@ -173,7 +173,8 @@ If drains are unavailable (Hobby plan or not yet configured), use these alternat | Query logs programmatically | **MCP / REST API** | `get_runtime_logs` tool or `/v3/deployments/:id/events` | | Monitor errors post-deploy | **CLI** | `vercel logs --level error --since 1h` | | Web Analytics data | **Dashboard only** | `https://vercel.com/{team}/{project}/analytics` | -| Performance metrics | **Dashboard only** | `https://vercel.com/{team}/{project}/speed-insights` | +| Observability metrics | **Vercel CLI** | `vercel metrics schema`, then `vercel metrics --format=json` | +| Speed Insights dashboard | **Dashboard** | `https://vercel.com/{team}/{project}/speed-insights` | > **Upgrade path:** When ready for centralized observability, upgrade to Pro and configure drains at `https://vercel.com/dashboard/{team}/~/settings/log-drains` or via REST API. The drain setup is typically < 5 minutes. @@ -183,7 +184,8 @@ If drains are unavailable (Hobby plan or not yet configured), use these alternat |------|-----|-----| | Page views, traffic sources | Web Analytics | First-party, privacy-friendly | | Business event tracking | Web Analytics custom events | Track conversions, feature usage | -| Core Web Vitals monitoring | Speed Insights | Real user data per route | +| Core Web Vitals monitoring | Speed Insights + `vercel metrics vercel.speed_insights_metric.lcp -a p75 --group-by route --since 7d` | Real user data per route | +| Query platform metrics | `vercel metrics` / `vc metrics` | Function invocations, request counts, AI Gateway spend, Speed Insights, grouped by schema dimensions | | Function debugging | Runtime Logs (CLI `vercel logs` / Dashboard (`https://vercel.com/{team}/{project}/logs`) / REST) | Real-time, per-invocation logs | | Export logs to external platform | Drains (JSON/NDJSON/Syslog) | Centralize observability (Pro+) | | Export analytics data | Drains (Web Analytics type) | Warehouse pageviews + custom events (Pro+) | @@ -202,6 +204,7 @@ Confirm each data source returned successfully: - [ ] Domain list retrieved (or "no custom domains") - [ ] vercel.json parsed (or "not present") - [ ] Drain status checked (count, errored drains identified) +- [ ] Metrics schema checked with `vercel metrics schema --format=json` when CLI auth/team scope is available - [ ] Analytics/Speed Insights instrumentation detected (or gap flagged) - [ ] Drain signature secret checked (if drains configured) diff --git a/commands/status.md.tmpl b/commands/status.md.tmpl index 26fbf10..62cf602 100644 --- a/commands/status.md.tmpl +++ b/commands/status.md.tmpl @@ -173,7 +173,8 @@ If drains are unavailable (Hobby plan or not yet configured), use these alternat | Query logs programmatically | **MCP / REST API** | `get_runtime_logs` tool or `/v3/deployments/:id/events` | | Monitor errors post-deploy | **CLI** | `vercel logs --level error --since 1h` | | Web Analytics data | **Dashboard only** | `https://vercel.com/{team}/{project}/analytics` | -| Performance metrics | **Dashboard only** | `https://vercel.com/{team}/{project}/speed-insights` | +| Observability metrics | **Vercel CLI** | `vercel metrics schema`, then `vercel metrics --format=json` | +| Speed Insights dashboard | **Dashboard** | `https://vercel.com/{team}/{project}/speed-insights` | > **Upgrade path:** When ready for centralized observability, upgrade to Pro and configure drains at `https://vercel.com/dashboard/{team}/~/settings/log-drains` or via REST API. The drain setup is typically < 5 minutes. @@ -183,7 +184,8 @@ If drains are unavailable (Hobby plan or not yet configured), use these alternat |------|-----|-----| | Page views, traffic sources | Web Analytics | First-party, privacy-friendly | | Business event tracking | Web Analytics custom events | Track conversions, feature usage | -| Core Web Vitals monitoring | Speed Insights | Real user data per route | +| Core Web Vitals monitoring | Speed Insights + `vercel metrics vercel.speed_insights_metric.lcp -a p75 --group-by route --since 7d` | Real user data per route | +| Query platform metrics | `vercel metrics` / `vc metrics` | Function invocations, request counts, AI Gateway spend, Speed Insights, grouped by schema dimensions | | Function debugging | Runtime Logs (CLI `vercel logs` / Dashboard (`https://vercel.com/{team}/{project}/logs`) / REST) | Real-time, per-invocation logs | | Export logs to external platform | Drains (JSON/NDJSON/Syslog) | Centralize observability (Pro+) | | Export analytics data | Drains (Web Analytics type) | Warehouse pageviews + custom events (Pro+) | @@ -202,6 +204,7 @@ Confirm each data source returned successfully: - [ ] Domain list retrieved (or "no custom domains") - [ ] vercel.json parsed (or "not present") - [ ] Drain status checked (count, errored drains identified) +- [ ] Metrics schema checked with `vercel metrics schema --format=json` when CLI auth/team scope is available - [ ] Analytics/Speed Insights instrumentation detected (or gap flagged) - [ ] Drain signature secret checked (if drains configured) diff --git a/generated/skill-manifest.json b/generated/skill-manifest.json index a032ea3..3845c5b 100644 --- a/generated/skill-manifest.json +++ b/generated/skill-manifest.json @@ -773,6 +773,7 @@ "deployment status", "deploy status", "vercel logs", + "vercel metrics", "deployment logs", "deploy logs", "vercel inspect", @@ -800,6 +801,10 @@ "vercel", "logs" ], + [ + "vercel", + "metrics" + ], [ "deploy", "error" @@ -844,7 +849,8 @@ "vercel deploy", "vercel env", "vercel link", - "vercel logs" + "vercel logs", + "vercel metrics" ], "examples": [] } diff --git a/package.json b/package.json index 670345e..a68238b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "vercel-plugin", - "version": "0.42.0", + "version": "0.42.1", "private": true, "bin": { "vercel-plugin": "src/cli/index.ts" diff --git a/skills/vercel-cli/SKILL.md b/skills/vercel-cli/SKILL.md index 7d8a349..1ec0290 100644 --- a/skills/vercel-cli/SKILL.md +++ b/skills/vercel-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: vercel-cli -description: Vercel CLI expert guidance. Use when deploying, managing environment variables, linking projects, viewing logs, managing domains, or interacting with the Vercel platform from the command line. +description: Vercel CLI expert guidance. Use when deploying, managing environment variables, linking projects, viewing logs, querying metrics, managing domains, or interacting with the Vercel platform from the command line. metadata: priority: 4 docs: @@ -27,6 +27,7 @@ metadata: - "deployment status" - "deploy status" - "vercel logs" + - "vercel metrics" - "deployment logs" - "deploy logs" - "vercel inspect" @@ -41,6 +42,7 @@ metadata: - [check, deploy] - [vercel, status] - [vercel, logs] + - [vercel, metrics] - [deploy, error] - [deploy, failed] - [deploy, stuck] @@ -71,6 +73,7 @@ retrieval: - vercel env - vercel link - vercel logs + - vercel metrics chainTo: - pattern: '"functions"\s*:\s*\{|"maxDuration"\s*:|"memory"\s*:' @@ -123,7 +126,7 @@ Use this to route to the correct reference file: - **CI/CD automation** → `references/ci-automation.md` - **Domains or DNS** → `references/domains-and-dns.md` - **Projects or teams** → `references/projects-and-teams.md` -- **Logs, debugging, or accessing preview deploys** → `references/monitoring-and-debugging.md` +- **Logs, metrics, debugging, or accessing preview deploys** → `references/monitoring-and-debugging.md` - **Blob storage** → `references/storage.md` - **Integrations (databases, storage, etc.)** → `references/integrations.md` - **Access a preview deployment** → use `vercel curl` (see `references/monitoring-and-debugging.md`) diff --git a/skills/vercel-cli/overlay.yaml b/skills/vercel-cli/overlay.yaml index 17fa0a7..1b0d319 100644 --- a/skills/vercel-cli/overlay.yaml +++ b/skills/vercel-cli/overlay.yaml @@ -1,5 +1,5 @@ name: vercel-cli -description: Vercel CLI expert guidance. Use when deploying, managing environment variables, linking projects, viewing logs, managing domains, or interacting with the Vercel platform from the command line. +description: Vercel CLI expert guidance. Use when deploying, managing environment variables, linking projects, viewing logs, querying metrics, managing domains, or interacting with the Vercel platform from the command line. metadata: priority: 4 docs: @@ -26,6 +26,7 @@ metadata: - "deployment status" - "deploy status" - "vercel logs" + - "vercel metrics" - "deployment logs" - "deploy logs" - "vercel inspect" @@ -40,6 +41,7 @@ metadata: - [check, deploy] - [vercel, status] - [vercel, logs] + - [vercel, metrics] - [deploy, error] - [deploy, failed] - [deploy, stuck] @@ -70,6 +72,7 @@ retrieval: - vercel env - vercel link - vercel logs + - vercel metrics chainTo: - pattern: '"functions"\s*:\s*\{|"maxDuration"\s*:|"memory"\s*:' @@ -80,4 +83,3 @@ chainTo: pattern: '"redirects"\s*:\s*\[|"rewrites"\s*:\s*\[|"headers"\s*:\s*\[' targetSkill: routing-middleware message: 'Routing rules in vercel.json — loading Routing Middleware guidance for platform-level request interception patterns.' - diff --git a/skills/vercel-cli/references/monitoring-and-debugging.md b/skills/vercel-cli/references/monitoring-and-debugging.md index 2adf5fe..392886b 100644 --- a/skills/vercel-cli/references/monitoring-and-debugging.md +++ b/skills/vercel-cli/references/monitoring-and-debugging.md @@ -11,6 +11,20 @@ vercel logs --since 2024-01-01 # filter by time vercel logs --query "timeout" # search ``` +## Metrics + +```bash +vercel metrics schema # list available metrics +vercel metrics schema vercel.function_invocation # inspect a metric prefix +vercel metrics vercel.function_invocation.count --since 1h # query linked project +vercel metrics vercel.request.count --group-by http_status --since 6h # group by schema dimension +vercel metrics vercel.function_invocation.request_duration_ms -a avg --group-by route --since 1h +vercel metrics vercel.ai_gateway_request.cost -a sum --group-by ai_provider --since 7d +vercel metrics vercel.speed_insights_metric.lcp -a p75 --group-by route --since 7d +vercel metrics --all vercel.function_invocation.count --group-by project_id --since 24h +vercel metrics vercel.function_invocation.count -f "http_status ge 500" --group-by error_code --since 1h --format=json +``` + ## Inspecting Deployments ```bash diff --git a/skills/vercel-cli/upstream/SKILL.md b/skills/vercel-cli/upstream/SKILL.md index 91b5799..4b109d0 100644 --- a/skills/vercel-cli/upstream/SKILL.md +++ b/skills/vercel-cli/upstream/SKILL.md @@ -42,7 +42,7 @@ Use this to route to the correct reference file: - **CI/CD automation** → `references/ci-automation.md` - **Domains or DNS** → `references/domains-and-dns.md` - **Projects or teams** → `references/projects-and-teams.md` -- **Logs, debugging, or accessing preview deploys** → `references/monitoring-and-debugging.md` +- **Logs, metrics, debugging, or accessing preview deploys** → `references/monitoring-and-debugging.md` - **Blob storage** → `references/storage.md` - **Integrations (databases, storage, etc.)** → `references/integrations.md` - **Access a preview deployment** → use `vercel curl` (see `references/monitoring-and-debugging.md`) diff --git a/skills/vercel-cli/upstream/references/monitoring-and-debugging.md b/skills/vercel-cli/upstream/references/monitoring-and-debugging.md index 2adf5fe..392886b 100644 --- a/skills/vercel-cli/upstream/references/monitoring-and-debugging.md +++ b/skills/vercel-cli/upstream/references/monitoring-and-debugging.md @@ -11,6 +11,20 @@ vercel logs --since 2024-01-01 # filter by time vercel logs --query "timeout" # search ``` +## Metrics + +```bash +vercel metrics schema # list available metrics +vercel metrics schema vercel.function_invocation # inspect a metric prefix +vercel metrics vercel.function_invocation.count --since 1h # query linked project +vercel metrics vercel.request.count --group-by http_status --since 6h # group by schema dimension +vercel metrics vercel.function_invocation.request_duration_ms -a avg --group-by route --since 1h +vercel metrics vercel.ai_gateway_request.cost -a sum --group-by ai_provider --since 7d +vercel metrics vercel.speed_insights_metric.lcp -a p75 --group-by route --since 7d +vercel metrics --all vercel.function_invocation.count --group-by project_id --since 24h +vercel metrics vercel.function_invocation.count -f "http_status ge 500" --group-by error_code --since 1h --format=json +``` + ## Inspecting Deployments ```bash