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

）的规范化封装，可将运维问题转化为精准、返回证据的查询，并给出人类可一键在仪表板验证的答案。这种规范借鉴了在实际场景中表现最佳的可观测性MCP界面：查询前先发现字段、提供三种视图而非十五种工具、输出节省token、每个答案都附带仪表板深度链接。

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.

防护步骤：deploy-guard步骤0-1 —— 识别并声明正在读取的部署。读取日志/洞察是只读操作；在洞察查询阶段绝不要启用生产环境变更标志。
查询前先发现——绝不猜测标识符。使用
```
functionSpec
```
列出真实函数名称，使用
```
status
```
获取部署/版本信息。提前注意工具限制：
```
logs
```
仅支持
```
--history <n>
```
（数量，而非时间窗口）、
```
--success
```
、
```
--jsonl
```
、
```
--prod
```
、
```
--deployment
```
参数；没有服务端状态/函数/requestId/时间过滤器；
```
insights
```
没有函数过滤器，且仅支持云端开发/生产环境及用户授权。因此需获取最近的窗口数据并在客户端过滤。
选择三种视图之一，获取原始窗口数据后在本地过滤：
- 故障视图 →
```
logs --history <n> --jsonl
```
  ，然后在本地保留故障数据并按函数+错误消息分组，返回计数+每组的首个堆栈信息。可回答“哪些功能报错”、“部署后哪些功能失败”。
- 健康视图 →
```
insights
```
  （仅云端）：带类型的72小时读取限制/OCC事件。展示并排序这些事件，但将性能/成本根因分析和修复工作交给convex-advisor——仅输出指向性发现，不负责性能修复的框架构建。
- 追踪视图 →
```
logs --history <n> --jsonl
```
  ，然后在本地过滤到单个requestId/函数以读取完整执行记录。可回答“此次调用为何失败”。
范围限定：获取有限的近期窗口数据（合理的
```
--history
```
数量），并在客户端过滤到查询涉及的函数/状态/requestId；当窗口数据量大时，按函数/消息聚合（计数）而非输出全部日志行。
回答包含：(a) 一行核心结论，(b) 证据（计数+一条代表性堆栈/日志行），(c) 尽可能附带Agent构建的仪表板深度链接（dashboard.convex.dev，部署的日志/函数视图）供人类验证——没有工具会返回该链接，需从部署名称+函数构建；绝不要将原始日志转储作为答案。
交叉验证部署因果关系：当被问及“我的部署是否导致此问题”时，对比日志时间戳中的故障起始时间与
```
status
```
中的部署版本；进行关联分析，而非直接断言。
转交任务而非在此修复：性能/成本问题 → 交给convex-advisor（负责此类修复）；代码缺陷 → 交给convex-reviewer/convex-authz；需实时响应的持续错误 → 交给monitor/sentinel。在总线（specs/finding.schema.json）上输出发现——主要为
```
observability
```
类型，性能/成本问题作为指向性发现转交advisor——以便复合流程能接收这些信息。

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.

过滤前先发现真实的函数/字段名称（通过functionSpec/status）——绝不猜测标识符，绝不为应用不存在的名称返回易混淆的空结果。
```
logs
```
和
```
insights
```
没有服务端状态/函数/requestId/时间窗口过滤器（logs仅支持--history数量参数；insights仅支持云端）——获取有限的近期窗口数据并在客户端过滤；需明确说明这一点，而非暗示存在不存在的参数。
每个问题仅使用三种视图之一（故障/健康/追踪）——不要进行大量推测性工具调用。
没有工具会返回仪表板链接——尽可能从部署名称+函数构建链接供人类验证；绝不要用原始日志转储作为答案。
始终保持只读：洞察查询阶段不执行任何变更操作，绝不要启用生产环境变更标志（遵循deploy-guard规范）。
仅作为读取者，将性能/成本修复工作交给convex-advisor：主要输出
```
observability
```
类型发现，将性能/成本问题作为指向性发现转交advisor，由其专门负责性能修复的框架构建；前瞻性响应任务交给monitor/sentinel。