Documentation PostgreSQL 14.22 » Administration du serveur » Configuration du serveur » Remonter et tracer les erreurs

Précédent | Niveau supérieur | Suivant
20.7. Planification des requêtes | Sommaire | 20.9. Statistiques d'exécution

## 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 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.

  Quand soit stderr ou soit csvlog sont inclus, le fichier `current_logfiles` est créé pour enregistrer l'emplacement du ou des fichiers de traces actuellement utilisés par le collecteur de traces ainsi que la destination de trace associée. Cela fournit un moyen pratique pour trouver le fichier de trace actuellement utilisé par l'instance. Voici un exemple du contenu de ce fichier :

      stderr log/postgresql.log
      csvlog log/postgresql.csv

  `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 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é.)

  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 peut seulement être configuré au démarrage du serveur.

### 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 super-utilisateurs 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 super-utilisateurs 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 super-utilisateurs 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'échantillonnage 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'échantillonnage 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 super-utilisateurs 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 super-utilisateurs 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'échantillonnage 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 super-utilisateurs peuvent changer ce paramètre.

  ### Note

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

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é | Usage | syslog | eventlog
--- | --- | --- | ---
`DEBUG1 .. DEBUG5` | Fournit des informations successivement plus détaillées à destination des développeurs. | `DEBUG` | `INFORMATION`
`INFO` | Fournit des informations implicitement demandées par l'utilisateur, par exemple la sortie de `VACUUM VERBOSE`. | `INFO` | `INFORMATION`
`NOTICE` | Fournit des informations éventuellement utiles aux utilisateurs, par exemple la troncature des identifiants longs. | `NOTICE` | `INFORMATION`
`WARNING` | Fournit des messages d'avertissement sur d'éventuels problèmes. Par exemple, un `COMMIT` en dehors d'un bloc de transaction. | `NOTICE` | `WARNING`
`ERROR` | Rapporte l'erreur qui a causé l'annulation de la commande en cours. | `WARNING` | `ERROR`
`LOG` | Rapporte des informations à destination des administrateurs. Par exemple, l'activité des points de vérification. | `INFO` | `INFORMATION`
`FATAL` | Rapporte l'erreur qui a causé la fin de la session en cours. | `ERR` | `ERROR`
`PANIC` | Rapporte l'erreur qui a causé la fin de toutes les sessions. | `CRIT` | `ERROR`

### 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 par défaut (`-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. 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 chqaue 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. Désactivé 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 super-utilisateurs 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 super-utilisateurs 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 super-utilisateurs 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 super-utilisateurs 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.

  Échappement | Produit | Session seule
  --- | --- | ---
  `%a` | Nom de l'application | yes
  `%u` | Nom de l'utilisateur | oui
  `%d` | Nom de la base de données | oui
  `%r` | Nom ou adresse IP de l'hôte distant et port distant | oui
  `%h` | Nom d'hôte distant ou adresse IP | oui
  `%b` | Type de processus serveur | no
  `%p` | ID du processus | non
  `%P` | L'ID du processus leader du groupe de parallélisation, si ce processus est parallélisé | no
  `%t` | Estampille temporelle sans millisecondes | non
  `%m` | Estampille temporelle avec millisecondes | non
  `%n` | Estampille temporelle avec millisecondes (sous la forme d'un epoch Unix) | non
  `%i` | Balise de commande : type de commande | oui
  `%e` | code d'erreur correspondant à l'état SQL | no
  `%c` | ID de session : voir ci-dessous | non
  `%l` | Numéro de la ligne de trace de chaque session ou processus, commençant à 1 | non
  `%s` | Estampille temporelle du lancement du processus | oui
  `%v` | Identifiant virtuel de transaction (backendID/localXID) | no
  `%x` | ID de la transaction (0 si aucune affectée) | non
  `%q` | Ne produit aucune sortie, mais indique aux autres processus de stopper à cet endroit de la chaîne. Ignoré par les processus de session. | non
  `%Q` | Identifiant 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 idenfiant 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 super-utilisateurs 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 super-utilisateurs 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 super-utilisateurs 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 peuvent 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 53.4 pour plus d'informations à propos des commandes de réplication. La valeur par défaut est `off`. Seuls les super-utilisateurs 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 super-utilisateurs 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. 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 super-utilisateurs peuvent modifier ce paramètre.