使用 PlanetScale Insights 与…

在 PlanetScale 上检查查询行为与标签覆盖，用 SQLCommenter 兼容标签归因负载、找出风险查询，并给出需审批的 Traffic Control、schema 与代码变更建议。

适用场景

解决思路

1. 使用 PlanetScale Insights 理解查询行为，然后推荐 SQLCommenter 兼容标签，使未来诊断和 Traffic Control 可行；不要在未获批准时更改数据库设置或仓库代码。
2. 对于选定的 database 和 branch，检查按 total time 排序的 Top queries。
3. 对于选定的 database 和 branch，检查按 time per execution 排序的 Top queries。
4. 对于选定的 database 和 branch，检查按 rows read 排序的 Top queries。
5. 对于选定的 database 和 branch，检查按 execution count 排序的 Top queries。
6. 对于 Postgres，检查按 CPU usage 排序的 Top queries，可在 Insights API 上使用 `sort=cpuTime` 或 `sort=percentCpuTime`。
7. 检查 Queries with errors。
8. 检查 notable queries 和 active anomalies。
9. 检查受 recent deploys 影响的 query patterns。
10. 检查附带 schema recommendations 的 query patterns。
11. 对于 sharded Vitess databases，检查每个 query pattern 的 vindex usage：使用相关 vindexes 的流量百分比以及 vindex-usage 随时间趋势。API 暴露 per-pattern `index_usages` 和 `routing_index_usages`；从 dashboard Vindexes tab 或比较 API windows 获取趋势。将缺失或下降的相关 vindex 使用作为 indexing 或 routing 调查输入，而不是作为需要新 index 的证据。
12. 使用 Query Insights public API：只读 GET endpoints，位于 `organizations/{org}/databases/{db}/branches/{branch}` 下，通过 service token 或具有 `read_databases`/`read_database` 的 OAuth token 授权。
13. 调用 `/insights` 获取请求窗口内每个 query pattern 的聚合统计。用 `from`/`to`（ISO 8601）或 `period`（例如 `1h`、`24h`）设置窗口；用 `q` 搜索 SQL patterns；用 `sort` 和 `dir` 服务端排序——sort keys 包括 `count`、`errorCount`、`rowsRead`、`totalTime`、`cpuTime`、`ioTime`、`percentTime`、`percentCpuTime`、`p50Latency`、`p99Latency`、`maxLatency`、`egressBytes`，以及 `trafficControlWarnings`/`trafficControlThrottled` 系列。用 `tablet_type`（`primary`、`replica`、`rdonly`）和 `type`（`SELECT`、`INSERT`、`UPDATE`、`DELETE`）过滤；用 `fields` 精简响应；用 `page`/`per_page` 分页。
14. 调用 `/insights/{fingerprint}` 获取某个 pattern 的单个已收集 executions（timestamps、duration、rows、username、client address、error message）。无论是否启用 raw query collection，都可用；raw collection 会在这些记录中增加 literal parameter values。`/insights/{fingerprint}/summary` 返回单 pattern 聚合；`/insights/queries/{id}` 获取一次 execution。
15. 调用 `/insights/errors` 获取 error fingerprints 及其 counts 和 messages（用 `q` 搜索 error message；按 `count`、`lastRun`、`totalTime` 或 `timePerQuery` 排序）。`/insights/errors/{fingerprint}` 列出某个 error fingerprint 后面的 failing executions。
16. 调用 `/insights/anomalies` 和 `/insights/anomalies/{id}` 获取 anomaly windows，并用 per-query correlation coefficients 识别哪些 patterns 随 anomaly 变化。
17. 调用 `/insights/tags` 获取 tag keys 及其 observed values（支持 `values_limit`、`literal_values_only` 以及 `fingerprint`/`keyspace` filters）；`/insights/tags/{tag}` 获取单个 key。`/insights/tags/summaries` 通过 `tags` 参数按一个或多个 tag keys 对完整 statistics schema 分组——用它把负载归因到 routes、jobs 或 features，无需客户端聚合。
18. 调用 `/insights/{fingerprint}/traffic/budgets` 获取影响某个 fingerprint 的 Traffic Control budgets 和 rules（Postgres）。
19. 记住 aggregates 覆盖请求窗口；duration 字段使用如 `sum_total_duration_millis` 的名称，并有显式 share-of-window 百分比字段（`sum_total_duration_percent`）；totals 和 percentages 对请求窗口均可靠。
20. 注意 response schema 跨引擎共享，但部分字段因引擎而异：CPU/IO durations 和 block-cache statistics（`sum_cpu_duration_millis`、`blocks_read`、`block_cache_hit_ratio` 等）在 Postgres 填充；shard queries、keyspaces、`tablet_type` 和 routing-index（vindex）usage 在 Vitess 填充。
21. 对每个 expensive 或 anomalous query，确定：是否已打 tag？哪个 service 产生？哪个 route、job、controller 或 action 产生？哪个 deployment SHA 产生？tag cardinality 是否安全？tags 是否跨 frameworks 和 languages 一致？
22. 使用 tags API 回答上述问题：`/insights/tags` 显示存在哪些 keys 和 values；`/insights/tags/summaries?tags=...` 按 tag value 归因负载。在 Vitess dashboard 中，用 `tag:key:value` 过滤 query table，并下钻到 query details 查看单个 executions 上的 tags。Built-in query metadata 和 SQLCommenter tags 都是有效归因来源。
23. 检查 raw query / complete query collection 是否启用。Postgres 上有效状态是 `pginsights.raw_queries` cluster parameter（per branch，dashboard Extensions tab，默认 `false`）；database API object 的 `insights_raw_queries` 字段是另一个 surface。当两者不同时，报告 cluster parameter 为有效状态，不要将差异描述为 inconsistency。Vitess 上没有 cluster parameter；database API 的 `insights_raw_queries` 字段是有效状态。
24. 将 raw query collection 报告为 capability state，而不是 risk posture。Raw query collection 记录每个 execution 的 literal parameter values，这是 pattern-level Insights data 不提供的；它是定位某个 pattern 的哪个具体 invocation 异常的方法。Execution-level records 无论是否 raw collection 都可通过 `/insights/{fingerprint}` 获取；raw collection 会给这些记录增加 literal parameter values。
25. 当 raw query collection 被禁用时，将发现视为 capability gap：找出本次评估中 pattern-level data 不足的 query patterns（同一 fingerprint 内无法解释的 latency variance、tenant- 或 parameter-dependent behavior），并说明 raw collection 可以解决它们。只陈述一次操作属性为事实：literal values 会变得对 observability pipeline 可见。若客户数据处理要求限制这一点，scoped enablement（incident windows、defined retention）和保持 collection 禁用都是有效结果——记录 rationale，而不是在任一方向默认判断。
26. 将 tags 和 raw collection 视为互补工具：tags 把 pattern 归因到 code path；raw collection 识别具体 invocation。评估应同时评估两者。
27. 推荐以下 SQLCommenter baseline tag set：`application`：稳定 app name；`service`：service 或 process name；`environment`：production、staging、development；`route`：normalized route template，例如 `/accounts/:id/orders`，而不是 `/accounts/123/orders`；`controller`：适用时 framework controller name；`action`：适用时 framework action name；`job`：background job class 或 worker name；`queue`：background queue；`feature`：用于 export、report、search、billing、checkout 等 traffic classes 的 bounded feature name；`release_sha`：short git SHA 或 deploy identifier；`source`：app、worker、script、agent、mcp、bi、integration；`tenant_tier`：free、pro、enterprise、internal，仅当 bounded。
28. 默认不要推荐这些 tags：`user_id`、`request_id`、`tenant_id`、`email`、`session_id`、raw URL、unbounded GraphQL operation text、access token、secret。
29. 如果客户需要 tenant-level isolation，先推荐 bounded abstraction，例如 tenant tier、cell、shard 或 customer class。Tenant ID 只有在 cardinality 和 privacy review 后明确批准才可接受。
30. 当 tag 满足以下条件时，将其标记为 unsafe：values 无界；values 包含 IDs、UUIDs、emails、slugs 或 raw paths；同一 query pattern 发出许多 unique tag combinations；该 tag 会使 Insights 或 Traffic Control aggregation 变得嘈杂。
31. 推荐在 application boundary 进行规范化。
32. 对每个 top query pattern，产出：Fingerprint 或 normalized query；Current metrics；Current tags；Missing tags；Likely source in application code；是否为 schema recommendation candidate；是否为 Traffic Control candidate；是否为 application optimization candidate。
33. 推荐类别 Add tags：当 query attribution 较弱时，推荐 SQLCommenter instrumentation。
34. 推荐类别 Improve tag normalization：推荐用 bounded values 替换 high-cardinality tags。
35. 推荐类别 Add Traffic Control warning budget：仅 Postgres，针对 expensive but important routes、jobs、analytics、exports 或 third-party integrations，推荐 `warn` mode budgets。
36. 推荐类别 Add schema recommendation workflow：Vitess 推荐把 open schema recommendations 转为 branch/deploy-request 工作；Postgres 推荐把它们转为针对 non-production branch 的 reviewed migrations。
37. 推荐类别 Fix code path：当 expensive query 由 N+1、missing pagination、accidental eager load、unbounded export、broad search 或 polling 引起时，推荐 repository PR。
38. Safety rules：没有明确批准，不要启用 raw query collection。
39. Safety rules：没有明确批准，不要向代码添加 tags。
40. Safety rules：没有明确批准，不要更改 Traffic Control budgets。
41. Safety rules：没有明确批准，不要应用 schema recommendations。
42. Safety rules：没有明确批准，不要在 expensive queries 上运行 production EXPLAIN ANALYZE。
43. Output 返回：Query risk table；Tag coverage table；Bad/high-cardinality tag table；Recommended tag schema for this application；Candidate Traffic Control slices；Candidate schema and code changes；Proposed changes requiring approval。
44. 最后以：“No Insights, tag, repository, or Traffic Control changes have been applied.” 结束。

适用边界 · 注意事项

• 不适用于不使用 PlanetScale 或其 Insights/Traffic Control 的数据库环境。
• 不适用于没有 Insights 只读 API 授权（service token 或 OAuth token 且具备 `read_databases`/`read_database`）的场景。
• 不适用于需要默认采集 raw query literal values，或使用 `user_id`、`request_id`、`tenant_id` 等高基数/敏感标签且未完成 cardinality 与 privacy review 的场景。