convex-insights

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

部署已经记录了发生的事情；Agent 只需要恰当地提问即可。该能力是官方 Convex MCP 只读工具（

logs

、

insights

、

functionSpec

、

status

）的一套严谨封装，将运维问题转化为范围狭窄、返回证据的查询，并返回人类可以在 dashboard 中一键验证的答案。这套方法借鉴了实际使用中最有效的可观测性 MCP 接口：查询前先发现字段、三种视图而不是十五个工具、节省 token 的输出，以及每个答案都附带 dashboard 深度链接。

Workflow

工作流程

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.
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.
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'.
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.
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.
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.
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.

GUARD：deploy-guard 步骤 0-1——确定并说明正在读取哪个 deployment。读取 logs/insights 是只读操作；执行 insights 查询时，绝不能启用 prod mutation flags。
DISCOVER：查询前先发现字段——绝不猜测标识符。使用
```
functionSpec
```
列出真实的函数名称，并使用
```
status
```
获取 deployment/version 的状态。提前说明工具限制：
```
logs
```
只接受
```
--history <n>
```
（这是 COUNT，不是时间窗口）、
```
--success
```
、
```
--jsonl
```
、
```
--prod
```
、
```
--deployment
```
——不存在服务端的 status/function/requestId/time 过滤器；
```
insights
```
没有 function 过滤器，且仅适用于 cloud dev/prod + user-auth。因此，获取最近的时间窗口，然后在客户端（CLIENT-SIDE）进行过滤。
PICK ONE OF THREE VIEWS：获取原始窗口，然后在本地过滤：
- failures 视图 →
```
logs --history <n> --jsonl
```
  ，然后在本地保留失败项，并按 function + error message 分组，返回每组的计数 + 第一个 stack。回答“什么正在报错”和“部署后什么失败了”。
- health 视图 →
```
insights
```
  （仅限 cloud）：类型化的 72h read-limit / OCC 事件。呈现并排序这些事件，但将性能/成本（perf/cost）的根因分析（ROOT-CAUSING）和修复交给 convex-advisor——将这些作为 pointer findings 输出，不要在此处承担 perf-fix 的表述框架。
- trace 视图 →
```
logs --history <n> --jsonl
```
  ，然后在本地过滤到一个 requestId/function，以读取完整执行过程。回答“为什么这次调用失败”。
SCOPE：通过获取有界的最近窗口（使用合理的
```
--history
```
数量）来限定范围，并按问题所涉及的 function/status/requestId 在客户端（CLIENT-SIDE）过滤；当窗口较大时，聚合数据（按 function/message 计数），而不是倾倒日志行。
ANSWER：包括 (a) 一句话结论，(b) 证据（计数 + 一条有代表性的 stack/log 行），以及 (c) 在可能的情况下，由 Agent 构建的 dashboard 深度链接（dashboard.convex.dev，该 deployment 的 Logs/Functions 视图），供人工验证——没有工具会返回该链接，因此根据 deployment 名称 + function 构建；绝不以原始日志转储作为答案。
CROSS-CHECK：在被问到“我的部署是否导致了这个问题”时，交叉检查部署因果关系：将失败开始时间（来自日志时间戳）与
```
status
```
中的 deployment 版本进行对比；判断相关性，不要断言因果关系。
HAND OFF：移交，不要在此处修复：性能/成本原因 → convex-advisor（由它负责这些修复）；代码缺陷 → convex-reviewer/convex-authz；今后需要持续响应的线上错误 → monitor/sentinel。通过 bus 输出 findings（specs/finding.schema.json）——主要标记为
```
observability
```
，其中性能/成本作为指向 advisor 的 pointer findings——以便 composite pass 接收这些结果。

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.

在过滤前发现真实的 function/field 名称（functionSpec/status）——绝不猜测标识符，不要因为 app 中不存在该名称而返回令人困惑的空结果。
```
logs
```
和
```
insights
```
没有服务端 status/function/requestId/time-window 过滤器（logs 只接受 --history COUNT；insights 仅限 cloud）——获取有界的最近窗口并在客户端（CLIENT-SIDE）过滤；应明确说明这一点，不要暗示不存在的参数。
每个问题只使用三个视图中的一个（failures / health / trace）——不要扩展为大量推测性的工具调用。
没有工具会返回 dashboard 链接——在可能的情况下，根据 deployment 名称 + function 构建链接，供人工验证；绝不以原始日志转储作为答案。
始终保持只读：insights 查询不执行 mutation，也绝不启用 prod mutation flags（遵循 deploy-guard 规范）。
保持只读观察者角色，将性能/成本修复交给 convex-advisor：主要输出
```
observability
```
，将性能/成本作为 POINTER findings 路由，使 advisor 唯一负责 perf-fix 的表述框架；面向未来的响应交给 monitor/sentinel。