planetscale-codebase-sqlcommenter-instrumentation

代码库 SQLCommenter 插桩

目的

检查连接到 PlanetScale 的应用仓库，并推荐合适的 SQLCommenter 风格插桩方案，以便 PlanetScale Insights 和 Postgres Traffic Control 能够将查询归因到应用代码路径。未经批准，不要编辑文件或安装依赖项。

仓库检查

识别以下内容：

• 语言和框架。
• ORM 或查询构建器。
• 数据库适配器。
• 迁移工具。
• 后台作业系统。
• 路由框架。
• 部署元数据来源，例如 git SHA 或发布 ID。
• 现有的 SQL 注释、查询标签、跟踪、OpenTelemetry 或数据库中间件。
• PlanetScale 连接配置。
• 仓库连接的是 Vitess、Postgres，还是两者都有。

建议的包映射

针对检测到的技术栈，选择最原生且维护良好的方案。

Ruby on Rails / ActiveRecord

为兼容 PlanetScale 标签，首选：

• 当 Rails 查询注释需要采用 SQLCommenter 格式以供 PlanetScale Query Insights 使用时，选择 PlanetScale 提供的 activerecord-sql_commenter。

其他选项：

• 在 Rails 内置查询日志足够用且与目标数据库或 Insights 的行为兼容时，使用该功能。
• 对于较旧版本的 Rails，或已在使用 Basecamp 风格的 ActiveRecord 查询归因时，使用 marginalia。
• 当项目已使用 OpenTelemetry SQLCommenter 生态系统时，使用 sqlcommenter_rails。

建议的标签：

• application
• controller
• action
• job
• route
• release_sha

Laravel / PHP

首选：

• 使用 spatie/laravel-sql-commenter 添加与 PlanetScale Query Insights 兼容的 SQLCommenter 格式注释。

建议的标签：

• application
• route
• controller
• action
• job
• queue
• release_sha

Prisma / TypeScript / JavaScript

首选：

• 检测到 Prisma 时，使用 Prisma 官方提供的 SQL 注释包：
  • @prisma/sqlcommenter
  • @prisma/sqlcommenter-query-tags
  • @prisma/sqlcommenter-trace-context

注意：PlanetScale 的 Postgres 查询标签文档可能会将 Prisma 列为不支持官方 SQLCommenter，但 Prisma 当前的官方文档提供了官方 SQLCommenter 包。检测到 Prisma 时，应优先参考 Prisma 当前的文档。

建议的标签：

• application
• service
• route
• operation
• feature
• release_sha

Knex / Sequelize / Express / Node

使用 OpenTelemetry SQLCommenter 生态系统中维护良好且兼容的 SQLCommenter 中间件或插桩方案。

建议的标签：

• application
• service
• route
• controller
• action
• feature
• release_sha

Kysely / Drizzle / Bun / 自定义查询构建器

如果没有维护良好的 SQLCommenter 包，则建议在数据库客户端边界或查询构建器扩展层手动添加标签。

要求：

• 标签必须是结构化 SQL 注释。
• 标签必须插入到语句终止符之前。
• 标签必须能够经受 ORM、代理和连接池的处理。
• 值必须经过 URL 编码，并且适用于 SQL 注释。
• 标签必须保持低基数。

Django / SQLAlchemy / psycopg2 / Flask / Python

使用 OpenTelemetry SQLCommenter 生态系统中的 SQLCommenter 插桩方案，并确保其兼容。

建议的标签：

• application
• framework
• route
• view
• job
• release_sha

Java / Hibernate / Spring

使用兼容 Hibernate/Spring 的 SQLCommenter 插桩方案。

建议的标签：

• application
• service
• controller
• action
• route
• release_sha

Go / database/sql / net/http / gorilla/mux

使用兼容 SQLCommenter 的插桩方案，或在查询边界使用数据库封装器。

建议的标签：

• application
• service
• handler
• route
• job
• release_sha

标准标签策略

建议所有框架采用以下基准：

• 仅使用稳定且范围有限的值。
• 标记前先规范化路由。
• 包含应用/服务/作业归属信息。
• 包含部署 SHA。
• 为 Agent、脚本、BI、工作进程和集成指定来源类型。
• 不包含机密、PII、用户 ID、请求 ID、原始租户 ID 或原始 URL。

验证计划

建议合并前：

• 确认生成的 SQL 注释出现在本地/暂存环境的查询日志中。
• 确认注释在经过 ORM、驱动程序、连接池代理和 PlanetScale 连接路径后仍然保留。
• 确认 Insights 显示标签。
• 确认标签基数有界。
• 确认 Traffic Control 可以为 Postgres 匹配预期标签。
• 确认不存在敏感数据。

输出

返回：

• 检测到的技术栈。
• 当前的查询标记状态。
• 建议使用的程序包或手动插桩路径。
• 拟定的标签架构。
• 可能需要更改的文件。
• 验证步骤。
• 风险。
• 需要审批的拟议更改。

结尾注明：

“未更改任何仓库文件或依赖项。”