---
id: gh-convex-insights
name: "convex-insights"
url: https://skills.yangsir.net/skill/gh-convex-insights
author: convex
domain: ai-system-observability-sre
tags: ["observability", "logs", "troubleshooting", "sre", "convex"]
install_count: 34900
rating: 4.60 (120 reviews)
github: https://github.com/convex/agent-skills/tree/main/skills/convex-insights
---

# convex-insights

> 该 Skill 用自然语言查询运行中 Convex 应用的日志与健康状态，覆盖报错排查、慢/贵函数定位、部署因果分析三类视图，输出带证据的结论并附仪表盘深链。它让开发者不必手写过滤命令或翻原始日志，几轮对话即可定位线上故障并一键核验。

**Stats**: 34,900 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 线上故障定位耗时

**Before**:

线上报错后，开发者需要回忆 CLI 参数、手动拉取日志、在编辑器里逐行 grep 过滤，往往还要猜函数名，一小时过去仍不确定哪个函数在炸。

**After**:

此技能先用 functionSpec/status 确认真实函数名与版本，再抓取有界窗口做客户端过滤，直接给出错误计数、首条堆栈和仪表盘深链，故障定位几分钟内完成。

| Metric | Before | After | Change |
|---|---|---|---|
| 故障定位耗时 | 60分钟 | 8分钟 | -87% |

### 诊断结论可核验程度

**Before**:

口头结论缺少证据，随手贴一大段原始日志，团队无法判断结论从哪来，部署是否导致故障只能靠猜，反复争论消耗沟通成本。

**After**:

该 Skill 每次回答都附带计数证据、一条代表性堆栈，以及 agent 依据部署名与函数构造的仪表盘深链，并把部署版本与错误起始时间做相关性对照，结论可一键复核。

| Metric | Before | After | Change |
|---|---|---|---|
| 结论可核验率 | 35% | 92% | +57% |

### 无效工具调用次数

**Before**:

不清楚日志接口不支持服务端过滤，反复尝试按状态码、函数名、时间窗查询，得到空结果后继续盲目重试，浪费大量往返。

**After**:

此技能明确 logs 仅接受 --history 计数、insights 仅限云端，先抓取有界近期窗口再本地过滤，并按问题只选失败/健康/追踪三种视图之一，调用次数显著收敛。

| Metric | Before | After | Change |
|---|---|---|---|
| 平均工具调用次数 | 14次 | 4次 | -71% |

## Readme

<!-- GENERATED from convex-agents content/capabilities/convex-insights.json — do not edit by hand. -->

# Query logs + health in natural language

The deployment already records what happened; the agent just has to ask well. This capability is a disciplined wrapper over the official Convex MCP's read tools (`logs`, `insights`, `functionSpec`, `status`) that turns operational questions into narrow, evidence-returning queries and hands back answers a human can one-click verify in the dashboard. The discipline is copied from the observability MCP surface that works best in the wild: discover fields before querying, three views not fifteen tools, token-frugal output, and a dashboard deep link on every answer.

## Workflow

1. GUARD: deploy-guard step 0-1 — identify + announce which deployment is being read. Reading logs/insights is read-only; never enable prod mutation flags for an insights pass.
2. DISCOVER before you query — never guess identifiers. Use `functionSpec` to list the real function names and `status` for the deployment/version. Note the tool limits up front: `logs` takes only `--history <n>` (a COUNT, not a time window), `--success`, `--jsonl`, `--prod`, `--deployment` — there is NO server-side status/function/requestId/time filter; `insights` has no function filter and is cloud dev/prod + user-auth only. So you fetch a recent window and filter CLIENT-SIDE.
3. PICK ONE OF THREE VIEWS and fetch the raw window, then filter locally:
   - failures view → `logs --history <n> --jsonl`, then locally keep failures + group by function + error message, returning counts + the first stack per group. Answers 'what's erroring', 'what failed after deploy'.
   - health view → `insights` (cloud only): the typed 72h read-limit / OCC events. Surface + rank them, but hand perf/cost ROOT-CAUSING and fixes to convex-advisor — emit those as pointer findings, do not own the perf-fix framing here.
   - trace view → `logs --history <n> --jsonl` then locally filter to one requestId/function to read the full execution. Answers 'why did THIS call fail'.
4. SCOPE by fetching a bounded recent window (a sensible `--history` count) and filtering client-side to the function/status/requestId asked about; when the window is large, aggregate (counts by function/message) rather than dumping lines.
5. ANSWER with (a) the one-line finding, (b) the evidence (counts + one representative stack/log line), and (c) WHEN POSSIBLE an agent-constructed dashboard deep link (dashboard.convex.dev, the deployment's Logs/Functions view) for human verification — no tool returns the link, so build it from the deployment name + function; never a raw log dump as the answer.
6. CROSS-CHECK deploy causality when asked 'did my deploy break this': compare the failure onset (from the log timestamps) against the deployment version from `status`; correlate, don't assert.
7. HAND OFF, don't fix here: a perf/cost cause → convex-advisor (which owns those fixes); a code defect → convex-reviewer/convex-authz; a live error to react to going forward → monitor/sentinel. Emit findings on the bus (specs/finding.schema.json) — primarily `observability`, with perf/cost as pointer findings to advisor — so a composite pass can pick them up.

## Rules

- Discover real function/field names (functionSpec/status) before filtering — never guess identifiers, never return a confusing empty result for a name the app doesn't have.
- `logs` and `insights` have NO server-side status/function/requestId/time-window filter (logs takes only a --history COUNT; insights is cloud-only) — fetch a bounded recent window and filter CLIENT-SIDE; say so rather than implying params that don't exist.
- One of three views per question (failures / health / trace) — don't fan out into many speculative tool calls.
- No tool returns a dashboard link — construct it from the deployment name + function when possible for human verification; never answer with a raw log dump.
- Read-only always: an insights pass runs no mutation and never enables prod mutation flags (deploy-guard discipline).
- Stay a reader and defer perf/cost fixes to convex-advisor: emit primarily `observability`, route perf/cost as POINTER findings so advisor uniquely owns the perf-fix framing; forward-looking reaction goes to monitor/sentinel.


---
*Source: https://skills.yangsir.net/skill/gh-convex-insights*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-convex-insights/markdown*