planetscale-codebase-sqlcommenter-instrumentation

Codebase SQLCommenter のインストルメンテーション

目的

PlanetScale に接続されたアプリケーションリポジトリを調査し、PlanetScale Insights と Postgres Traffic Control がクエリをアプリケーションのコードパスに関連付けられるよう、適切な SQLCommenter 形式のインストルメンテーションを推奨します。承認を得ずにファイルを編集したり、依存関係をインストールしたりしないでください。

リポジトリの調査

以下を特定します。

• 言語とフレームワーク。
• ORM またはクエリビルダー。
• データベースアダプター。
• マイグレーションツール。
• バックグラウンドジョブシステム。
• ルーティングフレームワーク。
• git SHA やリリース ID など、デプロイメタデータの取得元。
• 既存の SQL コメント、クエリタグ、トレーシング、OpenTelemetry、データベースミドルウェア。
• PlanetScale の接続設定。
• リポジトリが Vitess、Postgres、またはその両方に接続するかどうか。

推奨パッケージの対応表

検出されたスタックに最も適した、ネイティブで保守されている選択肢を使用します。

Ruby on Rails / ActiveRecord

PlanetScale のタグとの互換性を優先する場合：

• Rails のクエリコメントが PlanetScale Query Insights 向けの SQLCommenter 形式である必要がある場合は、PlanetScale の activerecord-sql_commenter。

その他の選択肢：

• Rails 組み込みのクエリログ。対象のデータベースや Insights の動作に対して十分で互換性がある場合に使用します。
• 古い Rails、または Basecamp 形式の ActiveRecord クエリ帰属がすでに使用されている場合は、marginalia。
• プロジェクトですでに OpenTelemetry SQLCommenter エコシステムを使用している場合は、sqlcommenter_rails。

推奨タグ：

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

Laravel / PHP

推奨：

• PlanetScale Query Insights と互換性のある SQLCommenter 形式のコメントには、spatie/laravel-sql-commenter を使用します。

推奨タグ：

• 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 を含めます。
• エージェント、スクリプト、BI、ワーカー、インテグレーションについて、ソースの種類を含めます。
• シークレット、PII、ユーザー ID、リクエスト ID、生のテナント ID、生の URL は含めません。

検証計画

マージを推奨する前に、次の点を確認します。

• 生成された SQL コメントが、ローカル／ステージング環境のクエリログに表示されること。
• コメントが ORM、ドライバー、プーラー、PlanetScale の接続経路を通過しても保持されること。
• Insights にタグが表示されること。
• タグのカーディナリティが制限されていること。
• Postgres で、Traffic Control が意図したタグに一致すること。
• 機密データが含まれていないこと。

出力

次の内容を返します。

• 検出されたスタック。
• 現在のクエリタグ付けの状態。
• 推奨するパッケージ、または手動計装の方法。
• 提案するタグスキーマ。
• 変更が見込まれるファイル。
• 検証手順。
• リスク。
• 承認が必要な変更案。

次の文で締めくくります。

「リポジトリのファイルや依存関係は変更されていません。」