planetscale-query-insights-and-tags

查询洞察与标签

目的

使用 PlanetScale Insights 了解查询行为，然后推荐兼容 SQLCommenter 的标签，以便后续诊断并启用 Traffic Control。未经批准，不要更改数据库设置或代码仓库中的代码。

检查内容

查询行为

针对所选数据库和分支，检查：

• 按总耗时排名靠前的查询。
• 按每次执行耗时排名靠前的查询。
• 按读取行数排名靠前的查询。
• 按执行次数排名靠前的查询。
• 对于 Postgres，按 CPU 使用率排名靠前的查询（Insights API 中使用 sort=cpuTime 或 sort=percentCpuTime）。
• 出错的查询。
• 值得关注的查询和活跃异常。
• 近期部署影响的查询模式。
• 关联了架构建议的查询模式。
• 对于分片 Vitess 数据库，检查每种查询模式的 vindex 使用情况：使用相关 vindex 的流量百分比，以及 vindex 使用率随时间的趋势。API 会公开每种模式的 index_usages 和 routing_index_usages；可从仪表板的 Vindexes 标签页获取趋势，也可通过比较 API 时间窗口得出。将相关 vindex 使用率缺失或下降视为索引或路由调查的线索，而非需要新建索引的证据。

Insights API 接口

Query Insights 是公开 API：位于 organizations/{org}/databases/{db}/branches/{branch} 下的只读 GET 端点，使用具有 read_databases/read_database 权限的服务令牌或 OAuth 令牌授权。

• /insights — 返回所请求时间窗口内每种查询模式的聚合统计信息。使用 from/to（ISO 8601）或 period（例如 1h、24h）设置时间窗口；使用 q 搜索 SQL 模式；使用 sort 和 dir 在服务器端排序 — 排序键包括 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 分页。
• /insights/{fingerprint} — 返回某种模式收集到的单次执行记录（时间戳、持续时间、行数、用户名、客户端地址、错误消息）。无论是否收集原始查询，此接口均可用；收集原始查询后，这些记录还会包含参数的字面值。 /insights/{fingerprint}/summary 返回单种模式的聚合数据； /insights/queries/{id} 获取一次执行记录。
• /insights/errors — 返回错误指纹及其计数和消息（q 搜索错误消息；按 count、lastRun、totalTime 或 timePerQuery 排序）。/insights/errors/{fingerprint} 列出某个错误指纹对应的失败执行记录。
• /insights/anomalies 和 /insights/anomalies/{id} — 返回异常时间窗口及每个查询的相关系数，用于识别哪些模式随异常发生变化。
• /insights/tags — 返回标签键及观测到的值（支持 values_limit、 literal_values_only 和 fingerprint/keyspace 筛选条件）； /insights/tags/{tag} 用于查询单个键。/insights/tags/summaries 通过 tags 参数按一个或多个标签键汇总完整统计信息架构 — 可用它将负载归因到路由、作业或功能，而无需在客户端聚合。
• /insights/{fingerprint}/traffic/budgets — 返回影响某个指纹的 Traffic Control 预算和规则（Postgres）。

聚合数据覆盖所请求的时间窗口。持续时间字段使用 sum_total_duration_millis 等名称，并提供明确表示占窗口比例的百分比字段（sum_total_duration_percent）；对于所请求的时间窗口，总量和百分比都可靠。

各数据库引擎共用同一响应架构，但某些字段因引擎而异：CPU/IO 持续时间和块缓存统计信息（sum_cpu_duration_millis、blocks_read、block_cache_hit_ratio、……）适用于 Postgres；分片查询、keyspace、tablet_type 和路由索引（vindex）使用情况适用于 Vitess。

标签覆盖范围

对于每个开销较高或异常的查询，请确定：

• 是否带有标签？
• 是由哪个服务生成的？
• 是由哪个路由、作业、控制器或操作生成的？
• 是由哪个部署 SHA 生成的？
• 标签基数是否安全？
• 不同框架和语言中的标签是否一致？
• 使用标签 API 回答这些问题：/insights/tags 显示存在的键和值，/insights/tags/summaries?tags=... 按标签值列出负载属性。在 Vitess 仪表板中，使用 tag:key:value 筛选查询表，并深入查看查询详情，以查看单次执行上的标签。内置查询元数据和 SQLCommenter 标签都可作为有效的归因来源。

原始查询采集

检查是否启用了原始查询／完整查询采集。在 Postgres 上，有效状态由 pginsights.raw_queries 集群参数决定（按分支设置，位于仪表板的 Extensions 选项卡中，默认值为 false）；数据库 API 对象的 insights_raw_queries 字段则是另一个独立入口。如果两者不同，应报告集群参数所表示的有效状态，不要将差异描述为不一致。在 Vitess 上没有集群参数；数据库 API 的 insights_raw_queries 字段表示有效状态。

应将其报告为能力状态，而非风险态势。原始查询采集会记录每次执行的字面参数值，而模式级 Insights 数据不提供这些信息。它是定位某个模式的具体哪次调用出现异常的手段。无论是否启用原始采集，都可以通过 /insights/{fingerprint} 获取执行级记录；原始采集会将字面参数值添加到这些记录中。

禁用该功能时，发现应表述为能力缺口：指出本次评估中哪些查询模式仅凭模式级数据无法充分分析（同一指纹内未能解释的延迟差异、依赖租户或参数的行为），并说明原始采集可以解决这些问题。只需陈述一次这一操作属性，并将其作为事实：字面值会变为可观测性管道可见的数据。如果客户的数据处理要求对此有所限制，则可选择在限定范围内启用（例如，在事件处理时段内启用、设置明确的保留期限），也可选择继续禁用采集；两种做法都合理——记录选择依据，而不要默认偏向任何一方。

标签和原始采集是互补的手段：标签将模式归因到代码路径；原始采集则识别具体调用。评估应同时考察两者。

SQLCommenter 标签架构

建议采用以下基准标签集：

• application：稳定的应用名称。
• service：服务或进程名称。
• environment：生产、预发布、开发。
• route：规范化的路由模板，例如 /accounts/:id/orders，而非 /accounts/123/orders。
• controller：适用时使用框架控制器名称。
• action：适用时使用框架操作名称。
• job：后台作业类或工作进程名称。
• queue：后台队列。
• feature：用于导出、报告、搜索、计费、结账等流量类别的有限特征名称。
• release_sha：短 git SHA 或部署标识符。
• source：app、worker、script、agent、mcp、bi、integration。
• tenant_tier：仅在取值范围有限时使用 free、pro、enterprise、internal。

默认情况下，请勿建议使用以下标签：

• user_id
• request_id
• tenant_id
• email
• session_id
• 原始 URL
• 不受限的 GraphQL 操作文本
• 访问令牌
• 密钥

如果客户需要按租户隔离，应先建议有限范围的抽象，例如租户等级、单元、分片或客户类别。只有在明确批准并完成基数与隐私审查后，才可使用 Tenant ID。

基数规则

出现以下情况时，将标签标记为不安全：

• 取值范围不受限制。
• 值中包含 ID、UUID、电子邮件地址、slug 或原始路径。
• 同一查询模式会生成大量唯一的标签组合。
• 该标签会导致 Insights 或 Traffic Control 聚合结果嘈杂。

建议在应用边界进行规范化。

分析输出

针对每种主要查询模式，提供：

• 指纹或规范化查询。
• 当前指标。
• 当前标签。
• 缺失的标签。
• 应用程序代码中可能的来源。
• 是否适合作为架构建议候选项。
• 是否适合作为 Traffic Control 候选项。
• 是否适合作为应用优化候选项。

建议类别

添加标签

当查询归因能力较弱时，建议使用 SQLCommenter 插桩。

改进标签规范化

建议将高基数标签替换为取值范围受限的值。

添加 Traffic Control 警告预算

仅针对 Postgres，建议为成本高但重要的路由、作业、分析、导出或第三方集成设置 warn 模式预算。

添加架构建议工作流

对于 Vitess，建议将未处理的架构建议转化为分支／部署请求工作。对于 Postgres，建议将这些建议转化为针对非生产分支、经过审核的迁移。

修复代码路径

如果昂贵查询由 N+1 查询、缺少分页、意外的预加载、无界导出、宽泛搜索或轮询导致，建议提交仓库 PR。

安全规则

未经明确批准，不要：

• 启用原始查询收集。
• 在代码中添加标签。
• 更改 Traffic Control 预算。
• 应用架构建议。
• 对昂贵查询运行生产环境的 EXPLAIN ANALYZE。

输出

返回：

• 查询风险表。
• 标签覆盖率表。
• 不良／高基数标签表。
• 此应用的建议标签架构。
• 候选 Traffic Control 切片。
• 候选架构和代码变更。
• 需要批准的拟议变更。

结尾注明：

“未应用任何 Insights、标签、仓库或 Traffic Control 变更。”