postgres_exporter

PostgreSQL サーバー エクスポーター

PostgreSQL サーバー メトリクスの Prometheus エクスポータ。

CI テスト済みの PostgreSQL バージョン: 11 、 12 、 13 、 14 、 15 、 16

クイックスタート

このパッケージは Docker で使用できます。

 # Start an example database
docker run --net=host -it --rm -e POSTGRES_PASSWORD=password postgres
# Connect to it
docker run 
  --net=host 
  -e DATA_SOURCE_URI="localhost:5432/postgres?sslmode=disable" 
  -e DATA_SOURCE_USER=postgres 
  -e DATA_SOURCE_PASS=password 
  quay.io/prometheuscommunity/postgres-exporter

以下を使用してテストします。

curl " http://localhost:9187/metrics "

Prometheus 構成の例:

 scrape_configs :
  - job_name : postgres
    static_configs :
      - targets : ["127.0.0.1:9187"] # Replace IP with the hostname of the docker container if you're running the container in a separate network

ここで、環境変数にパスワードが含まれないように、パスワードを含むマウントされたファイルで DATA_SOURCE_PASS_FILE を使用します。

コンテナー プロセスは uid/gid 65534 (ファイルのアクセス許可にとって重要) で実行されます。

マルチターゲットのサポート (ベータ版)

この機能はベータ版であり、将来のリリースでは変更が必要になる可能性があります。フィードバックは大歓迎です。

このエクスポーターはマルチターゲット パターンをサポートしています。これにより、複数の postgres ターゲットに対してこのエクスポーターの単一インスタンスを実行できるようになります。このエクスポーターのマルチターゲット機能の使用はオプションであり、SaaS マネージド サービスなど、エクスポーターをサイドカーとしてインストールできない場合を対象としています。

マルチターゲット機能を使用するには、http リクエストをエンドポイント/probe?target=foo:5432に送信します。ここで、target はメトリクスを取得する postgres インスタンスの DSN に設定されます。

ユーザー名やパスワードなどの機密情報を URL に含めることを避けるために、構成ファイルの auth_modules セクションを介して事前構成された認証モジュールがサポートされています。 DSN の auth_modules は、 ?auth_module=foo http パラメーターを指定することで/probeエンドポイントで使用できます。

Prometheus 構成の例:

 scrape_configs :
  - job_name : ' postgres '
    static_configs :
      - targets :
        - server1:5432
        - server2:5432
    metrics_path : /probe
    params :
      auth_module : [foo]
    relabel_configs :
      - source_labels : [__address__]
        target_label : __param_target
      - source_labels : [__param_target]
        target_label : instance
      - target_label : __address__
        replacement : 127.0.0.1:9116  # The postgres exporter's real hostname:port. 

設定ファイル

構成ファイルはエクスポーターの動作を制御します。 --config.fileコマンドライン フラグを使用して設定でき、デフォルトはpostgres_exporter.ymlです。

認証モジュール

このセクションでは、マルチターゲット エンドポイントで使用するプリセット認証および接続パラメーターを定義します。 auth_modulesは、 /probeエンドポイントで使用できる識別子をキーとするモジュールのマップです。現在、 userpassタイプのみがサポートされています。

例：

 auth_modules :
  foo1 : # Set this to any name you want
    type : userpass
    userpass :
      username : first
      password : firstpass
    options :
      # options become key=value parameters of the DSN
      sslmode : disable 

構築と実行

 git clone https://github.com/prometheus-community/postgres_exporter.git
cd postgres_exporter
make build
./postgres_exporter <flags>

Docker イメージをビルドするには:

 make promu
promu crossbuild -p linux/amd64 -p linux/armv7 -p linux/arm64 -p linux/ppc64le
make docker

これにより、 docker イメージがprometheuscommunity/postgres_exporter:${branch}としてビルドされます。

フラグ

• help状況依存のヘルプを表示します (--help-long および --help-man も試してください)。

• [no-]collector.database databaseコレクターを有効にします (デフォルト: 有効)。

• [no-]collector.database_wraparound database_wraparoundを有効にします (デフォルト: 無効)。

• [no-]collector.locks locksコレクターを有効にします (デフォルト: 有効)。

• [no-]collector.long_running_transactions long_running_transactionsコレクターを有効にします (デフォルト: 無効)。

• [no-]collector.postmaster postmasterコレクターを有効にします (デフォルト: 無効)。

• [no-]collector.process_idle process_idleコレクターを有効にします (デフォルト: 無効)。

• [no-]collector.replication replicationコレクターを有効にします (デフォルト: 有効)。

• [no-]collector.replication_slot replication_slotコレクターを有効にします (デフォルト: 有効)。

• [no-]collector.stat_activity_autovacuum stat_activity_autovacuumコレクターを有効にします (デフォルト: 無効)。

• [no-]collector.stat_bgwriter stat_bgwriterコレクターを有効にします (デフォルト: 有効)。

• [no-]collector.stat_database stat_databaseコレクターを有効にします (デフォルト: 有効)。

• [no-]collector.stat_statements stat_statementsコレクターを有効にします (デフォルト: 無効)。

• [no-]collector.stat_user_tables stat_user_tablesコレクターを有効にします (デフォルト: 有効)。

• [no-]collector.stat_wal_receiver stat_wal_receiverコレクターを有効にします (デフォルト: 無効)。

• [no-]collector.statio_user_indexes statio_user_indexesコレクターを有効にします (デフォルト: 無効)。

• [no-]collector.statio_user_tables statio_user_tablesコレクターを有効にします (デフォルト: 有効)。

• [no-]collector.wal walコレクターを有効にします (デフォルト: 有効)。

• [no-]collector.xlog_location xlog_locationコレクターを有効にします (デフォルト: 無効)。

• config.file構成ファイルのパスを設定します。デフォルトはpostgres_exporter.ymlです。

• web.systemd-socketポート リスナーの代わりに systemd ソケット アクティベーション リスナーを使用します (Linux のみ)。デフォルトはfalseです

• web.listen-address Web インターフェイスとテレメトリをリッスンするアドレス。デフォルトは:9187です。

• web.config.file TLS および/または基本認証を使用するための構成ファイル。ファイルの形式は、exporter-toolkit リポジトリに記載されています。

• web.telemetry-pathメトリクスを公開するパス。デフォルトは/metricsです。

• disable-default-metrics --extend.query-path経由でqueries.yamlから提供されるメトリクスのみを使用します。デフォルトはfalseです。

• disable-settings-metrics pg_settingsを収集したくない場合は、このフラグを使用します。デフォルトはfalseです。

• auto-discover-databases (非推奨) サーバー上のデータベースを動的に検出するかどうか。デフォルトはfalseです。

• extend.query-path (非推奨) 実行するカスタム クエリを含む YAML ファイルへのパス。形式の例については、 queries.yamlを確認してください。

• dumpmaps実行しない - メトリック マップの内部表現を出力します。カスタム クエリ ファイルをデバッグするときに役立ちます。

• constantLabels (非推奨) すべてのメトリックに設定するラベル。カンマで区切られたlabel=valueペアのリスト。

• versionアプリケーションのバージョンを表示します。

• exclude-databases (非推奨) autoDiscoverDatabases が有効な場合に削除するデータベースのリスト。

• include-databases (非推奨) autoDiscoverDatabases が有効な場合にのみ含めるデータベースのリスト。

• log.levelログレベルを設定します: debug 、 info 、 warn 、 errorのいずれか。

• log.formatログ形式を設定します: logfmt 、 jsonのいずれか。

環境変数

次の環境変数はエクスポーターを構成します。

• DATA_SOURCE_NAMEデフォルトのレガシー形式です。 URI 形式および key=value 形式の引数を受け入れます。 URI には、接続するためのユーザー名とパスワードが含まれる場合があります。

• DATA_SOURCE_URIユーザー名とパスワードのコンポーネントなしでホスト名のみを受け入れるDATA_SOURCE_NAMEの代替です。たとえば、 my_pg_hostnameまたはmy_pg_hostname:5432/postgres?sslmode=disable 。

• DATA_SOURCE_URI_FILE上記と同じですが、ファイルから URI を読み取ります。

• DATA_SOURCE_USER DATA_SOURCE_URI使用する場合、この環境変数はユーザー名を指定するために使用されます。

• DATA_SOURCE_USER_FILE同じですが、ファイルからユーザー名を読み取ります。

• DATA_SOURCE_PASS DATA_SOURCE_URIを使用する場合、この環境変数は接続するパスワードを指定するために使用されます。

• DATA_SOURCE_PASS_FILE上記と同じですが、ファイルからパスワードを読み取ります。

• PG_EXPORTER_WEB_TELEMETRY_PATHメトリクスを公開するパス。デフォルトは/metricsです。

• PG_EXPORTER_DISABLE_DEFAULT_METRICS queries.yamlから提供されるメトリクスのみを使用します。値はtrueまたはfalseです。デフォルトはfalseです。

• PG_EXPORTER_DISABLE_SETTINGS_METRICS pg_settingsをスクレイピングしたくない場合は、このフラグを使用します。値はtrueまたはfalseです。デフォルトはfalseです。

• PG_EXPORTER_AUTO_DISCOVER_DATABASES (非推奨) サーバー上のデータベースを動的に検出するかどうか。値はtrueまたはfalseです。デフォルトはfalseです。

• PG_EXPORTER_EXTEND_QUERY_PATH実行するカスタム クエリを含む YAML ファイルへのパス。形式の例については、 queries.yamlを確認してください。

• PG_EXPORTER_CONSTANT_LABELS (非推奨) すべてのメトリックに設定するラベル。カンマで区切られたlabel=valueペアのリスト。

• PG_EXPORTER_EXCLUDE_DATABASES (非推奨) autoDiscoverDatabases が有効な場合に削除するデータベースのカンマ区切りのリスト。デフォルトは空の文字列です。

• PG_EXPORTER_INCLUDE_DATABASES (非推奨) autoDiscoverDatabases が有効な場合にのみ含めるデータベースのカンマ区切りリスト。デフォルトは空の文字列で、すべてを許可することを意味します。

• PG_EXPORTER_METRIC_PREFIX postgres-exporter によってエクスポートされるデフォルトのメトリックのそれぞれに使用するプレフィックス。デフォルトはpgです

PG_で始まる環境変数によって設定された設定は、対応する CLI フラグ (指定されている場合) によって上書きされます。

Postgresサーバーのデータソース名の設定

PostgreSQL サーバーのデータ ソース名は、 DATA_SOURCE_NAME環境変数を介して設定する必要があります。

デフォルトの Debian/Ubuntu インストールでローカルに実行する場合、これは機能します (必要に応じて init スクリプトに置き換えます)。

 sudo -u postgres DATA_SOURCE_NAME="user=postgres host=/var/run/postgresql/ sslmode=disable" postgres_exporter

また、ソースのリストを設定して、1 つのエクスポーター設定からさまざまなインスタンスをスクレイピングすることもできます。カンマ区切りの文字列を定義するだけです。

 sudo -u postgres DATA_SOURCE_NAME="port=5432,port=6432" postgres_exporter

接続文字列をフォーマットする他の方法については、github.com/lib/pq モジュールを参照してください。

新しいメトリクスの追加

エクスポータは、今後追加のメトリクスが追加された場合に動的にエクスポートしようとしますが、それらは「型なし」としてマークされます。追加のメトリック マップは、Postgres ドキュメントからテーブルをコピーし、次の Python スニペットを使用することで簡単に作成できます。

 x = """tab separated raw text of a documentation table"""
for l in StringIO ( x ):
    column , ctype , description = l . split ( ' t ' )
    print """"{0}" : {{ prometheus.CounterValue, prometheus.NewDesc("pg_stat_database_{0}", "{2}", nil, nil) }}, """ . format ( column . strip (), ctype , description . strip ())

結果として得られるプロメテウス値タイプの値を適切に調整します。これは、エクスポータ向けに充実した自己文書化メトリクスを構築するのに役立ちます。

構成ファイルによる新しいメトリクスの追加 (非推奨)

この機能は、組み込みのコレクター関数を優先して非推奨になりました。一般的な SQL データベースの監視については、sql_exporter を参照してください。

-extend.query-path コマンドライン引数は、実行する追加のクエリを含む YAML ファイルを指定します。いくつかの例がqueries.yamlで提供されています。

デフォルトのメトリックの無効化

公式にサポートされていない postgres バージョン (例: 8.2.15)、または postgres のバリアント (例: Greenplum) を使用するには、 --disable-default-metricsフラグを使用してデフォルトのメトリクスを無効にすることができます。これにより、すべての組み込みメトリクスが削除され、指定したqueries.yamlファイル内のクエリによって定義されたメトリクスのみが使用されます (したがって、メトリクスを指定する必要があります。そうしないと、エクスポータはデータベースではなく内部ステータスのみを返します)。

データベースを自動的に検出する (非推奨)

データベース サーバー上のすべてのデータベースからメトリクスを取得するには、 --auto-discover-databasesフラグを使用してデータベース DSN を動的に検出できます。 true の場合、 SELECT datname FROM pg_database WHERE datallowconn = true AND datistemplate = false and datname != current_database()構成されているすべての DSN に対して実行されます。結果から、メトリクスが収集される新しい DSN のセットが作成されます。

さらに、オプション--exclude-databases追加すると、自動検出の結果をフィルタリングして、不要なデータベースを破棄できる可能性があります。

データベースのサブセットのみを含める場合は、オプション--include-databasesを使用できます。エクスポーターは引き続きpg_databaseテーブルにリクエストを行いますが、データベースがインクルード リストに含まれている場合にのみスクレイピングを行います。

非スーパーユーザーとして実行する

PostgreSQL サーバー バージョン 10 以上で非スーパーユーザーとしてpg_stat*ビューからメトリクスを収集できるようにするには、ユーザーにpg_monitorまたはpg_read_all_stats組み込みロールを付与します。古い PostgreSQL サーバーを監視する必要がある場合は、スーパーユーザーとして関数とビューを作成し、それらに個別に権限を割り当てる必要があります。

 -- To use IF statements, hence to be able to check if the user exists before
-- attempting creation, we need to switch to procedural SQL (PL/pgSQL)
-- instead of standard SQL.
-- More: https://www.postgresql.org/docs/9.3/plpgsql-overview.html
-- To preserve compatibility with <9.0, DO blocks are not used; instead,
-- a function is created and dropped.
CREATE OR REPLACE FUNCTION __tmp_create_user () returns void as $$
BEGIN
  IF NOT EXISTS (
          SELECT                       -- SELECT list can stay empty for this
          FROM   pg_catalog . pg_user
          WHERE  usename = ' postgres_exporter ' ) THEN
    CREATE USER postgres_exporter ;
  END IF;
END;
$$ language plpgsql;

SELECT __tmp_create_user();
DROP FUNCTION __tmp_create_user();

ALTER USER postgres_exporter WITH PASSWORD ' password ' ;
ALTER USER postgres_exporter SET SEARCH_PATH TO postgres_exporter,pg_catalog;

-- If deploying as non-superuser (for example in AWS RDS), uncomment the GRANT
-- line below and replace <MASTER_USER> with your root user.
-- GRANT postgres_exporter TO <MASTER_USER>;

GRANT CONNECT ON DATABASE postgres TO postgres_exporter;

PostgreSQL バージョン 10 以上を使用している場合は、次のコマンドを実行します。

 GRANT pg_monitor to postgres_exporter;

10 より古いバージョンの PostgreSQL を使用する場合にのみ、次の SQL コマンドを実行してください。PostgreSQL では、ビューはビューを作成したユーザーの権限で実行されるため、ビューはセキュリティ障壁として機能します。このデータをスーパーユーザー以外と共有するには関数を作成する必要があります。ビューを作成するだけでは、データの最も重要な部分が除外されます。

 CREATE SCHEMA IF NOT EXISTS postgres_exporter;
GRANT USAGE ON SCHEMA postgres_exporter TO postgres_exporter;

CREATE OR REPLACE FUNCTION get_pg_stat_activity () RETURNS SETOF pg_stat_activity AS
$$ SELECT * FROM pg_catalog . pg_stat_activity ; $$
LANGUAGE sql
VOLATILE
SECURITY DEFINER;

CREATE OR REPLACE VIEW postgres_exporter .pg_stat_activity
AS
  SELECT * from get_pg_stat_activity();

GRANT SELECT ON postgres_exporter . pg_stat_activity TO postgres_exporter;

CREATE OR REPLACE FUNCTION get_pg_stat_replication () RETURNS SETOF pg_stat_replication AS
$$ SELECT * FROM pg_catalog . pg_stat_replication ; $$
LANGUAGE sql
VOLATILE
SECURITY DEFINER;

CREATE OR REPLACE VIEW postgres_exporter .pg_stat_replication
AS
  SELECT * FROM get_pg_stat_replication();

GRANT SELECT ON postgres_exporter . pg_stat_replication TO postgres_exporter;

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE OR REPLACE FUNCTION get_pg_stat_statements () RETURNS SETOF pg_stat_statements AS
$$ SELECT * FROM public . pg_stat_statements ; $$
LANGUAGE sql
VOLATILE
SECURITY DEFINER;

CREATE OR REPLACE VIEW postgres_exporter .pg_stat_statements
AS
  SELECT * FROM get_pg_stat_statements();

GRANT SELECT ON postgres_exporter . pg_stat_statements TO postgres_exporter;

注記
接続文字列では必ずpostgresデータベース名を使用してください。

 DATA_SOURCE_NAME=postgresql://postgres_exporter:password@localhost:5432/postgres?sslmode=disable

テストの実行

 # Run the unit tests
make test
# Start the test database with docker
docker run -p 5432:5432 -e POSTGRES_DB=circle_test -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=test -d postgres
# Run the integration tests
DATA_SOURCE_NAME='postgresql://postgres:test@localhost:5432/circle_test?sslmode=disable' GOOPTS='-v -tags integration' make test