Prismaのメトリクス機能を使用すると、Prismaがデータベースとどのように対話しているかについての詳細な洞察が得られます。このチュートリアルでは、Prisma、Prometheus、Grafanaを使用してデータベースを監視するためにメトリクスを使用する方法を学びます。
目次
はじめに
このチュートリアルでは、メトリクスを使用してアプリケーションの監視機能を向上させる方法について学習します。 Prisma、 PostgreSQL、および Expressを使用して構築されたWebアプリケーションにメトリクスを統合する方法を実践的に確認します。
PostgreSQLデータベースと対話するためにPrismaを使用する、事前構築済みのExpress APIサーバーを使用します。チュートリアル全体を通して、Prismaのメトリクス機能を使用してAPIサーバーにメトリクスを追加する方法を学びます。また、生成されたメトリクスを収集および可視化するために、PrometheusとGrafanaをセットアップおよび構成する方法も学びます。
メトリクスとは？
メトリクスは、時間の経過に伴うシステム動作を監視および観察するために使用されるデータの数値表現です。これを使用して、システムが期待どおりに動作していることを確認したり、潜在的な問題を特定したり、ビジネス目標を測定したりできます。
Prismaでは、メトリクスはPrismaがデータベースとどのように対話するかを監視できる新機能です。メトリクスは、Prismaとデータベース接続の状態に関する情報を提供する、一連のカウンター、ゲージ、およびヒストグラムを公開します。 Prismaが公開するメトリクスには以下が含まれます。
- 実行されたPrisma Clientクエリの総数（
prisma_client_queries_total） - 実行されたSQLまたはMongoDBクエリの総数（
prisma_datasource_queries_total） - アクティブなデータベース接続の数（
prisma_pool_connections_open） - 実行されたすべてのPrisma Clientクエリの期間を含むヒストグラム（
prisma_client_queries_duration_histogram_ms） - ...その他多数！
注：利用可能なメトリクスの完全なリストは、メトリクスのドキュメントで入手できます。
メトリクスは、アプリケーションによって直接分析したり、PrometheusやStatsDなどの外部監視システムおよび時系列データベースに送信したりすることもできます。これらの外部システムとの統合により、次の機能をすぐに利用できるようになり、監視能力が大幅に向上します。
- 可視化とダッシュボードによるリアルタイムのパフォーマンス監視
- 過去データのクエリと分析
- 障害とパフォーマンスの低下に対する正確で自動化されたアラート
このチュートリアルでは、メトリクスの収集にPrometheusを使用し、メトリクスの可視化にGrafanaを使用します。
注：メトリクスは、システムの詳細な概要を把握するために、トレースと組み合わせて使用されることがよくあります。トレースの詳細については、トレースチュートリアルをご覧ください。
使用するテクノロジー
このチュートリアルでは、次のツールを使用します。
- オブジェクト・リレーショナル・マッパー（ORM）としてのPrisma
- データベースとしてのPostgreSQL
- メトリクスカウンターとしてのPrometheus
- メトリクス可視化ツールとしてのGrafana
- WebフレームワークとしてのExpress
- プログラミング言語としてのTypeScript
前提条件
前提知識
このチュートリアルは初心者向けです。ただし、以下を前提としています。
- JavaScriptまたはTypeScriptの基本的な知識（推奨）
- バックエンドWeb開発の基本的な知識
注：このチュートリアルでは、メトリクスに関する事前知識は必要ありません。
開発環境
このチュートリアルに従うには、以下が必要です。
- ... Node.jsがインストールされていること。
- ... DockerおよびDocker Composeがインストールされていること。
注：Linuxを使用している場合は、Dockerバージョンが20.10.0以降であることを確認してください。ターミナルで
docker versionを実行して、Dockerバージョンを確認できます。 - ... オプションで Prisma VS Code拡張機能がインストールされていること。 Prisma VS Code拡張機能は、Prismaに非常に優れたIntelliSenseと構文強調表示を追加します。
- ... オプションで 提供されているコマンドを実行するために、Unixシェル（LinuxおよびmacOSのターミナル/シェルなど）にアクセスできること。
Unixシェルがない場合（たとえば、Windowsマシンを使用している場合）でも、チュートリアルに従うことができますが、シェルコマンドはマシンに合わせて変更する必要がある場合があります。
リポジトリのクローン
このチュートリアル用に構築した既存のExpress Webアプリケーションを使用します。
開始するには、次の操作を実行します。
- リポジトリをクローンします
- クローンしたディレクトリに移動します
- 依存関係をインストールします
- ポート5432でPostgreSQLデータベースをDockerで起動します
注：Dockerコンテナを実行しているターミナルウィンドウを閉じると、コンテナも停止します。コマンドの最後に
-dオプション（例：docker-compose up -d）を追加すると、これを回避できます。
prisma/migrationsディレクトリからデータベース移行を適用します
注：このコマンドは、Prisma Clientも生成し、データベースにシードします。
- サーバーを起動します
注：アプリケーションを開発するときは、サーバーを実行したままにする必要があります。
devスクリプトは、コードに変更があるたびにサーバーを再起動します。
プロジェクトの構造とファイル
クローンしたリポジトリの構造は次のとおりです。
リポジトリには、REST APIのコードが含まれています。さまざまなCRUD（作成、読み取り、更新、削除）操作を実行できる/articlesエンドポイントが含まれています。また、さまざまな記事に加えられた変更のログを取得するためにクエリを実行できる/articles/auditエンドポイントもあります。
このリポジトリの注目すべきファイルとディレクトリは次のとおりです。
prismaschema.prisma：データベーススキーマを定義します。migrations：データベース移行履歴が含まれています。seed.ts：ダミーデータを使用して開発データベースにシードするスクリプトが含まれています。
server.ts：さまざまなエンドポイントを備えたExpress REST APIの実装。loadtest.js：k6を使用してREST APIに大量のトラフィックを生成するスクリプト。
注：アプリケーションをより深く理解するために、リポジトリ内のファイルを自由に探索してください。
アプリケーションへのメトリクスの統合
Expressアプリケーションには、すべてのコア「ビジネスロジック」がすでに実装されています。アプリケーションのパフォーマンスを測定するには、メトリクスを統合します。
このセクションでは、メトリクスを初期化し、Webサーバーから公開する方法について説明します。
Prisma Clientでのメトリクスの有効化
メトリクスは現在、Prismaでプレビュー機能として利用可能です。これを使用するには、schema.prismaファイルのgeneratorブロックでmetricsフィーチャーフラグを有効にする必要があります
注：このスキーマには、
interactiveTransactionsという別のプレビュー機能がすでに有効になっていることに気付いたかもしれません。これは、データベーストランザクションを実行するためにアプリケーション内で使用されます。
次に、Prisma Clientを再生成します
メトリクス機能が有効になっていると、Prismaはprisma.$metrics APIを使用してデータベース操作に関するメトリクスを取得できるようになります。メトリクスは、JSON形式またはPrometheus形式で公開できます。
Webサーバーからのメトリクスの公開
このセクションでは、Express Webサーバーからデータベースメトリクスを公開します。これを行うには、GET /metricsという新しいエンドポイントを作成します。これは、Prometheus形式でメトリクスを返します。
GET /metricsエンドポイントを実装するには、次のルートをserver.tsに追加します
サーバーが実行されていることを確認し、http://localhost:4000/metricsにアクセスして、生成されたメトリクスを確認します。
注：
npm run devを実行してサーバーを起動できます。
注：
prisma.$metrics.json()を使用してJSON形式でメトリクスを取得することもできます。 JSON形式の詳細については、ドキュメントをご覧ください。
Prometheusの統合
このセクションでは、Prometheusを構成し、アプリケーションに統合する方法について学習します。 Prometheusは、特定のエンドポイントから定期的にデータを要求することにより、メトリクスを収集します。 http://localhost:4000/metricsエンドポイントからメトリクスデータをスクレイピングするようにPrometheusを構成します。
Prometheus構成ファイルの作成
まず、プロジェクトのルートにprometheusという新しいフォルダーを作成します。次に、このフォルダーにprometheus.ymlという新しいファイルを作成します。
Prometheusの構成でファイルを更新します
覚えておくべき重要なオプションのいくつかは次のとおりです。
job_nameは、特定の構成からのメトリクスを識別するために使用されるメタデータです。scrape_intervalは、Prometheusがメトリクスエンドポイントをスクレイピングする間隔です。targetsには、スクレイピングするエンドポイントのリストが含まれています。 Prometheusは、デフォルトで/metricsエンドポイントをスクレイピングします。したがって、明示的に言及する必要はありません。注：
host.docker.internalは、Dockerを実行しているホストマシンの内部IPアドレスに解決される特別なDNS名です。 PrometheusはDocker内で実行されているため、この特別なDNS名を使用して、ホストマシン（コンピューター）のhttp://localhostを解決できるようにします。
Prometheusインスタンスの起動
構成ファイルが準備できたので、Prometheusを実行する必要があります。docker-compose.ymlファイルを拡張して、Dockerコンテナ内でPrometheusをセットアップします。docker-compose.ymlファイルにprometheusイメージを追加して、現在のファイルの内容を次のように置き換えます
新しいprometheusイメージは、以前に作成したprometheus/prometheus.yml構成ファイルを使用するようにセットアップされています。また、ポート9090をホストマシンに公開します。これは、Prometheusユーザーインターフェイス（UI）にアクセスするために使用できます。イメージは、Prometheusのデータを保存するために、prometheus-storageというボリュームを使用します。
注：
extra_hostsオプションは、Linuxマシンでhost.docker.internalを解決するために必要です。 Linuxを使用している場合は、Dockerバージョン20.10.0以降を使用していることを確認してください。詳細については、このGithubコメントを確認してください。
次に、Docker Composeで実行しているコンテナを再起動する必要があります。これを行うには、docker-compose upコマンドを再度実行し、--force-recreateオプションを追加します。新しいターミナルウィンドウを開き、次のコマンドを実行します
コマンドが成功すると、http://localhost:9090でPrometheus UIを確認できるはずです。
Prometheus UIでのメトリクスの探索
Expression入力フィールドに、PromQL（Prometheusクエリ言語）クエリを入力して、メトリクスデータを取得できます。たとえば、prisma_client_queries_totalと入力すると、Prisma Clientによって実行されたクエリの数が表示されます。クエリを入力したら、Executeボタンをクリックして結果を表示します。
注：実際の値の代わりにEmpty query resultという応答が表示される場合があります。これも問題ありません。次の手順に進んでください。
表示されているインターフェイスは、式ブラウザと呼ばれます。これにより、任意のPromQL式の結果をテーブルまたはグラフ形式で確認できます。
現在、APIリクエストをまだ行っていないため、クエリの数は0または空です。メトリクスデータを生成するために手動で多数のリクエストを行う代わりに、ロードテストツールk6を使用します。loadtest.jsというロードテストスクリプトは、プロジェクトにすでに用意されています。このスクリプトは、次のコマンドを実行して実行できます
このコマンドは、最初にk6 Dockerイメージをプルしてから、Express APIに多数のリクエストを送信し始めます。 k6がリクエストの送信を開始したら、Prometheus UIに戻り、前のクエリを再度実行できます。これで、クエリの数が急速に増加するのがわかるはずです。
Prometheus UIには、メトリクスを時系列グラフで表示する方法も用意されています。これを行うには、Graphタブをクリックします。Expression入力フィールドに、以前と同じクエリを入力し、Executeボタンをクリックします。時間の経過とともに実行されたPrisma Clientクエリの数を示すグラフが表示されるはずです。
注：Prometheus UIで他のクエリを自由に試してみてください。利用可能なすべてのメトリクスのリストは、Prismaドキュメントにあります。Prometheusドキュメントを読むことで、より複雑なPromQLクエリを実行する方法を学ぶこともできます。
Prometheus式ブラウザは、アドホッククエリをすばやく可視化するのに役立つツールです。しかし、これは完全に機能する可視化ツールではありません。 Prometheusは、機能が豊富で堅牢な可視化および分析ツールであるGrafanaと組み合わせて使用されることがよくあります。
Grafanaを使用したメトリクスの可視化
このセクションでは、Grafanaをセットアップし、それを使用してメトリクスデータを可視化するダッシュボードを作成する方法について学習します。 Grafanaは、監視と可視化に広く使用されている一般的なオープンソースの可視化ツールです。
最初に、GrafanaがPrometheusからアプリケーションの監視データを収集できるようにGrafanaを統合します。次に、システムによって公開されるさまざまなメトリクスを有意義に表現するダッシュボードを作成します。
完全に構成すると、アプリケーションは次のようになります
注：Webアプリケーションには、通常、WebサーバーのAPIを使用するフロントエンド（クライアント）があります。ただし、このチュートリアルでは、不必要な複雑さを避けるためにフロントエンドを含めていません。
Grafanaインスタンスの起動
Grafanaインスタンスを起動するには、grafanaという新しいイメージをDocker Composeファイルに追加する必要があります。docker-compose.ymlの現在の内容を次の構成に置き換えます
grafanaイメージは、データを保存するためにgrafana-storageというボリュームを使用するように構成されています。このボリュームは、再起動間でGrafanaのデータを永続化するために使用されます。grafanaイメージは、Grafana UIにアクセスするために使用できるポート3000をホストマシンに公開するように構成されています。
次のコマンドを実行して、コンテナを再度再起動します
http://localhost:3000にアクセスすると、Grafanaログイン画面が表示されます。デフォルトのユーザー名とパスワードはどちらもadminであり、これを使用してログインできます。新しいパスワードの作成はスキップできます。
これで、Grafanaランディングページが表示されるはずです。
GrafanaへのPrometheusデータソースの追加
Grafanaにデータソースを追加する必要があります。データソースは、Grafanaがクエリを実行してメトリクスデータを取得できる外部システムです。この場合、データソースはPrometheusになります。
UIを介してデータソースを追加するには、次の手順を実行します。
- サイドメニューの左下にある歯車アイコンをクリックします。
- Data sources構成ウィンドウで、Add data sourceをクリックします。
- データソースタイプとしてPrometheusをクリックします。
- Prometheusデータソース構成ページで、URLを
http://prometheus:9090に、Scrape Intervalを1sに設定します。http://prometheus:9090は、prometheusコンテナのポート9090に解決されます。これは、Docker Composeによって自動的に構成されるDockerネットワークが原因で可能です。 - Save & testをクリックして構成を保存します。
すべてが正しく構成されている場合は、Data source is workingメッセージが表示されるはずです。
最初のGrafanaダッシュボードの作成
ダッシュボードは、メトリクスデータを表す可視化のコレクションです。ダッシュボードは、Grafanaの基本的な可視化構成要素である1つ以上のパネルで構成されています。
注：開始する前に、可視化するデータがいくつかあるように、
npm run loadtestを実行してトラフィックを生成する必要があります。
最初のダッシュボードを作成するには、次の手順を実行します。
- サイドメニューのDashboardsアイコンの下にある+ New dashboardオプションをクリックします。
- ダッシュボードで、Add a new panelをクリックして、パネルエディターに移動します。QueryタブのData sourceは、すでにPrometheusに設定されているはずです。
- Queryタブ内で、Metric入力を
prisma_client_queries_totalで入力します。 - + Queryボタンを押し、新しいMetricに
prisma_datasource_queries_totalを追加します。 - 右側のサイドバーで、TitleフィールドをPanel Titleから「Prisma Client Queries vs. Datasource Queries」に変更します。
- 上部のSaveを押すと、ダッシュボードの名前を尋ねられます。
- Dashboard nameを「Prisma Metrics Dashboard」に変更し、Saveを押します。
prisma_client_queries_totalは、実行されたPrisma Clientクエリの総数を表します。prisma_datasource_queries_totalは、データソースレベルで実行されたデータベースクエリの総数を表します。 2つのメトリクスは同じグラフに可視化され、2つを比較できます。
おめでとうございます！ Prisma ClientとPrisma Datasourceによって作成されたクエリの数を可視化するダッシュボードを作成しました。ダッシュボードは、Grafana内でアクセスできるようになりました。
注：Grafanaが提供するさまざまな機能を探索する必要があります。たとえば、ダッシュボードにパネルを追加したり、可視化タイプを変更したり、注釈を追加したりできます。 Grafanaを使用して、システムを監視するための自動アラートをセットアップすることもできます。詳細については、Grafanaドキュメントをご覧ください。
（オプション）既存のGrafanaダッシュボードのインポート
最後のセクションでは、単一のパネルを含むダッシュボードを作成しました。このセクションでは、複数のパネルを含む既存のダッシュボードをインポートします。ダッシュボードをインポートするには、次の手順を実行します。
- サイドメニューのDashboardsアイコンの下にある+ Importオプションをクリックします。
- このJSONファイルをコピーして、Import via panel json入力フィールドに貼り付けます。
- Loadボタンをクリックし、次にImportをクリックします。
これで、複数のパネルを備えたダッシュボードが表示されるはずです。さまざまなパネルを調べて、可視化するメトリクスを確認する必要があります。
まとめ
このチュートリアルでは、以下を学びました。
- メトリクスとは何か、そしてそれを使用する理由。
- Prismaを使用して、既存のWebアプリケーションにデータベースメトリクスを統合する方法。
- Prometheusを使用して、メトリクスデータを収集およびクエリする方法。
- Grafanaを使用して、メトリクスデータを可視化する方法。
さらに詳しく知りたい場合は、次のリソースを確認してください。
メトリクス機能に関するご意見をお待ちしております！このGithub issueでメトリクスに関するフィードバックをお寄せください。
このプロジェクトのソースコードはGitHubにあります。問題に気付いた場合は、リポジトリで問題を提起するか、PRを送信してください。 Twitterで直接私に連絡することもできます。
次の投稿をお見逃しなく！
Prismaニュースレターに登録する