convex-insights

Query Convex deployment logs and health insights through the official MCP read tools.

9.4k|1.5k|Updated Jan 3, 2026
One-click install
npx skills add https://github.com/openclaw/clawhub --skill convex-insights
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: convex-insights
Source: https://github.com/openclaw/clawhub/tree/main/.agents/skills/convex-insights
Command: npx skills add https://github.com/openclaw/clawhub --skill convex-insights

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Investigating failures, slow functions, and deploy regressions in a running Convex app requires knowing the right log filters and identifiers, and raw log dumps are hard to act on. This Skill turns natural-language operational questions into scoped, evidence-backed queries against the official Convex MCP read tools.

Core Features & Use Cases

  • Three Focused Views: Choose between a failures view (errors grouped by function and message), a health view (72h read-limit and OCC events from insights), and a trace view (full execution of a single requestId or function).
  • Discovery-First Querying: Uses functionSpec and status to resolve real function names and deployment versions before querying, avoiding empty results from guessed identifiers.
  • Deploy Causality Checks: Correlates failure onset timestamps against deployment versions to answer whether a deploy broke something.
  • Use Case: After a production deploy, ask what started failing; the Skill fetches a bounded log window, groups errors by function, and returns counts, a representative stack trace, and a dashboard deep link for verification.

Quick Start

Ask the agent to check what functions are failing in my Convex deployment since the last deploy and show the evidence with a dashboard link.

Frequently Asked Questions about convex-insights

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check what is failing in my Convex deployment?▼

Use the failures view: fetch a bounded recent window with logs --history <n> --jsonl, then filter client-side to group failures by function and error message. The result includes counts, a representative stack trace, and a dashboard deep link.

How to trace a single failed request in Convex logs?▼

Use the trace view: fetch a recent log window with logs --history <n> --jsonl, then filter client-side to one requestId or function name to read the full execution. There is no server-side requestId filter, so filtering happens locally.

Can I filter Convex logs by function or time range server-side?▼

No. The logs tool accepts only --history (a count, not a time window), --success, --jsonl, --prod, and --deployment, and insights has no function filter. You fetch a bounded recent window and filter client-side by function, status, or requestId.

Does Convex insights work on local or self-hosted deployments?▼

No. The insights tool is cloud-only and requires user authentication, covering dev and prod cloud deployments. It surfaces typed 72-hour read-limit and OCC conflict events, which this Skill ranks and reports.

How do I know if my Convex deploy caused new errors?▼

Compare the failure onset timestamps from the logs against the deployment version reported by the status tool. The Skill correlates these signals to answer deploy-causality questions without asserting causation beyond the evidence.

When should I use convex-advisor instead of log querying?▼

Use convex-advisor when the question is about root-causing and fixing performance or cost problems. This Skill stays read-only for observability and hands off perf and cost findings to convex-advisor as pointer findings.