postgres_exporter

Exportateur de serveur PostgreSQL

Exportateur Prometheus pour les métriques du serveur PostgreSQL.

Versions PostgreSQL testées par CI : 11 , 12 , 13 , 14 , 15 , 16

Démarrage rapide

Ce package est disponible pour 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

Testez avec :

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

Exemple de configuration 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

Utilisez maintenant le DATA_SOURCE_PASS_FILE avec un fichier monté contenant le mot de passe pour éviter d'avoir le mot de passe dans une variable d'environnement.

Le processus conteneur s'exécute avec l'uid/gid 65534 (important pour les autorisations de fichiers).

Prise en charge multi-cibles (BETA)

Cette fonctionnalité est en version bêta et peut nécessiter des modifications dans les versions futures. Les commentaires sont les bienvenus.

Cet exportateur prend en charge le modèle multi-cible. Cela permet d'exécuter une seule instance de cet exportateur pour plusieurs cibles Postgres. L'utilisation de la fonctionnalité multi-cibles de cet exportateur est facultative et destinée aux cas où il est impossible d'installer l'exportateur en tant que side-car, par exemple les services gérés en SaaS.

Pour utiliser la fonctionnalité multi-cible, envoyez une requête http au point de terminaison /probe?target=foo:5432 où la cible est définie sur le DSN de l'instance postgres à partir de laquelle récupérer les métriques.

Pour éviter de mettre des informations sensibles telles que le nom d'utilisateur et le mot de passe dans l'URL, les modules d'authentification préconfigurés sont pris en charge via la section auth_modules du fichier de configuration. Les auth_modules pour les DSN peuvent être utilisés avec le point de terminaison /probe en spécifiant le paramètre http ?auth_module=foo .

Exemple de configuration 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. 

Fichier de configuration

Le fichier de configuration contrôle le comportement de l'exportateur. Il peut être défini à l'aide de l'indicateur de ligne de commande --config.file et sa valeur par défaut est postgres_exporter.yml .

auth_modules

Cette section définit les paramètres d'authentification et de connexion prédéfinis à utiliser dans le point de terminaison multi-cible. auth_modules est une carte de modules dont la clé est l'identifiant qui peut être utilisé dans le point de terminaison /probe . Actuellement, seul le type userpass est pris en charge.

Exemple:

 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 

Construire et faire fonctionner

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

Pour créer l'image Docker :

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

Cela construira l'image du docker sous le nom prometheuscommunity/postgres_exporter:${branch} .

Drapeaux

• help Afficher l'aide contextuelle (essayez également --help-long et --help-man).

• [no-]collector.database Activer le collecteur database (par défaut : activé).

• [no-]collector.database_wraparound Activer le collecteur database_wraparound (par défaut : désactivé).

• [no-]collector.locks Activer le collecteur locks (par défaut : activé).

• [no-]collector.long_running_transactions Activer le collecteur long_running_transactions (par défaut : désactivé).

• [no-]collector.postmaster Activer le collecteur postmaster (par défaut : désactivé).

• [no-]collector.process_idle Activer le collecteur process_idle (par défaut : désactivé).

• [no-]collector.replication Activer le collecteur replication (par défaut : activé).

• [no-]collector.replication_slot Activer le collecteur replication_slot (par défaut : activé).

• [no-]collector.stat_activity_autovacuum Activer le collecteur stat_activity_autovacuum (par défaut : désactivé).

• [no-]collector.stat_bgwriter Activer le collecteur stat_bgwriter (par défaut : activé).

• [no-]collector.stat_database Activer le collecteur stat_database (par défaut : activé).

• [no-]collector.stat_statements Activer le collecteur stat_statements (par défaut : désactivé).

• [no-]collector.stat_user_tables Activer le collecteur stat_user_tables (par défaut : activé).

• [no-]collector.stat_wal_receiver Activer le collecteur stat_wal_receiver (par défaut : désactivé).

• [no-]collector.statio_user_indexes Activer le collecteur statio_user_indexes (par défaut : désactivé).

• [no-]collector.statio_user_tables Activer le collecteur statio_user_tables (par défaut : activé).

• [no-]collector.wal Activer le collecteur wal (par défaut : activé).

• [no-]collector.xlog_location Activer le collecteur xlog_location (par défaut : désactivé).

• config.file Définissez le chemin du fichier de configuration. La valeur par défaut est postgres_exporter.yml

• web.systemd-socket Utilisez les écouteurs d'activation de socket systemd au lieu des écouteurs de port (Linux uniquement). La valeur par défaut est false

• web.listen-address Adresse sur laquelle écouter l'interface Web et la télémétrie. La valeur par défaut est :9187 .

• web.config.file Fichier de configuration pour utiliser TLS et/ou l'authentification de base. Le format du fichier est décrit dans le référentiel exportateur-toolkit.

• web.telemetry-path Chemin sous lequel exposer les métriques. La valeur par défaut est /metrics .

• disable-default-metrics Utilisez uniquement les métriques fournies par queries.yaml via --extend.query-path . La valeur par défaut est false .

• disable-settings-metrics Utilisez l'indicateur si vous ne souhaitez pas supprimer pg_settings . La valeur par défaut est false .

• auto-discover-databases (DEPRECATED) Indique s'il faut découvrir les bases de données sur un serveur de manière dynamique. La valeur par défaut est false .

• extend.query-path (OBSERVÉ) Chemin d'accès à un fichier YAML contenant des requêtes personnalisées à exécuter. Consultez queries.yaml pour des exemples de format.

• dumpmaps Ne pas exécuter - imprime la représentation interne des cartes métriques. Utile lors du débogage d'un fichier de requêtes personnalisées.

• constantLabels (obsolète) Étiquettes à définir dans toutes les métriques. Une liste de paires label=value , séparées par des virgules.

• version Afficher la version de l'application.

• exclude-databases (OBSERVÉ) Une liste de bases de données à supprimer lorsque autoDiscoverDatabases est activé.

• include-databases (OBSERVÉ) Liste de bases de données à inclure uniquement lorsque autoDiscoverDatabases est activé.

• log.level Définit le niveau de journalisation : debug , info , warn , error .

• log.format Définissez le format du journal : l'un des logfmt , json .

Variables d'environnement

Les variables d'environnement suivantes configurent l'exportateur :

• DATA_SOURCE_NAME est le format hérité par défaut. Accepte le formulaire URI et les arguments de formulaire clé=valeur. L'URI peut contenir le nom d'utilisateur et le mot de passe avec lesquels se connecter.

• DATA_SOURCE_URI une alternative à DATA_SOURCE_NAME qui accepte exclusivement le nom d'hôte sans composant de nom d'utilisateur et de mot de passe. Par exemple, my_pg_hostname ou my_pg_hostname:5432/postgres?sslmode=disable .

• DATA_SOURCE_URI_FILE Identique à ci-dessus mais lit l'URI à partir d'un fichier.

• DATA_SOURCE_USER Lors de l'utilisation DATA_SOURCE_URI , cette variable d'environnement est utilisée pour spécifier le nom d'utilisateur.

• DATA_SOURCE_USER_FILE La même chose, mais lit le nom d'utilisateur à partir d'un fichier.

• DATA_SOURCE_PASS Lors de l'utilisation DATA_SOURCE_URI , cette variable d'environnement est utilisée pour spécifier le mot de passe avec lequel se connecter.

• DATA_SOURCE_PASS_FILE Identique à ci-dessus mais lit le mot de passe à partir d'un fichier.

• PG_EXPORTER_WEB_TELEMETRY_PATH Chemin sous lequel exposer les métriques. La valeur par défaut est /metrics .

• PG_EXPORTER_DISABLE_DEFAULT_METRICS Utilisez uniquement les métriques fournies par queries.yaml . La valeur peut être true ou false . La valeur par défaut est false .

• PG_EXPORTER_DISABLE_SETTINGS_METRICS Utilisez l'indicateur si vous ne souhaitez pas supprimer pg_settings . La valeur peut être true ou false . La valeur par défaut est false .

• PG_EXPORTER_AUTO_DISCOVER_DATABASES (DEPRECATED) S'il faut découvrir les bases de données sur un serveur de manière dynamique. La valeur peut être true ou false . La valeur par défaut est false .

• PG_EXPORTER_EXTEND_QUERY_PATH Chemin d'accès à un fichier YAML contenant des requêtes personnalisées à exécuter. Consultez queries.yaml pour des exemples de format.

• PG_EXPORTER_CONSTANT_LABELS (DEPRECATED) Étiquettes à définir dans toutes les métriques. Une liste de paires label=value , séparées par des virgules.

• PG_EXPORTER_EXCLUDE_DATABASES (DEPRECATED) Une liste de bases de données séparées par des virgules à supprimer lorsque autoDiscoverDatabases est activé. La valeur par défaut est une chaîne vide.

• PG_EXPORTER_INCLUDE_DATABASES (DEPRECATED) Une liste de bases de données séparées par des virgules à inclure uniquement lorsque autoDiscoverDatabases est activé. La valeur par défaut est une chaîne vide, ce qui signifie tout autoriser.

• PG_EXPORTER_METRIC_PREFIX Un préfixe à utiliser pour chacune des métriques par défaut exportées par postgres-exporter. La valeur par défaut est pg

Les paramètres définis par les variables d'environnement commençant par PG_ seront écrasés par l'indicateur CLI correspondant s'il est fourni.

Définition du nom de la source de données du serveur Postgres

Le nom de la source de données du serveur PostgreSQL doit être défini via la variable d'environnement DATA_SOURCE_NAME .

Pour l'exécuter localement sur une installation Debian/Ubuntu par défaut, cela fonctionnera (transposer en script d'initialisation le cas échéant) :

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

En outre, vous pouvez définir une liste de sources pour extraire différentes instances de la configuration d'un exportateur. Définissez simplement une chaîne séparée par des virgules.

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

Consultez le module github.com/lib/pq pour d'autres façons de formater la chaîne de connexion.

Ajout de nouvelles métriques

L'exportateur tentera d'exporter dynamiquement des métriques supplémentaires si elles sont ajoutées ultérieurement, mais elles seront marquées comme « non typées ». Des cartes de métriques supplémentaires peuvent être facilement créées à partir de la documentation Postgres en copiant les tableaux et en utilisant l'extrait Python suivant :

 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 ())

Ajustez la valeur du type de valeur prometheus résultant de manière appropriée. Cela permet de créer de riches mesures auto-documentées pour l'exportateur.

Ajout de nouvelles métriques via un fichier de configuration (OBSERVÉ)

Cette fonctionnalité est obsolète au profit des fonctions de collecteur intégrées. Pour la surveillance générique de la base de données SQL, consultez sql_exporter.

L'argument de ligne de commande -extend.query-path spécifie un fichier YAML contenant des requêtes supplémentaires à exécuter. Quelques exemples sont fournis dans queries.yaml.

Désactivation des métriques par défaut

Pour travailler avec des versions de Postgres non officiellement prises en charge (par exemple 8.2.15) ou des variantes de Postgres (par exemple Greenplum), vous pouvez désactiver les métriques par défaut avec l'option --disable-default-metrics . Cela supprime toutes les métriques intégrées et utilise uniquement les métriques définies par les requêtes dans le fichier queries.yaml que vous fournissez (vous devez donc en fournir une, sinon l'exportateur ne renverra que des statuts internes et non votre base de données).

Découvrir automatiquement les bases de données (OBSERVÉ)

Pour extraire les métriques de toutes les bases de données sur un serveur de base de données, les DSN de la base de données peuvent être découverts dynamiquement via l'indicateur --auto-discover-databases . Lorsque vrai, SELECT datname FROM pg_database WHERE datallowconn = true AND datistemplate = false and datname != current_database() est exécuté pour tous les DSN configurés. À partir du résultat, un nouvel ensemble de DSN est créé pour lequel les métriques sont récupérées.

De plus, l'option --exclude-databases ajoute la possibilité de filtrer le résultat de la découverte automatique pour supprimer les bases de données dont vous n'avez pas besoin.

Si vous souhaitez inclure uniquement un sous-ensemble de bases de données, vous pouvez utiliser l'option --include-databases . L'exportateur envoie toujours une requête à la table pg_database , mais ne la supprime que si la base de données est dans la liste d'inclusion.

Exécuter en tant que non-superutilisateur

Pour pouvoir collecter des métriques à partir des vues pg_stat* en tant que non-superutilisateur dans les versions du serveur PostgreSQL >= 10, vous pouvez accorder les rôles intégrés pg_monitor ou pg_read_all_stats à l'utilisateur. Si vous devez surveiller des serveurs PostgreSQL plus anciens, vous devrez créer des fonctions et des vues en tant que superutilisateur et leur attribuer des autorisations séparément.

 -- 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;

Exécutez la commande suivante si vous utilisez les versions de PostgreSQL >= 10

 GRANT pg_monitor to postgres_exporter;

Exécutez les commandes SQL suivantes uniquement si vous utilisez des versions de PostgreSQL antérieures à 10. Dans PostgreSQL, les vues s'exécutent avec les autorisations de l'utilisateur qui les a créées afin qu'elles puissent servir de barrières de sécurité. Des fonctions doivent être créées pour partager ces données avec le non-superutilisateur. Seule la création des vues laissera de côté les éléments de données les plus importants.

 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;

NOTE
N'oubliez pas d'utiliser le nom de la base de données postgres dans la chaîne de connexion :

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

Exécuter les tests

 # 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