Sqlcommenter を使用したクエリのタグ付けを有効にしてデータベースのパフォーマンスに対するアプリケーションの影響を把握する

※この投稿は米国時間 2021 年 9 月 10 日に、Google Cloud blog に投稿されたものの抄訳です。

今年の前半にリリースされた Cloud SQL Insights により、デベロッパーは PostgreSQL for Cloud SQL データベースに対するクエリ パフォーマンスの問題の検出、診断、防止を簡単に行えるようになりました。すぐに使える Query Insights ダッシュボードでは、データベース負荷のグラフ、詳細なクエリ パフォーマンス、組み込みのクエリプランを確認できます。ユーザーは Sqlcommenter と呼ばれるオープンソース ライブラリを使用したクエリのタグ付けを有効にすることで、Insights の機能をさらに活用できます。この投稿では、クエリのタグ付けを使用するメリット、Sqlcommenter の概要、Sqlcommenter を有効にする 2 つの方法（サポートされている ORM を使用する、Sqlcommenter の仕様に沿って手動で行う）をご紹介します。

アプリケーション中心のデータベース モニタリング

Insights の特に優れた特長の一つは、アプリケーション中心のデータベース モニタリングを可能にし、アプリケーションのトラブルシューティングを簡素化できることです。この追加機能を利用するには、クエリのタグ付けを有効にして設定する必要があります。クエリのタグ付けにより、SQL ステートメントをアプリケーションに関する情報で補完できます。ビジネス ロジック、マイクロサービス、ルート、コントローラなどでタグ付けでき、たとえば、支払いタグ、在庫タグ、ビジネス分析タグ、配送タグなどを使用できます。このようにすることで、各種サービスにより作成されるクエリとデータベース負荷を特定できます。これにより、1 日の特定の時間帯でのビジネス分析タグの急増など、予期しないイベントが発生した場合や、前週に決済サービス トレンドの異常な増加があった場合に、それを確認できるようになります。ここまでで、優れた機能であることはおわかりいただけたかと思いますので、次は仕組みについてご説明します。

Sqlcommenter の概要

Insights では、Sqlcommenter と呼ばれるオープンソース ライブラリが使用されます。これにより、MVC フレームワークに関連するアプリケーション情報を SQL コメントとしてクエリとともにデータベースに送信できるようになります。Sqlcommenter は最近、OpenTelemetry と統合されました。これにより、OpenTelemetry のビジョンがデータベースまで拡張され、オブザーバビリティ エコシステムの拡大につながっています。アプリケーション情報のほか、Sqlcommenter を使用すると、アプリケーション トレースとデータベースのクエリプランに相関性を持たせて、OpenTelemetry のトレース コンテキスト情報をデータベースにプロパゲートできます。デベロッパーはこのオブザーバビリティ情報をデータベース ログで直接確認でき、情報を Cloud SQL Insights や APM ツール（Datadog、Dynatrace、Splunk などから提供）といった他のツールに統合できます。

Sqlcommenter では、Django、SQLAlchemy Ruby on Rails、Knex.js、Sequelize.js、Spring、Hibernate などのさまざまな ORM とフレームワークがサポートされています。サポートされているいずれかの ORM を使用している場合、アプリケーション タグは自動的に作成され、アプリケーション コードを変更する必要はほとんど、あるいはまったくありません。ORM を使用していない場合は、Sqlcommenter タグを SQL クエリに手動で追加できます。サポートされている言語とフレームワークで Sqlcommenter を使用してクエリにタグ付けできるようにする方法と、ORM を使用していない場合に手動でクエリにタグ付けする方法を以下でご説明します。

Python と SQLAlchemy で Sqlcommenter を使用する

サポートされている各 ORM には、インストールして有効にする方法を示したドキュメントと例が用意されています。ここでは、SQLAlchemy を使用する Python アプリケーションで Sqlcommenter を設定する手順を紹介します。

次のコマンドを実行し、OpenTelemetry のトレース コンテキストを記録するオプションを指定して Sqlcommenter をインストールします。

次に、アプリケーション コードで、データベース エンジンの before_cursor_execute イベントに、以下に示したイベント リスナーをアタッチします。これにより、対象のエンジンで実行されるすべてのクエリに SQL コメントが追加されるようになります。Sqlcommenter をインストールして以下のコードを追加した後は、アプリケーションに他のコード変更を加える必要はありません。

データベース ログの出力は、以下のようになります。

他の ORM とフレームワークについては、こちらに示されたリンクから Sqlcommenter の設定手順を確認できます。

Sqlcommenter の仕様を使用して手動でクエリにタグ付けする

サポートされている ORM を使用していない場合、Sqlcommenter の仕様に沿って、SQL ステートメントにコメントを手動で追加できます。Sqlcommenter アルゴリズムによって、シリアル化された Key-Value ペアが含まれるコメントが SQL ステートメントに追加されます。アルゴリズムの概要は以下のとおりです。アルゴリズムの各要素を詳細に確認するには、アルゴリズムのドキュメントをご覧ください。

Cloud SQL Insights では、action、controller、framework、route、application、db_driver、traceparent、tracestate の各キーがサポートされています。ただし、Cloud SQL Insights を使用していない場合は、他のカスタムキーを追加することもできます。

Sqlcommenter アルゴリズムに以下の情報が渡された場合:

次のように結果が出力されます。

次のステップ

PostgreSQL for Cloud SQL データベースを実行しているお客様で、まだ Insights を確認されていない場合は、ぜひすぐにご確認ください。Sqlcommenter でサポートされているいずれかの ORM かフレームワークをご利用の場合、各言語とフレームワークに対して Sqlcommenter を有効にする手順をドキュメントでご確認いただけます。また、GitHub リポジトリには、サンプル アプリケーションが用意されています。ご意見やご質問がございましたら、公開バグトラッカーに上げるか、Twitter からお寄せください。

-Cloud デベロッパー アドボケイト Jan Kleinert