PostgreSQLLa base de données la plus sophistiquée au monde.
Documentation PostgreSQL 15.6 » Administration du serveur » Configuration du serveur » Remonter et tracer les erreurs

20.8. Remonter et tracer les erreurs

20.8.1. Où tracer

log_destination (string)

PostgreSQL supporte plusieurs méthodes pour la journalisation des messages du serveur, dont stderr, csvlog, jsonlog et syslog. Sur Windows, eventlog est aussi supporté. Ce paramètre se configure avec la liste des destinations souhaitées séparées par des virgules. Par défaut, les traces ne sont dirigées que vers stderr. Ce paramètre ne peut être configuré que dans le fichier postgresql.conf ou indiqué sur la ligne de commande.

Si csvlog est la valeur de log_destination, les entrées du journal applicatif sont enregistrées dans le format CSV (« comma separated value »), ce qui est bien pratique pour les charger dans des programmes. Voir Section 20.8.4 pour les détails. logging_collector doit être activé pour produire des journaux applicatifs au format CSV.

Si jsonlog est inclus dans log_destination, les enregistrements des traces sont faits dans le format JSON, ce qui peut être adéquat pour le chargement des fichiers de traces dans des programmes. Voir Section 20.8.5 pour les détails. logging_collector doit être activé pour générer des traces au format JSON.

Quand soit stderr, soit csvlog, soit jsonlog sont inclus, le fichier current_logfiles est créé pour enregistrer l'emplacement des fichiers de trace actuellement utilisés par le récupérateur des traces, ainsi que la destination associée des traces. Ceci fournit un moyen agréable pour trouver les fichiers en cours d'utilisation par l'instance. Voici un exemple du contenu de ce fichier :

stderr log/postgresql.log
 csvlog log/postgresql.csv
+jsonlog log/postgresql.json

current_logfiles est recréé quand un nouveau fichier de trace est crée du à une rotation, et quand log_destination est rechargé. Il est supprimé quand ni stderr ni csvlog ni jsonlog ne sont inclus dans log_destination, et quand le collecteur de traces es désactivé.

Note

Sur la plupart des systèmes Unix, il est nécessaire de modifier la configuration du démon syslog pour utiliser l'option syslog de log_destination. PostgreSQL peut tracer dans les niveaux syslog LOCAL0 à LOCAL7 (voir syslog_facility) mais la configuration par défaut de syslog sur la plupart des plateformes ignore de tels messages. Il faut ajouter une ligne similaire à :

local0.*    /var/log/postgresql
      

dans le fichier de configuration de syslog pour obtenir ce type de journalisation.

Sur Windows, quand vous utilisez l'option eventlog pour log_destination, vous devez enregistrer une source d'événement et sa bibliothèque avec le système d'exploitation, pour que le visualisateur des événements Windows puisse affiche correctement les traces. Voir Section 19.12 pour les détails.

logging_collector (boolean)

Ce paramètre active le collecteur de traces (logging collector), qui est un processus en tâche de fond capturant les traces envoyées sur stderr et les enregistrant dans des fichiers. Cette approche est souvent plus utile que la journalisation avec syslog, car certains messages peuvent ne pas apparaître dans syslog. (Un exemple standard concerne les messages d'échec de l'édition dynamique ; un autre concerne les messages d'erreurs produits par les scripts comme archive_command.). Ce paramètre ne peut être configuré qu'au lancement du serveur.

Note

Il est possible de tracer sur stderr sans utiliser le collecteur de traces. Les messages iront à l'endroit où est redirigé la sortie des erreurs (stderr) du système. Néanmoins, cette méthode est seulement acceptable pour les petits volumes de traces car il ne fournit pas de moyens corrects pour gérer la rotation des fichiers de traces. Ainsi, sur certaines plateformes n'utilisant pas le collecteur des traces, cela peut avoir pour résultat la perte ou la corruption des traces, notamment si plusieurs processus écrivent en même temps dans le même fichier de traces, écrasant ainsi les traces des autres processus.

Note

Le collecteur des traces est conçu pour ne jamais perdre de messages. Cela signifie que, dans le cas d'une charge extrêmement forte, les processus serveur pourraient se trouver bloqués lors de l'envoi de messages de trace supplémentaires. Le collecteur pourrait accumuler dans ce cas du retard. syslog préfère supprimer des messages s'il ne peut pas les écrire. Il pourrait donc ne pas récupérer certains messages dans ces cas mais il ne bloquera pas le reste du système.

log_directory (string)

Lorsque logging_collector est activé, ce paramètre détermine le répertoire dans lequel les fichiers de trace sont créés. Il peut s'agir d'un chemin absolu ou d'un chemin relatif au répertoire des données du cluster. Ce paramètre ne peut être configuré que dans le fichier postgresql.conf ou indiqué sur la ligne de commande. La valeur par défaut est log.

log_filename (string)

Lorsque logging_collector est activé, ce paramètre indique les noms des journaux applicatifs créés. La valeur est traitée comme un motif strftime. Ainsi les échappements % peuvent être utilisés pour indiquer des noms de fichiers horodatés. (S'il y a des échappements % dépendant des fuseaux horaires, le calcul se fait dans le fuseau précisé par log_timezone.) Les échappements % supportés sont similaires à ceux listés dans la spécification de strftime par l'Open Group. Notez que la fonction strftime du système n'est pas utilisée directement, ce qui entraîne que les extensions spécifiques à la plateforme (non-standard) ne fonctionneront pas.

Si vous spécifiez un nom de fichier sans échappements, vous devriez prévoir d'utiliser un utilitaire de rotation des journaux pour éviter le risque de remplir le disque entier. Dans les versions précédentes à 8.4, si aucun échappement % n'était présent, PostgreSQL aurait ajouté l'epoch de la date de création du nouveau journal applicatif mais ce n'est plus le cas.

Si la sortie au format CSV est activée dans log_destination, .csv est automatiquement ajouté au nom du journal horodaté. (Si log_filename se termine en .log, le suffixe est simplement remplacé.)

Si la sortie en format JSON est activée dans log_destination, .json sera ajouté au nom du fichier de trace pour créer le nom du fichier au format JSON. (Si log_filename se termine en .log, le suffise est remplacé.)

Ce paramètre ne peut être positionné que dans le fichier postgresql.conf ou en ligne de commande. La valeur par défaut est postgresql-%Y-%m-%d_%H%M%S.log.

log_file_mode (integer)

Sur les systèmes Unix, ce paramètre configure les droits pour les journaux applicatifs quand logging_collector est activé. (Sur Microsoft Windows, ce paramètre est ignoré.) La valeur de ce paramètre doit être un mode numérique spécifié dans le format accepté par les appels systèmes chmod et umask. (Pour utiliser le format octal, ce nombre doit être précédé d'un zéro, 0.)

Les droits par défaut sont 0600, signifiant que seul l'utilisateur qui a lancé le serveur peut lire ou écrire les journaux applicatifs. Un autre paramétrage habituel est 0640, permettant aux membres du groupe propriétaire de lire les fichiers. Notez néanmoins que pour utiliser ce paramètre, vous devez modifier log_directory pour enregistrer les fichiers en dehors du répertoire des données de l'instance. Dans ce cas, il est déconseillé de rendre les journaux applicatifs lisibles par tout le monde car ils pourraient contenir des données sensibles.

Ce paramètre ne peut être positionné que dans le fichier postgresql.conf ou en ligne de commande.

log_rotation_age (integer)

Lorsque logging_collector est activé, ce paramètre détermine la durée maximale pour utiliser un fichier de trace individuel, après lequel un nouveau fichier de trace sera créé. Si cette valeur est indiquée sans unité, elle sera compris comme un nombre de minutes. La valeur par défaut est de 24 heures. Configurer à zéro désactive la création de nouveaux fichiers de trace en se basant sur la date et heure. Ce paramètre ne peut qu'être configuré dans le fichier postgresql.conf ou indiqué sur la ligne de commande.

log_rotation_size (integer)

Lorsque logging_collector est activé, ce paramètre détermine la taille maximale (en kilooctets) d'un journal individuel. Après cette quantité de données a été émise dans un fichier de trace, un nouveau fichier de trace sera créé. Si cette valeur est spécifiée sans unité, elle est comprise comme un nombre de Ko. La valeur par défaut est de 10 Mo. Configurer à zéro désactive la création de nouveaux fichiers de trace en se basant sur la taille. Ce paramètre ne peut être configuré que dans le fichier postgresql.conf ou indiqué sur la ligne de commande.

log_truncate_on_rotation (boolean)

Lorsque logging_collector est activé, ce paramètre impose à PostgreSQL de vider (écraser), plutôt qu'ajouter à, tout fichier journal dont le nom existe déjà. Toutefois, cet écrasement ne survient qu'à partir du moment où un nouveau fichier doit être ouvert du fait d'une rotation par temps compté, et non pas à la suite du démarrage du serveur ou d'une rotation par taille comptée. Si ce paramètre est désactivé (off), les traces sont, dans tous les cas, ajoutées aux fichiers qui existent déjà.

Par exemple, si ce paramètres est utilisé en combinaison avec un log_filename tel que postgresql-%H.log, il en résulte la génération de 24 journaux (un par heure) écrasés de façon cyclique.

Ce paramètre ne peut être configuré que dans le fichier postgresql.conf ou indiqué sur la ligne de commande.

Exemple : pour conserver sept jours de traces, un fichier par jour nommé server_log.Mon, server_log.Tue, etc. et écraser automatiquement les traces de la semaine précédente avec celles de la semaine courante, on positionne log_filename à server_log.%a, log_truncate_on_rotation à on et log_rotation_age à 1440.

Exemple : pour conserver 24 heures de traces, un journal par heure, toute en effectuant la rotation plus tôt si le journal dépasse 1 Go, on positionne log_filename à server_log.%H%M, log_truncate_on_rotation à on, log_rotation_age à 60 et log_rotation_size à 1000000. Inclure %M dans log_filename permet à toute rotation par taille comptée qui survient d'utiliser un nom de fichier distinct du nom initial horodaté.

syslog_facility (enum)

Lorsque les traces syslog sont activées, ce paramètre fixe le niveau (« facility ») utilisé par syslog. Les différentes possibilités sont LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7 ; LOCAL0 étant la valeur par défaut. Voir aussi la documentation du démon syslog du serveur. Ce paramètre ne peut être configuré que dans le fichier postgresql.conf ou indiqué sur la ligne de commande.

syslog_ident (string)

Si syslog est activé, ce paramètre fixe le nom du programme utilisé pour identifier les messages PostgreSQL dans les traces de syslog. La valeur par défaut est postgres. Ce paramètre ne peut être configuré que dans le fichier postgresql.conf ou indiqué sur la ligne de commande.

syslog_sequence_numbers (boolean)

Lorsque les traces ont pour destination syslog et que ce paramètre vaut on (c'est la valeur par défaut), alors chaque message est préfixé par un numéro de séquence en constante augmentation (par exemple [2]). Ceci permet d'éviter la suppression du type « --- last message repeated N times --- » qu'un grand nombre d'implémentations de syslog réalisent par défaut. Dans les implémentations plus modernes de syslog, la suppression des messages répétés peut être configurée (par exemple, $RepeatedMsgReduction dans rsyslog), ce paramètre pourrait ne plus être nécessaire. De plus, vous pouvez désactiver cette fonction si vous voulez vraiment supprimer des messages répétés

Ce paramètre peut seulement être configuré dans le fichier postgresql.conf ou sur la ligne de commande du serveur.

syslog_split_messages (boolean)

Lorsque les traces ont pour destination syslog, ce paramètre détermine comment les messages sont délivrées à syslog. Si ce paramètre vaut on (ce qui correspond à la valeur par défaut), les messages sont divisés en ligne, et les longues lignes sont divisées pour qu'elles tiennent sur 1024 octets, qui est la limite typique en taille pour les implémentations syslog traditionnelles. Si ce paramètre est à off, les messages du serveur PostgreSQL sont délivrés au service syslog tel quel, et c'est au service syslog de se débrouiller avec les messages potentiellement gros.

Si syslog enregistre au final les messages dans un fichier texte, alors l'effet sera le même de toute façon et il est préférable de laisser ce paramètre à la valeur on car la plupart des implémentations syslog ne peuvent pas gérer de grands messages ou auraient besoin d'être configurés spécialement pour les gérer. Si syslog écrit au final dans un autre média, il pourrait être nécessaire ou utile de conserver les messages dans un ensemble logique.

Ce paramètre peut seulement être configuré dans le fichier postgresql.conf ou sur la ligne de commande du serveur.

event_source (string)

Si la journalisation applicative se fait au travers du journal des événements (event log), ce paramètre détermine le nom du programme utilisé pour identifier les messages de PostgreSQL dans la trace. La valeur par défaut est PostgreSQL. Ce paramètre ne peut être configuré que dans le fichier postgresql.conf ou indiqué sur la ligne de commande.

20.8.2. Quand tracer

log_min_messages (enum)

Contrôle les niveaux de message écrits dans les traces du serveur. Les valeurs valides sont DEBUG5, DEBUG4, DEBUG3, DEBUG2, DEBUG1, INFO, NOTICE, WARNING, ERROR, LOG, FATAL et PANIC. Chaque niveau inclut tous les niveaux qui le suivent. Plus on progresse dans la liste, plus le nombre de messages envoyés est faible. WARNING est la valeur par défaut. LOG a ici une portée différente de celle de client_min_messages. Seuls les superutilisateurs et les utilisateurs disposant des droits SET appropriés peuvent modifier la valeur de ce paramètre.

log_min_error_statement (enum)

Contrôle si l'instruction SQL à l'origine d'une erreur doit être enregistrée dans les traces du serveur. L'instruction SQL en cours est incluse dans les traces pour tout message de sévérité indiquée ou supérieure. Les valeurs valides sont DEBUG5, DEBUG4, DEBUG3, DEBUG2, DEBUG1, INFO, NOTICE, WARNING, ERROR, LOG, FATAL et PANIC. ERROR est la valeur par défaut, ce qui signifie que les instructions à l'origine d'erreurs, de messages applicatifs, d'erreurs fatales ou de paniques sont tracées. Pour réellement désactiver le traçage des instructions échouées, ce paramètre doit être positionné à PANIC. Seuls les superutilisateurs et les utilisateurs disposant des droits SET appropriés peuvent modifier la valeur de ce paramètre.

log_min_duration_statement (integer)

Trace la durée de toute instruction terminée dont le temps d'exécution égale ou dépasse cette durée. Par exemple, si le paramètre est positionné à 250ms, alors toutes les instructions SQL dont la durée est supérieure ou égale à 250 ms sont tracées. Il est utile d'activer ce paramètre pour tracer les requêtes non optimisées des applications. Si cette valeur est indiquée sans unité, elle est considérée comme un nombre de millisecondes. La configurer à zéro affiche la durée de toutes les requêtes. -1 (valeur par défaut) désactive la trace de la durée des requêtes. Seuls les superutilisateurs et les utilisateurs disposant des droits SET appropriés peuvent modifier cette configuration.

Ceci surcharge log_min_duration_sample, ceci signifiant que les requêtes dont la durée dépasse cette configuration ne sont pas sujet à l'échantillonage et sont toujours tracées.

Pour les clients utilisant le protocole de requêtage étendu, les durées des étapes Parse (analyse), Bind (lien) et Execute (exécution) sont tracées indépendamment.

Note

Lorsque cette option est utilisée avec log_statement, le texte des instructions tracées du fait de log_statement n'est pas répété dans le message de trace de la durée. Si syslog n'est pas utilisé, il est recommandé de tracer le PID ou l'ID de session à l'aide de log_line_prefix de façon à pouvoir lier le message de l'instruction au message de durée par cet identifiant.

log_min_duration_sample (integer)

Permet l'échantillonage de la durée des requêtes traitées pour celles qui durent au moins la durée indiquée. Ceci produit le même type de traces que log_min_duration_statement, mais seulement pour un sous-ensemble des requêtes exécutées, avec un taux d'échantillonnage contrôlé avec le paramètre log_statement_sample_rate. Par exemple, si vous voulez le configurer à 100ms, alors toutes les requêtes SQL qui durent 100 millisecondes ou plus seront considérées pour l'échantillonnage. Activer ce paramètre peut être utile quand le trafic est trop important pour tracer toutes les requêtes. Si cette valeur est indiquée sans unité, elle est considérée comme un nombre de milltisecondes. Le configurer à zéro échantillonne toutes les durées de requêtes. La valeur -1 (valeur par défaut) désactive l'échantillonnage des durées des requêtes. Seuls les superutilisateurs et les utilisateurs disposant des droits SET appropriés peuvent modifier ce paramètre.

Ce paramètre a une priorité plus basse que log_min_duration_statement, signifiant que les requêtes dont la durée dépasse log_min_duration_statement ne sont pas sujets à l'échantillonnage et seront toujours tracées.

D'autres notes pour log_min_duration_statement s'appliquent aussi à ce paramètre.

log_statement_sample_rate (floating point)

Détermine la fraction de requêtes dont la durée dépasse log_min_duration_sample et qui seront tracées. L'échantillonnage est stochastique, par exemple 0.5 signifie qu'il y a une chance sur qu'une requête soit tracée. La valeur par défaut est 1.0, signifiant toutes les requêtes. Le configurer à zéro désactive la trace des durées des requêtes, tout comme configurer le paramètre log_min_duration_sample à -1. Seuls les superutilisateurs et les utilisateurs disposant des droits SET appropriés peuvent modifier ce paramètre.

log_transaction_sample_rate (floating point)

Initialise la fraction de transactions dont les requêtes seront toutes tracées en plus des requêtes tracées pour d'autres raisons. Cela s'applique à toute nouvelle transaction, quelque soit les durées des requêtes. L'échantillonage est stochastique, par exemple 0.1 signifie qu'il y a statistiquement une chance sur dix qu'une transaction donnée soit tracée. log_transaction_sample_rate peut être utilisé pour construire un échantillon de transactions. La valeur par défaut (0) signifie qu'aucune requête d'une transaction supplémentaire ne sera tracée. Positionner ce paramètre à 1 permet de tracer toutes les requêtes de toutes les transactions. Seuls les superutilisateurs peuvent changer ce paramètre.

Note

Comme toutes les options sur les traces des requêtes, cette option peut ajouter une surcharge importante.

log_startup_progress_interval (integer)

Configure la durée après laquelle le processus de démarrage tracera un message sur l'opération longue toujours en cours, ainsi que l'intervalle entre les messages de progression*. La valeur par défaut est de 10 secondes. Une configuration à 0 désactive cette fonctionnalité. Si cette valeur est indiquée sans unité, elle est considérée comme étant un nombre de millisecondes. Cette configuration est appliquée séparément pour chaque opération. Ce paramètre peut seulement être configuré dans le fichier postgresql.conf et sur la ligne de commande du serveur.

Par exemple, si la synchronisation du répertoire de données prends 25 secondes et qu'après cela, la réinitialisation des relations non journalisées prend 8 secondes et que ce paramètre a sa valeur par défaut de 10 secondes, alors un message sera tracé pour la synchronisation du répertoire de données une fois que cette étape est en cours depuis plus de 10 secondes, puis de nouveau au bout de 20 secondes, mais rien ne sera tracé pour les opérations de réinitialisation des relations non journalisées.

Tableau 20.2 explique les niveaux de sévérité des messages utilisés par PostgreSQL. Si la journalisation est envoyée àsyslog ou à l'eventlog de Windows, les niveaux de sévérité sont traduits comme indiqué ci-dessous.

Tableau 20.2. Niveaux de sévérité des messages

SévéritéUsagesyslogeventlog
DEBUG1 .. DEBUG5Fournit des informations successivement plus détaillées à destination des développeurs.DEBUGINFORMATION
INFOFournit des informations implicitement demandées par l'utilisateur, par exemple la sortie de VACUUM VERBOSE.INFOINFORMATION
NOTICEFournit des informations éventuellement utiles aux utilisateurs, par exemple la troncature des identifiants longs.NOTICEINFORMATION
WARNINGFournit des messages d'avertissement sur d'éventuels problèmes. Par exemple, un COMMIT en dehors d'un bloc de transaction.NOTICEWARNING
ERRORRapporte l'erreur qui a causé l'annulation de la commande en cours.WARNINGERROR
LOGRapporte des informations à destination des administrateurs. Par exemple, l'activité des points de vérification.INFOINFORMATION
FATALRapporte l'erreur qui a causé la fin de la session en cours.ERRERROR
PANICRapporte l'erreur qui a causé la fin de toutes les sessions.CRITERROR

20.8.3. Que tracer

Note

Ce que vous choisissez de tracer peut avoir des implications sur la sécurité ; voir Section 25.3.

application_name (string)

Le paramètre application_name peut être n'importe quelle chaîne de caractères inférieure à NAMEDATALEN caractères (64 caractères après une compilation standard). Il est typiquement configuré lors de la connexion d'une application au serveur. Le nom sera affiché dans la vue pg_stat_activity et inclus dans les traces du journal au format CSV. Il peut aussi être inclus dans les autres formats de traces en configurant le paramètre log_line_prefix. Tout caractère ASCII affichable peut être utilisé. Les autres caractères seront remplacés par des points d'interrogation (?).

debug_print_parse (boolean)
debug_print_rewritten (boolean)
debug_print_plan (boolean)

Ces paramètres activent plusieurs sorties de débogage. Quand positionnés, il affichent l'arbre d'interprétation résultant, la sortie de la réécriture de requête, ou le plan d'exécution pour chaque requête exécutée. Ces messages sont émis au niveau de trace LOG , par conséquent ils apparaîtront dans le journal applicatif du serveur, mais ne seront pas envoyés au client. Vous pouvez changer cela en ajustant client_min_messages et/ou log_min_messages. Ces paramètres sont désactivés par défaut.

debug_pretty_print (boolean)

Quand positionné, debug_pretty_print indente les messages produits par debug_print_parse, debug_print_rewritten, ou debug_print_plan. Le résultat est une sortie plus lisible mais plus verbeuse que le format « compact » utilisé quand ce paramètre est à off. La valeur par défaut est 'on'.

log_autovacuum_min_duration (integer)

Permet de tracer chaque action de l'autovacuum dans les journaux de PostgreSQL si celui-ci tourne pour une durée supérieure à la valeur spécifiée. Configurer ce paramètre à zéro permet de tracer toutes les actions de l'autovacuum. La valeur -1 désactive cette fonctionnalité. Si la valeur ne comporte pas d'unité, elle est comprise en millisecondes. Par exemple, si la valeur 250ms est fournie, toutes les actions des opérations automatiques de vacuum et d'analyze durant plus de 250ms seront tracées dans les journaux de PostgreSQL. De plus, lorsque ce paramètre prend une valeur différente de -1, un message sera inscrit dans les journaux de PostgreSQL si une action d'autovacuum doit être omise à cause d'un conflit de verrou ou parce qu'une relation a été supprimée entretemps. La valeur par défaut est 10min. Activer ce paramètre peut aider à mieux comprendre les activités de l'autovacuum. Ce paramètre ne peut être configuré que dans le fichier postgresql.conf ou sur la ligne de commande, mais le paramétrage peut être surchargé pour chaque table au niveau des paramètres de stockage de chaque table.

log_checkpoints (boolean)

Trace les points de vérification and restartpoints dans les journaux applicatifs. Diverses statistiques sont incluses dans les journaux applicatifs, dont le nombre de tampons écrits et le temps passé à les écrire. Activé par défaut, ce paramètre ne peut être configuré que dans le fichier postgresql.conf ou indiqué sur la ligne de commande.

log_connections (boolean)

Trace chaque tentative de connexion sur le serveur, ainsi que la réussite de l'authentification du client (si nécessaire) et son autorisation. Seuls les superutilisateurs et les utilisateurs disposant des droits SET adéquats peuvent modifier ce paramètre au démarrage d'une session, et il ne peut pas être changé du tout à l'intérieur d'une session. La valeur par défaut est off.

Note

Quelques programmes clients, comme psql, tentent de se connecter deux fois pour déterminer si un mot de passe est nécessaire, des messages « connection received » dupliqués n'indiquent donc pas forcément un problème.

log_disconnections (boolean)

Entraîne l'enregistrement dans les traces du serveur de la fin des sessions. Les sorties des traces fournissent une information similaire à log_connections, plus la durée de la session. Seuls les superutilisateurs et les utilisateurs disposant des droits SET adéquats peuvent modifier ce paramètre au démarrage d'une session, et il ne peut pas être changé du tout à l'intérieur d'une session. La valeur par défaut est off.

log_duration (boolean)

Trace la durée de toute instruction exécutée. Désactivé par défaut (off), seuls les superutilisateurs et les utilisateurs disposant des droits SET adéquats peuvent modifier ce paramètre.

Pour les clients utilisant le protocole de requêtage étendu, les durées des étapes Parse (analyse), Bind (lien) et Execute (exécution) sont tracées indépendamment.

Note

À la différence de log_min_duration_statement, log_duration ne force pas le traçage du texte des requêtes. De ce fait, si log_duration est activé (on) et que log_min_duration_statement a une valeur positive, toutes les durées sont tracées mais le texte de la requête n'est inclus que pour les instructions qui dépassent la limite. Ce comportement peut être utile pour récupérer des statistiques sur les installations à forte charge.

log_error_verbosity (enum)

Contrôle la quantité de détails écrit dans les traces pour chaque message tracé. Les valeurs valides sont TERSE, DEFAULT et VERBOSE, chacun ajoutant plus de champs aux messages affichés. TERSE exclut des traces les informations de niveau DETAIL, HINT, QUERY et CONTEXT. La sortie VERBOSE inclut le code d'erreur SQLSTATE (voir aussi Annexe A), le nom du code source, le nom de la fonction et le numéro de la ligne qui a généré l'erreur. Seuls les superutilisateurs et les utilisateurs disposant des droits SET adéquats peuvent modifier ce paramètre.

log_hostname (boolean)

Par défaut, les traces de connexion n'affichent que l'adresse IP de l'hôte se connectant. Activer ce paramètre permet de tracer aussi le nom de l'hôte. En fonction de la configuration de la résolution de nom d'hôte, les performances peuvent être pénalisées. Ce paramètre ne peut être configuré que dans le fichier postgresql.conf ou indiqué sur la ligne de commande.

log_line_prefix (string)

Il s'agit d'une chaîne de style printf affichée au début de chaque ligne de trace. Les caractères % débutent des « séquences d'échappement » qui sont remplacées avec l'information de statut décrite ci-dessous. Les échappement non reconnus sont ignorés. Les autres caractères sont copiés directement dans la trace. Certains échappements ne sont reconnus que par les processus de session et seront traités comme vide par les processus en tâche de fond tels que le processus principal du serveur. L'information de statut pourrait être alignée soit à gauche soit à droite en indiquant un nombre après le signe pourcent et avant l'option. Une valeur négative implique un alignement à droite par ajout d'espaces alors qu'une valeur positive est pour un alignement à gauche. L'alignement peut être utile pour aider à la lecture des fichiers de trace.

Ce paramètre ne peut être configuré que dans le fichier postgresql.conf ou indiqué sur la ligne de commande. La valeur par défaut est '%m [%p] ' ce qui affiche dans les trace l'heure courante ainsi que l'identifiant de processus.

ÉchappementProduitSession seule
%aNom de l'applicationyes
%uNom de l'utilisateuroui
%dNom de la base de donnéesoui
%rNom ou adresse IP de l'hôte distant et port distantoui
%hNom d'hôte distant ou adresse IPoui
%bType de processus serveurno
%pID du processusnon
%PL'ID du processus leader du groupe de parallélisation, si ce processus est paralléliséno
%tEstampille temporelle sans millisecondesnon
%mEstampille temporelle avec millisecondesnon
%nEstampille temporelle avec millisecondes (sous la forme d'un epoch Unix)non
%iBalise de commande : type de commandeoui
%ecode d'erreur correspondant à l'état SQLno
%cID de session : voir ci-dessousnon
%lNuméro de la ligne de trace de chaque session ou processus, commençant à 1non
%sEstampille temporelle du lancement du processusoui
%vIdentifiant virtuel de transaction (backendID/localXID)no
%xID de la transaction (0 si aucune affectée)non
%qNe produit aucune sortie, mais indique aux autres processus de stopper à cet endroit de la chaîne. Ignoré par les processus de session.non
%QIdentifiant de la requête actuelle. Les identifiants de requête ne sont pas calculés par défaut, ce champ vaudra donc zéro à moins que le paramètre compute_query_id ne soit activé ou qu'un module externe qui calcule ce champ ne soit utilisé.oui
%%%non

Le type de processus serveur correspond à la colonne backend_type dans la vue pg_stat_activity, mais des types supplémentaires, non visibles dans cette vue, peuvent apparaître dans les traces.

L'échappement %c affiche un identifiant de session quasi-unique constitué de deux nombres hexadécimaux sur quatre octets (sans les zéros initiaux) et séparés par un point. Les nombres représentent l'heure de lancement du processus et l'identifiant du processus, %c peut donc aussi être utilisé comme une manière de raccourcir l'affichage de ces éléments. Par exemple, pour générer l'identifiant de session à partir de pg_stat_activity, utilisez cette requête :

SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' ||
       to_hex(pid)
FROM pg_stat_activity;
     

Astuce

Si log_line_prefix est différent d'une chaîne vide, il est intéressant d'ajouter une espace en fin de chaîne pour créer une séparation visuelle avec le reste de la ligne. Un caractère de ponctuation peut aussi être utilisé.

Astuce

syslog produit ses propres informations d'horodatage et d'identifiant du processus. Ces échappements n'ont donc que peu d'intérêt avec syslog.

Astuce

L'échappement %q est utile quand des informations qui ne sont disponibles que dans le contexte d'une session (processus client) est utilisé, comme le nom de l'utilisateur ou de la base. Par exemple :

log_line_prefix = '%m [%p] %q%u@%d/%a '
      

Note

L'échappement %Q retourne toujours un identifiant à zéro pour les sorties de lignes ordonnées par log_statement car log_statement génère la sortie avant que les identifiants ne soient calculés, y compris pour les requêtes invalides pour lesquelles un identifiant ne peut pas être calculé.

log_lock_waits (boolean)

Contrôle si une trace applicative est écrite quand une session attend plus longtemps que deadlock_timeout pour acquérir un verrou. Ceci est utile pour déterminer si les attentes de verrous sont la cause des pertes de performance. Désactivé (off) par défaut. Seuls les superutilisateurs et les utilisateurs disposant des droits SET adéquats peuvent modifier ce paramétrage.

log_recovery_conflict_waits (boolean)

Contrôle si un message doit être tracé dans les journaux de PostgreSQL au cas où le processus de démarrage doit attendre plus longtemps que deadlock_timeout en cas de conflit de récupération. C'est utile pour savoir si un conflit de restauration empêche l'application des journaux de transactions.

La valeur par défaut est off. Ce paramètre ne peut être configuré que dans le fichier postgresql.conf ou sur la ligne de commande.

log_parameter_max_length (integer)

Si supérieur à zéro, chaque valeur de paramètre lié tracée avec un message qui n'est pas dû à une erreur est raccourcie à ce nombre d'octets. Zéro désactive la trace des paramètres liés pour les traces de requêtes sans erreur. -1 (valeur par défaut) autorise la trace complète des paramètres liés. Si cette valeur est indiquée sans unité, elle est prise pour un nombre d'octets. Seuls les superutilisateurs et les utilisateurs disposant des droits SET appropriés peuvent modifier ce paramètre.

Ce paramètre affecte seulement les messages affichés en résultat de la configuration de log_statement, log_duration, et d'autres paramètres liés. Une valeur différente de zéro pour ce paramètre ajoute une surcharge, particulièrement si les paramètres sont envoyés en forme binaire, parce qu'une conversion en texte est requise.

log_parameter_max_length_on_error (integer)

Si supérieur à zéro, chaque valeur de paramètre lié dans une trace d'erreur est raccourcie à ce nombre d'octets. Zéro (valeur par défaut) désactive la trace des paramètres liés pour les traces de requêtes en erreur. -1 autorise la trace complète des paramètres liés. Si cette valeur est indiquée sans unité, elle est prise pour un nombre d'octets.

Une configuration de ce paramètre à une valeur différente de zéro ajoute une surcharge car PostgreSQL aura besoin de stocker les représentations textuelles des valeurs de paramètres en mémoire au début de chaque requête, qu'une erreur survienne ou pas. La surcharge est supérieure quand les paramètres liés sont envoyés au format binaire que quand ils sont envoyés au format car le premier cas nécessite la conversion des données alors que le dernier cas nécessite seulement la copie de la chaîne.

log_statement (enum)

Contrôle les instructions SQL à tracer. Les valeurs valides sont none (off), ddl, mod et all (toutes les instructions). ddl trace toutes les commandes de définition comme CREATE, ALTER et DROP. mod trace toutes les instructions ddl ainsi que les instructions de modification de données INSERT, UPDATE, DELETE, TRUNCATE et COPY FROM. Les instructions PREPARE, EXECUTE et EXPLAIN ANALYZE sont aussi tracées si la commande qui les contient est d'un type approprié. Pour les clients utilisant le protocole de requêtage étendu, la trace survient quand un message Execute est reçu et les valeurs des paramètres de Bind sont incluses (avec doublement de tout guillemet simple embarqué).

La valeur par défaut est none. Seuls les superutilisateurs et les utilisateurs disposant des droits SET appropriés peuvent changer ce paramétrage.

Note

Les instructions qui contiennent de simples erreurs de syntaxe ne sont pas tracées même si log_statement est positionné à all car la trace n'est émise qu'après qu'une analyse basique soit réalisée pour déterminer le type d'instruction. Dans le cas du protocole de requêtage étendu, ce paramètre ne trace pas les instructions qui échouent avant la phase Execute (c'est-à-dire pendant l'analyse et la planification). log_min_error_statement doit être positionné à ERROR pour tracer ce type d'instructions.

Les requêtes tracées pourraient révéler des données sensibles et même contenir des mots de passe en clair.

log_replication_commands (boolean)

A pour effet d'enregistrer dans le fichier des traces du serveur chaque commande de réplication. Voir Section 55.4 pour plus d'informations à propos des commandes de réplication. La valeur par défaut est off. Seuls les superutilisateurs et les utilisateurs avec les droits SET adéquats peuvent modifier ce paramètre.

log_temp_files (integer)

Contrôle l'écriture de traces sur l'utilisation des fichiers temporaires (noms et tailles). Les fichiers temporaires peuvent être créés pour des tris, des hachages et des résultats temporaires de requête. Si activé, une entrée de journal est générée pour chaque fichier temporaire au moment où il est effacé. Zéro implique une trace des informations sur tous les fichiers temporaires alors qu'une valeur positive ne trace que les fichiers dont la taille est supérieure ou égale au nombre indiqué (en kilo-octets). Si cette valeur est indiquée sans unité, elle est comprise comme un nombre de Ko. La valeur par défaut est -1, ce qui a pour effet de désactiver les traces. Seuls les superutilisateurs et les utilisateurs disposant des droits SET peuvent modifier ce paramètre.

log_timezone (string)

Configure le fuseau horaire utilisé par l'horodatage des traces. Contrairement à TimeZone, cette valeur est valable pour le cluster complet, de façon à ce que toutes les sessions utilisent le même. La valeur par défaut est GMT, mais elle est généralement surchargée dans le fichier postgresql.conf ; initdb installera une configuration correspondant à l'environnement système. Voir Section 8.5.3 pour plus d'informations.

20.8.4. Utiliser les journaux au format CSV

L'ajout de csvlog dans la liste log_destination est une manière simple d'importer des journaux dans une table de base de données. Cette option permet de créer des journaux au format CSV avec les colonnes : l'horodatage en millisecondes, le nom de l'utilisateur, le nom de la base de données, le PID du processus serveur, l'hôte et le numéro de port du client, l'identifiant de la session, le numéro de ligne dans la session, le tag de la commande, l'horodatage de début de la session, l'identifiant de transaction virtuelle, l'identifiant de transaction standard, la sévérité de l'erreur, le code SQLSTATE, le message d'erreur, les détails du message d'erreur, une astuce, la requête interne qui a amené l'erreur (si elle existe), le nombre de caractères pour arriver à la position de l'erreur, le contexte de l'erreur, la requête utilisateur qui a amené l'erreur (si elle existe et si log_min_error_statement est activé), le nombre de caractères pour arriver à la position de l'erreur, l'emplacement de l'erreur dans le code source de PostgreSQL (si log_error_verbosity est configuré à verbose), le nom de l'application, le type du processus serveur, l'identifiant du processus du leader et l'identifiant de la requête.

Exemple de définition d'une table de stockage de journaux au format CSV :

CREATE TABLE postgres_log
(
  log_time timestamp(3) with time zone,
  user_name text,
  database_name text,
  process_id integer,
  connection_from text,
  session_id text,
  session_line_num bigint,
  command_tag text,
  session_start_time timestamp with time zone,
  virtual_transaction_id text,
  transaction_id bigint,
  error_severity text,
  sql_state_code text,
  message text,
  detail text,
  hint text,
  internal_query text,
  internal_query_pos integer,
  context text,
  query text,
  query_pos integer,
  location text,
  application_name text,
  backend_type text,
  leader_pid integer,
  query_id bigint,
  PRIMARY KEY (session_id, session_line_num)
);
 

Pour importer un journal dans cette table, on utilise la commande COPY FROM :

COPY postgres_log FROM '/chemin/complet/vers/le/logfile.csv' WITH csv;
  

Il est aussi possible d'accéder au fichier via une table externe en utilisant le module file_fdw.

Quelques conseils pour simplifier et automatiser l'import des journaux CVS :

  1. configurer log_filename et log_rotation_age pour fournir un schéma de nommage cohérent et prévisible des journaux. Cela permet de prédire le nom du fichier et le moment où il sera complet (et donc prêt à être importé) ;

  2. initialiser log_rotation_size à 0 pour désactiver la rotation par taille comptée, car elle rend plus difficile la prévision du nom du journal ;

  3. positionner log_truncate_on_rotation à on pour que les données anciennes ne soient pas mélangées aux nouvelles dans le même fichier ;

  4. la définition de la table ci-dessus inclut une clé primaire. C'est utile pour se protéger de l'import accidentel de la même information à plusieurs reprises. La commande COPY valide toutes les données qu'elle importe en une fois. Toute erreur annule donc l'import complet. Si un journal incomplet est importé et qu'il est de nouveau importé lorsque le fichier est complet, la violation de la clé primaire cause un échec de l'import. Il faut attendre que le journal soit complet et fermé avant de l'importer. Cette procédure protége aussi de l'import accidentel d'une ligne partiellement écrite, qui causerait aussi un échec de COPY.

20.8.5. Utiliser le format de trace JSON

Ajouter jsonlog dans la liste log_destination permet d'importer facilement les fichiers de trace dans différents programmes. Cette option émet des lignes de trace au format JSON.

Les champs texte avec des valeurs NULL sont exclus de la sortie. Des champs supplémentaires pourraient être ajoutés dans le futur. Les applications utilisateurs qui traitent le format jsonlog doivent ignorer les champs inconnus.

Chaque ligne de trace est sérialisée sous la forme d'un objet JSON avec un ensemble de clés et de valeurs associées, clés indiquées dans Tableau 20.3.

Tableau 20.3. Clés et valeurs des enregistrements JSON

CléTypeDescription
timestampstringHorodatage en millisecondes
userstringNom d'utilisateur
dbnamestringNom de base de données
pidnumberIdentifiant de processus
remote_hoststringHôte client
remote_portnumberPort client
session_idstringIdentifiant de session
line_numnumberNuméro de ligne par session
psstringAffichage actuel de ps
session_startstringHeure de début de session
vxidstringIdentifiant de transaction virtuelle
txidstringIdentifiant de transaction standard
error_severitystringNiveau de l'erreur
state_codestringCode SQLSTATE
messagestringMessage d'erreur
detailstringDétails du message d'erreur
hintstringAstuce du message d'erreur
internal_querystringRequête interne qui amène à l'erreur
internal_positionnumberCurseur dans la requête interne
contextstringContexte d'erreur
statementstringChaîne de requête fournie par le client
cursor_positionnumberCurseur dans la chaîne de requête
func_namestringNom de la fonction ayant déclenché l'erreur
file_namestringNom du fichier contenant la fonction ayant déclenché l'erreur
file_line_numnumberNuméro de ligne du fichier contenant la fonction ayant déclenché l'erreur
application_namestringNom d'application du client
backend_typestringType de backend
leader_pidnumberIdentifiant du processus leader pour les workers parallélisés
query_idnumberIdentifiant de requête

20.8.6. Titre des processus

Ces paramètres contrôlent comment les titres de processus des processus serveurs sont modifiés. Les titres de processus sont affichées typiquement en utilisant des programmes comme ps ou, sur Windows, Process Explorer. Voir Section 28.1 pour plus de détails.

cluster_name (string)

Configure un nom qui identifie cette instance pour différentes raisons. Le nom de l'instance apparaît dans le titre de tous les processus de l'instance. De plus, c'est le nom d'application par défaut pour une connexion standby (voir synchronous_standby_names.)

Le nom peut être n'importe quelle chaîne de caractères de longueur inférieure à NAMEDATALEN (64 caractères dans une compilation standard du serveur). Seuls les caractères ASCII imprimables peuvent être utilisés dans cluster_name. Les autres caractères seront remplacés par des points d'interrogation (?). Aucun nom n'est affiché si ce paramètre est positionné sur la chaîne vide '' (ce qui est la valeur par défaut). Ce paramètre ne peut être positionné qu'au démarrage du serveur.

update_process_title (boolean)

Active la mise à jour du titre du processus chaque fois qu'une nouvelle commande SQL est reçue par le serveur. Ce paramètre est à on par défaut sur la plupart des plateformes mais il est à off sur Windows car cette plateforme souffre de lenteurs plus importantes pour la mise à jour du titre du processus. Seuls les superutilisateurs et les utilisateurs disposant des droits SET adéquats peuvent modifier ce paramètre.