Prisma、Prometheus、Grafana を使用したデータベースメトリクス

目次

• はじめに
  • メトリクスとは？
  • 使用するテクノロジー
• 前提条件
  • 前提知識
  • 開発環境
• リポジトリをクローンする
  • プロジェクトの構造とファイル
• メトリクスをアプリケーションに統合する
  • Prisma Clientでメトリクスを有効にする
  • ウェブサーバーからメトリクスを公開する
• Prometheusを統合する
  • Prometheus設定ファイルを作成する
  • Prometheusインスタンスを起動する
  • Prometheus UIでメトリクスを探索する
• Grafanaでメトリクスを可視化する
  • Grafanaインスタンスを起動する
  • GrafanaにPrometheusデータソースを追加する
  • 最初のGrafanaダッシュボードを作成する
  • (任意) 既存のGrafanaダッシュボードをインポートする
• まとめ

はじめに

このチュートリアルでは、メトリクスを使用してアプリケーションの監視機能を向上させる方法を学びます。Prisma、PostgreSQL、Expressを使用して構築されたウェブアプリケーションにメトリクスを統合する実践的な方法を説明します。

Prismaを使用してPostgreSQLデータベースと対話する、事前に構築された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
• ウェブフレームワークとしてのExpress
• プログラミング言語としてのTypeScript

前提条件

前提知識

このチュートリアルは初心者向けですが、以下を前提としています。

• JavaScriptまたはTypeScriptの基本的な知識（TypeScriptが望ましい）
• バックエンドウェブ開発の基本的な知識

注: このチュートリアルは、メトリクスに関する事前の知識を想定していません。

開発環境

このチュートリアルを進めるには、以下が必要です。

• ... 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ウェブアプリケーションを使用します。

始めるには、次の手順を実行します。

1. リポジトリをクローンする

2. クローンしたディレクトリに移動する

3. 依存関係をインストールする

4. DockerでPostgreSQLデータベースをポート5432で起動する

注: Dockerコンテナを実行しているターミナルウィンドウを閉じると、コンテナも停止します。-dオプションをコマンドの末尾に追加することで、これを回避できます。例: docker-compose up -d。

5. prisma/migrationsディレクトリからデータベースマイグレーションを適用する

注: このコマンドは、Prisma Clientを生成し、データベースにダミーデータをシードします。

6. サーバーを起動する

注: アプリケーションを開発中は、サーバーを起動したままにしてください。devスクリプトは、コードに変更があるたびにサーバーを再起動します。

プロジェクトの構造とファイル

クローンしたリポジトリは以下の構造になっています。

このリポジトリには、REST APIのコードが含まれています。/articlesエンドポイントがあり、様々なCRUD（作成、読み取り、更新、削除）操作を実行できます。また、様々な記事に対して行われた変更のログを取得できる/articles/auditエンドポイントもあります。

このリポジトリの注目すべきファイルとディレクトリは以下の通りです。

• prisma
  • schema.prisma: データベーススキーマを定義します。
  • migrations: データベースマイグレーション履歴が含まれます。
  • seed.ts: 開発データベースにダミーデータをシードするためのスクリプトが含まれます。
• server.ts: 様々なエンドポイントを持つExpress REST APIの実装。
• loadtest.js: k6を使用してREST APIに大量のトラフィックを生成するスクリプト。

注: アプリケーションをよりよく理解するために、リポジトリ内のファイルを自由に探索してください。

メトリクスをアプリケーションに統合する

あなたのExpressアプリケーションには、すべてのコアな「ビジネスロジック」がすでに実装されています。アプリケーションのパフォーマンスを測定するために、メトリクスを統合します。

このセクションでは、メトリクスを初期化し、ウェブサーバーからそれらを公開する方法を学びます。

Prisma Clientでメトリクスを有効にする

メトリクスは現在、Prismaのプレビュー機能として利用可能です。これを使用するには、schema.prismaファイルのgeneratorブロックでmetrics機能フラグを有効にする必要があります。

次に、Prisma Clientを再生成します。

メトリクス機能が有効になると、Prismaはprisma.$metrics APIを使用してデータベース操作に関するメトリクスを取得できるようになります。メトリクスはJSON形式またはPrometheus形式で公開できます。

ウェブサーバーからメトリクスを公開する

このセクションでは、Expressウェブサーバーからデータベースメトリクスを公開します。これを行うには、Prometheus形式でメトリクスを返すGET /metricsという新しいエンドポイントを作成します。

GET /metricsエンドポイントを実装するには、以下のルートをserver.tsに追加します。

サーバーが実行中であることを確認し、https://:4000/metricsにアクセスして生成されたメトリクスを確認します。

注: サーバーはnpm run devを実行して起動できます。

注: prisma.$metrics.json()を使用してJSON形式でメトリクスを取得することもできます。JSON形式の詳細についてはドキュメントを参照してください。

Prometheusを統合する

このセクションでは、Prometheusを構成し、アプリケーションに統合する方法を学びます。Prometheusは、特定のエンドポイントから定期的にデータを要求することでメトリクスを収集します。Prometheusを構成して、https://:4000/metricsエンドポイントからメトリクスデータをスクレイピングするようにします。

Prometheus設定ファイルを作成する

まず、プロジェクトのルートにprometheusという新しいフォルダを作成します。次に、このフォルダ内にprometheus.ymlという新しいファイルを作成します。

ファイルをPrometheusの設定で更新します。

覚えておくべき重要なオプションは次のとおりです。

• job_name は、特定の構成からメトリクスを識別するために使用されるメタデータです。
• scrape_interval は、Prometheusがメトリクスエンドポイントをスクレイピングする間隔です。
• targets には、スクレイピングするエンドポイントのリストが含まれます。Prometheusはデフォルトで/metricsエンドポイントをスクレイピングするため、明示的に記述する必要はありません。

  注: host.docker.internal は、Dockerを実行しているホストマシンの内部IPアドレスに解決される特別なDNS名です。PrometheusはDocker内で実行されているため、この特別なDNS名を使用して、ホストマシン（あなたのコンピューター）のhttps://を解決できるようにします。

Prometheusインスタンスを起動する

これで設定ファイルが準備できたので、Prometheusを実行する必要があります。docker-compose.ymlファイルを拡張して、Dockerコンテナ内にPrometheusを設定します。現在のファイルの内容を以下に置き換えて、docker-compose.ymlファイルにprometheusイメージを追加します。

新しいprometheusイメージは、以前に作成したprometheus/prometheus.yml設定ファイルを使用するように設定されています。また、ホストマシンにポート9090を公開し、Prometheusユーザーインターフェース（UI）にアクセスするために使用できます。このイメージは、prometheus-storageというボリュームを使用してPrometheusのデータを保存します。

注: Linuxマシンでhost.docker.internalを解決するには、extra_hostsオプションが必要です。Linuxを使用している場合は、Dockerのバージョンが20.10.0以上であることを確認してください。詳細については、こちらのGithubコメントを参照してください。

これで、Docker Composeで実行中のコンテナを再起動する必要があります。docker-compose upコマンドを再度実行し、--force-recreateオプションを追加することでこれを行うことができます。新しいターミナルウィンドウを開き、次のコマンドを実行します。

コマンドが成功すれば、https://:9090でPrometheus UIを見ることができるはずです。

Prometheus UIでメトリクスを探索する

Expression入力フィールドにPromQL (Prometheus Query Language)クエリを入力して、メトリクスデータを取得できます。たとえば、prisma_client_queries_totalと入力すると、Prisma Clientによって実行されたクエリの数を確認できます。クエリを入力した後、Executeボタンをクリックして結果を確認します。

注: 実際の値の代わりにEmpty query resultという応答が表示される場合があります。これは問題ありません — 次のステップに進んでください。

今ご覧になっているインターフェースは「expression browser」と呼ばれます。これにより、任意のPromQL式の結果をテーブルまたはグラフ形式で確認できます。

現在、クエリ数は0または空です。これは、まだAPIリクエストを何も行っていないためです。手動で大量のリクエストを行ってメトリクスデータを生成する代わりに、負荷テストツール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からアプリケーションの監視データを収集できるようにします。次に、システムの様々なメトリクスを意味のある形で表現するダッシュボードを作成します。

完全に構成されると、アプリケーションは次のようになります。

注: ウェブアプリケーションは通常、ウェブサーバーのAPIを利用するフロントエンド（クライアント）を持っていますが、このチュートリアルでは不必要な複雑さを避けるため、フロントエンドは含まれていません。

Grafanaインスタンスを起動する

Grafanaインスタンスを起動するには、Docker Composeファイルに新しいgrafanaイメージを追加する必要があります。docker-compose.ymlの現在の内容を次の設定に置き換えてください。

grafanaイメージは、データを保存するためにgrafana-storageというボリュームを使用するように構成されています。このボリュームは、Grafanaのデータを再起動後も永続化するために使用されます。grafanaイメージは、Grafana UIにアクセスするためにホストマシンにポート3000を公開するように構成されています。

次のコマンドを実行して、コンテナを再度再起動します。

https://:3000にアクセスすると、Grafanaのログイン画面が表示されます。デフォルトのユーザー名とパスワードは両方ともadminなので、これを使用してログインできます。新しいパスワードの作成はスキップしても構いません。

これでGrafanaのランディングページが表示されるはずです。

GrafanaにPrometheusデータソースを追加する

Grafanaにデータソースを追加する必要があります。データソースとは、Grafanaがメトリクスデータを取得するためにクエリできる外部システムのことです。この場合、データソースはPrometheusになります。

UIからデータソースを追加するには、次の手順を実行します。

1. サイドメニューの左下にある歯車アイコンをクリックします。
2. Data sources設定ウィンドウで、Add data sourceをクリックします。
3. データソースの種類としてPrometheusをクリックします。
4. Prometheusデータソース設定ページで、URLをhttp://prometheus:9090に、Scrape Intervalを1sに設定します。http://prometheus:9090はprometheusコンテナのポート9090に解決されます。これは、Docker Composeによって自動的に設定されるDockerネットワークのおかげで可能です。
5. Save & testをクリックして設定を保存します。

すべてが正しく設定されていれば、Data source is workingというメッセージが表示されるはずです。

最初のGrafanaダッシュボードを作成する

ダッシュボードは、メトリクスデータを表現する視覚化の集合体です。ダッシュボードは、Grafanaにおける基本的な視覚化の構成要素である1つ以上のパネルで構成されます。

注: 開始する前に、視覚化するデータがあるようにnpm run loadtestを実行してトラフィックを生成してください。

最初のダッシュボードを作成するには、以下の手順を実行します。

1. サイドメニューのDashboardsアイコンの下にある+ New dashboardオプションをクリックします。
2. ダッシュボードで、Add a new panelをクリックしてパネルエディターに移動します。QueryタブのData sourceはすでにPrometheusに設定されているはずです。
3. Queryタブ内で、Metric入力フィールドにprisma_client_queries_totalを入力します。
4. + Queryボタンを押し、新しいMetricにprisma_datasource_queries_totalを追加します。
5. 右サイドバーで、TitleフィールドをPanel Titleから「Prisma Client Queries vs. Datasource Queries」に変更します。
6. 上部のSaveを押すと、ダッシュボードの名前を尋ねられます。
7. Dashboard nameを「Prisma Metrics Dashboard」に変更し、Saveを押します。

prisma_client_queries_totalは、実行されたPrisma Clientクエリの総数を表します。prisma_datasource_queries_totalは、データソースレベルで実行されたデータベースクエリの総数を表します。これら2つのメトリクスは同じグラフで視覚化され、比較することができます。

おめでとうございます！Prisma ClientとPrisma Datasourceによるクエリ数を視覚化するダッシュボードを作成しました。これで、ダッシュボードはGrafana内でアクセスできるようになります。

注: Grafanaが提供する様々な機能を探索してみてください。例えば、ダッシュボードにさらにパネルを追加したり、視覚化の種類を変更したり、注釈を追加したりできます。また、Grafanaを使用してシステム監視のための自動アラートを設定することもできます。詳細については、Grafanaドキュメントを参照してください。

(任意) 既存のGrafanaダッシュボードをインポートする

前回のセクションでは、単一のパネルを持つダッシュボードを作成しました。このセクションでは、複数のパネルを含む既存のダッシュボードをインポートします。ダッシュボードをインポートするには、次の手順を実行します。

1. サイドメニューのDashboardsアイコンの下にある+ Importオプションをクリックします。
2. このJSONファイルをコピーしてImport via panel json入力フィールドに貼り付けます。
3. Loadボタンをクリックし、次にImportをクリックします。

これで、複数のパネルを持つダッシュボードが表示されるはずです。さまざまなパネルを探索し、それらが可視化するメトリクスを確認してください。

まとめ

このチュートリアルでは、以下を学びました。

• メトリクスとは何か、そしてなぜそれを使用すべきなのか。
• Prismaを使用して、既存のウェブアプリケーションにデータベースメトリクスを統合する方法。
• Prometheusを使用してメトリクスデータを収集し、クエリする方法。
• Grafanaを使用してメトリクスデータを視覚化する方法。

さらに学習するには、以下のリソースを参照してください。

• Prismaメトリクスドキュメント
• Prismaを使ったトレーシングのチュートリアル
• Prometheusドキュメント
• Grafanaドキュメント

メトリクス機能に関するご意見をお待ちしております！こちらのGithub issueでメトリクスに関するフィードバックをお寄せください。

このプロジェクトのソースコードはGitHubで公開しています。問題を発見した場合は、リポジトリにissueを立てるか、PRを提出してください。また、Twitterで直接私に連絡することもできます。