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.