Serveur HTTP Apache Version 2.5

Apache > Serveur HTTP > Documentation > Version 2.5 > Modules

# Module Apache mod_log_config

Description: | Journalisation des requêtes envoyées au serveur
Statut: | Base
Identificateur de Module: | log_config_module
Fichier Source: | mod_log_config.c

### Sommaire

Ce module apporte une grande souplesse dans la journalisation des requêtes des clients. Les journaux sont écrits sous un format personnalisable, et peuvent être enregistrés directement dans un fichier, ou redirigés vers un programme externe. La journalisation conditionnelle est supportée, si bien que des requêtes individuelles peuvent être incluses ou exclues des journaux en fonction de leur caractéristiques.

Ce module fournit trois directives : `TransferLog` crée un fichier journal, `LogFormat` définit un format personnalisé, et `CustomLog` définit un fichier journal et un format en une seule étape. Pour journaliser les requêtes dans plusieurs fichiers, vous pouvez utiliser plusieurs fois les directives `TransferLog` et `CustomLog` dans chaque serveur.

### Sujets

- Formats de journaux personnalisés
- Considérations concernant la sécurité

### Directives

### Traitement des bugs

- Journal des modifications de httpd
- Problèmes connus
- Signaler un bug

### Voir aussi

- Les fichiers journaux d'Apache

## Formats de journaux personnalisés ¶

L'argument format des directives `LogFormat` et `CustomLog` est une chaîne de caractères. Cette chaîne définit le format de la journalisation des requêtes dans le fichier journal. Elle peut contenir des caractères littéraux qui seront reproduits dans le fichier journal, et les caractères de contrôle de style C "\n" et "\t" représentant respectivement une nouvelle ligne et une tabulation. Les guillemets et les anti-slashes littéraux doivent être échappés à l'aide d'anti-slashes.

Les caractéristiques de la requête en elle-même sont journalisées en insérant des directives "`%`" dans la chaîne de format, celles-ci étant remplacées dans le fichier journal par certaines valeurs comme suit :

Chaîne de format | Description
--- | ---
`%%` | Le signe "pourcentage"
`%a` | L'adresse IP distante (voir le module `mod_remoteip`).
`%{c}a` | Adresse IP distante de la connexion(voir le module `mod_remoteip`)
`%A` | L'adresse IP locale
`%B` | La taille de la réponse en octets, en excluant les en-têtes HTTP.
`%b` | La taille de la réponse en octets, en excluant les en-têtes HTTP. Au format CLF , c'est à dire un '`-`' à la place d'un 0 lorsqu'aucun octet n'est renvoyé.
`%{NOMVAR}C` | Le contenu du cookie NOMVAR dans la requête envoyée au serveur. Seuls les cookies version 0 sont pleinement supportés.
`%D` | Le temps mis à servir la requête, en microsecondes. Voir %T pour plus de détails
`%{NOMVAR}e` | Le contenu de la variable d'environnement NOMVAR
`%f` | Nom de fichier
`%h` | Serveur distant. Contiendra l'adresse IP si la directive `HostnameLookups` est définie à `Off`, ce qui est sa valeur par défaut. Si cette adresse IP n'est enregistrée que pour certains serveurs, vous avez probablement défini des directives de contrôle d'accès qui mentionnent ces derniers par leurs noms. Voir la documentation de Require host. Ce format peut être impacté par la modifications du nom d'hote distant par des modules comme `mod_remoteip`.
`%{c}h` | Semblable à `%h`, mais exploite toujours le nom d'hôte de la connection TCP sous-jacente, en ignorant toute modification réalisée sur le nom d'hôte distant par des modules tels que `mod_remoteip`.
`%H` | Le protocole de la requête
`%{NOMVAR}i` | Le contenu des lignes d'en-tête `NOMVAR:` dans la requête envoyée au serveur. Ces en-têtes sont ajoutés par d'autres modules (par exemple `mod_headers`). Si vous êtes intéressé par ce qu'était l'en-tête de la requête avant d'être modifié par la plupart des modules, utilisez `mod_setenvif` pour copier l'en-tête dans une variable d'environnement interne et journaliser sa valeur via le champ `%{VARNAME}e` décrit plus haut.
`%k` | Nombre de requêtes persistantes en cours pour cette connexion. Interessant si la directive `KeepAlive` est utilisée ; par exemple, '1' signifie la première requête après la requête initiale, '2' la seconde, etc... ; autrement, il s'agit toujours de 0 (indiquant la requête initiale).
`%l` | Le nom de connexion distant (en provenance d'identd, si disponible). Affiche un tiret, sauf si `mod_ident` est présent et si `IdentityCheck` est à `On`.
`%L` | L'identifiant du message de journalisation de la requête dans le journal des erreurs (ou '-' si aucun message n'a été enregistré dans le journal des erreurs pour cette requête). Consulter le journal d'erreurs pour voir quelle requête a généré quelle erreur.
`%{c}L` | L'identifiant du message de journalisation de la connexion dans le journal des erreurs (ou '-' si aucun message n'a été enregistré dans le journal des erreurs pour cette requête). Consulter le journal d'erreurs pour voir quelle requête a généré quelle erreur.
`%m` | La méthode de la requête
`%{NOMVAR}n` | Le contenu de la note NOMVAR en provenance d'un autre module.
`%{NOMVAR}o` | Le contenu de la ligne d'en-tête `NOMVAR:` de la réponse.
`%p` | Le port canonique du serveur servant la requête
`%{format}p` | Le port canonique du serveur servant la requête ou le véritable port du serveur ou le véritable port du client. les formats valides sont `canonical`, `local`, ou `remote`.
`%P` | Le numéro de processus du processus enfant qui a servi la requête.
`%{format}P` | Le numéro de processus ou le numéro de thread du processus enfant qui a servi la requête. Les formats valides sont `pid`, `tid`, et `hextid`.
`%q` | La chaîne d'arguments (préfixée par un `?` si une chaîne d'arguments existe, sinon une chaîne vide)
`%r` | La première ligne de la requête. Ne tient pas compte de la directive `MergeSlashes` (autrement dit, pas de fusion, même si cette dernière est à ON).
`%R` | Le gestionnaire qui génère la réponse (s'il y en a un).
`%s` | Statut. Pour les requêtes redirigées en interne, il s'agit du statut de la requête *originale* --- `%>s` pour la dernière.
`%t` | Date à laquelle la requête a été reçue (au format anglais standard)
`%{format}t` | La date, sous la forme spécifiée par format, qui devrait être au format étendu `strftime(3)` (éventuellement localisé). Si le format commence par `begin:` (valeur par défaut), la date est extraite au début du traitement de la requête ; s'il commence par `end:`, la date correspond au moment où l'entrée du journal est inscrite, par conséquent vers la fin du traitement de la requête. Hormis les formats supportés par `strftime(3)`, les formats suivants sont aussi disponibles :
`sec` | nombre de secondes depuis Epoch
`msec` | nombre de millisecondes depuis Epoch
`usec` | nombre de microsecondes depuis Epoch
`msec_frac` | fraction de milliseconde
`usec_frac` | fraction de microseconde
Ces symboles ne peuvent pas être combinés entre eux ou avec un formatage `strftime(3)` dans la même chaîne de format. Par contre, vous pouvez utiliser plusieurs symboles `%{format}t`.
`%T` | Le temps mis pour servir la requête, en secondes. Le temps commence à être mesuré au moment où la première ligne de la requête HTTP est transmise par le système d'exploitation au serveur HTTP, et se termine au moment où le dernier octet de la réponse est envoyé au système d'exploitation par le serveur HTTP. Le temps mesuré n'inclut donc aucune des rubriques suivantes : Temps passé dans les échanges TCP ou TLS. Temps écoulé avant qu'un thread du serveur web ne réussisse à lire la première ligne de la requête. Retards pris par le système d'exploitation pour renvoyer la réponse sur le réseau. Temps pris par la réponse pour arriver au système d'exploitation du client. Temps pris par le client pour lire et traiter la réponse.
`%{UNIT}T` | Le temps mis pour traiter la requête dans une unité définie par `UNIT`. Les valeurs d'unité valides sont `ms` pour millisecondes, `us` pour microsecondes et `s` pour secondes. Si `UNIT` est omis, la valeur de l'unité par défaut est la seconde ; spécifier la valeur d'unité `us` revient à utiliser le format `%D`. La possibilité de spécifier une valeur d'unité avec le format `%T` est disponible depuis la version 2.4.13 du serveur HTTP Apache.
`%u` | L'utilisateur distant (en provenance d'auth ; peut être faux si le statut de retour (`%s`) est 401).
`%U` | Le chemin de la requête, à l'exclusion de toute chaîne d'arguments. Tient compte de la directive `MergeSlashes` (autrement dit, les barres obliques sont fusionnées si cette dernière est à ON).
`%v` | Le nom canonique du serveur qui a servi la requête, défini par la directive `ServerName`.
`%V` | La nom du serveur en tenant compte de la définition de la directive `UseCanonicalName`.
`%X` | Statut de la connexion lorsque la réponse a été renvoyée :
`X` = | connexion abandonnée avant l'envoi de la réponse.
`+` = | la connexion peut rester ouverte après l'envoi de la réponse.
`-` = | la connexion sera fermée après l'envoi de la réponse.
`%I` | Le nombre d'octets reçus, en comptant la requête et les en-têtes, ne peut être nul. Nécessite l'activation de `mod_logio`.
`%O` | Nombre d'octets envoyés, y compris les en-têtes. Peut être nul dans les rares cas où une requête est avortée avant que la réponse ne soit envoyée. Nécessite l'activation de `mod_logio`.
`%S` | Nombre d'octets transmis en émission et réception y compris la requête et les en-têtes ; cette valeur ne peut pas être nulle, il s'agit de la combinaison de %I et %O. Vous devez activer `mod_logio` pour utiliser cette chaîne de format.
`%{VARNAME}^ti` | Le contenu de la variable `VARNAME:` spécifiée dans la requête envoyée au serveur.
`%{VARNAME}^to` | Le contenu de la variable `VARNAME:` spécifiée dans la réponse envoyée par le serveur.

### Modificateurs

Il est possible de restreindre l'enregistrement de certains éléments en fonction du code de statut de la réponse, en insérant une liste de codes de statut séparés par des virgules immédiatement après le caractère "%". Par exemple, `"%400,501{User-agent}i"` n'enregistrera l'en-tête `User-agent` que dans le cas d'une erreur 400 ou 501. Avec les autres codes de statut, c'est la chaîne littérale `"-"` qui sera enregistrée. La liste de codes peut être précédée d'un "`!`" pour inverser la condition : `"%!200,304,302{Referer}i"` enregistre l'en-tête `Referer` pour toutes les requêtes qui ne renvoient pas un des trois codes spécifiés.

Les modificateurs "<" et ">" peuvent être utilisés pour les requêtes qui ont été redirigées en interne afin de choisir si c'est respectivement la requête originale ou finale qui doit être consultée. Par défaut, les directives `%s, %U, %T, %D,` et `%r` consultent la requête originale, alors que toutes les autres consultent la requête finale. Ainsi, par exemple, on peut utiliser `%>s` pour enregistrer le statut final de la requête, et `%<u` pour enregistrer l'utilisateur authentifié à l'origine pour une requête redirigée en interne vers une ressource sans authentification.

### Quelques Notes

Pour des raisons de sécurité, à partir de la version 2.0.46, les caractères non imprimables et autres caractères spéciaux dans une chaîne de formatage qui peut contenir des données de chaîne arbitraires doivent être échappés à l'aide des séquences `\xhh`, où hh est le code hexadécimal du caractère spécial. Comme exceptions à cette règle, les caractères `"` et `\` doivent être échappés par un anti-slash, et tous les "blancs" doivent être écrits selon leur notation de style C (`\n`, `\t`, etc...). Avant la version 2.0.46, aucun échappement n'était effectué sur ces chaînes, et il fallait être très prudent lors de l'exploitation des journaux bruts.

Format | Description | Échappé
--- | --- | ---
`%c` | variable SSL (raccourci) | Oui
`%C` | Valeur de Cookie | Oui
`%e` | Variable d’environnement | Oui
`%f` | Nom de fichier de la requête | Oui
`%h` | Nom hôte distant | Oui
`%H` | Protocole de la requête | Oui
`%i` | En-tête de la requête | Oui
`%l` | Nom de connexion distant | Oui
`%m` | Méthode de la requête | Oui
`%n` | Note | Oui
`%o` | En-tête de la réponse | Oui
`%q` | Chaîne de paramètres | Oui
`%r` | Ligne de la requête | Oui
`%R` | Gestionnaire | Oui
`%u` | Utilisateur distant | Oui
`%U` | URI de la requête | Oui
`%v` | Nom d’hôte du serveur | Oui
`%V` | Nom canonique du serveur | Oui
`%x` | Variable SSL | Oui
`%^ti` | Données en fin de requête | Oui
`%^to` | Données en fin de réponse | Oui
`%a` | Adresse IP distante | Non (adresse IP)
`%A` | Adresse IP locale | Non (adresse IP)
`%b`, `%B` | Nombre d’octets envoyés | Non (numérique)
`%D` | Durée de la requête (microsecondes) | Non (numérique)
`%F` | Requête rejetée | Non (un seul caractère)
`%k` | Requêtes en cours | Non (numérique)
`%L` | Identifiant de connexion | Non (généré en interne)
`%p` | Port du serveur | Non (numérique)
`%P` | PID/TID | Non (numérique)
`%s` | Code d’état | Non (numérique)
`%t` | Moment de la requête | Non (temps formaté)
`%T` | Durée de la requête (secondes) | Non (numérique)
`%X` | État de la connexion | Non (un seul caractère)

`%b` et `%B` ne représentent pas le nombre d'octets envoyés au client, mais simplement la taille en octets de la réponse HTTP (les deux étant différents, par exemple, si la connexion est abandonnée, ou si SSL est utilisé). Le format `%O` fourni par `mod_logio`, enregistrera le nombre réel d'octets envoyés sur le réseau.

Note : `mod_cache` est implémenté en tant que gestionnaire basique et non en tant que gestionnaire standard. C'est pourquoi la chaîne de format `%R` ne renverra pas d'information à propos du gestionnaire lorsqu'une mise en cache de contenu entre en jeu.

Note : la présence du caractère '^' au début d'une chaîne de format de trois caractères n'a aucune incidence sur la signification de cette chaîne, mais il doit être le premier caractère de toute chaîne de format de trois caractères nouvellement créée, afin d'éviter d'éventuels conflits avec des chaînes de format qui utilisent des caractères littéraux adjacents à un spécificateur de format tel que "%Dus".

### Exemples

Quelques chaînes de format couramment utilisées :

Format de journal courant (CLF)
  `"%h %l %u %t \"%r\" %>s %b"`
Format de journal courant avec un serveur virtuel
  `"%v %h %l %u %t \"%r\" %>s %b"`
Format de journal NCSA étandu/combiné
  `"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""`
Format de journal de la page qui contient le lien vers la page concernée (Referer)
  `"%{Referer}i -> %U"`
Format de journal de l'agent (Navigateur)
  `"%{User-agent}i"`

Vous pouvez utiliser plusieurs fois la directive `%{format}t` pour construire un format de temps utilisant les symboles de format étendus tels que `msec_frac` :

Format de temps prenant en compte les milisecondes
  `"%{%d/%b/%Y %T}t.%{msec_frac}t %{%z}t"`

## Considérations concernant la sécurité ¶

Voir le document conseils à matière de sécurité pour plus de détails sur les raisons pour lesquelles votre sécurité pourrait être compromise, si le répertoire où sont stockés les fichiers journaux sont inscriptibles par tout autre utilisateur que celui qui démarre le serveur.

## Directive BufferedLogs ¶

Description: | Enregistre les entrées du journal dans un tampon en mémoire avant de les écrire sur disque
Syntaxe: | `BufferedLogs On|Off`
Défaut: | `BufferedLogs Off`
Contexte: | configuration globale
Statut: | Base
Module: | mod_log_config

Lorsque la directive `BufferedLogs` est à "on", `mod_log_config` stocke de nombreuses entrées du journal en mémoire, et les écrit d'un seul bloc sur disque, plutôt que de les écrire après chaque requête. Sur certains systèmes, ceci peut améliorer l'efficacité des accès disque, et par conséquent les performances. La directive ne peut être définie qu'une seule fois pour l'ensemble du serveur ; elle ne peut pas être définie au niveau d'un serveur virtuel.

Cette directive doit être utilisée avec précautions car un crash peut provoquer la perte de données de journalisation.

## Directive CustomLog ¶

Description: | Définit le nom et le format du fichier journal
Syntaxe: | `CustomLog fichier|pipe|provider format|alias [env=[!]variable-environnement| expr=expression]`
Contexte: | configuration globale, serveur virtuel
Statut: | Base
Module: | mod_log_config

La directive `CustomLog` permet de contrôler la journalisation des requêtes destinées au serveur. Un format de journal est spécifié, et la journalisation peut s'effectuer de manière conditionnelle en fonction des caractéristiques de la requête en utilisant des variables d'environnement.

Le premier argument, qui spécifie l'emplacement où les journaux seront écrits, accepte deux types de valeurs :

fichier
  Un nom de fichier, relatif au répertoire défini par la directive `ServerRoot`.
pipe
  Le caractère pipe "`|`", suivi du chemin vers un programme qui recevra les informations de la journalisation sur son entrée standard. Voir les notes à propos de la journalisation redirigée pour plus d'informations.

  ### Sécurité :

  Si les journaux sont redirigés vers un programme, ce dernier s'exécutera sous l'utilisateur qui a démarré `httpd`. Ce sera l'utilisateur root si le serveur a été démarré par root ; vérifiez que le programme est sécurisé.

  ### Note

  Lors de la spécification d'un chemin de fichier sur les plate-formes non-Unix, il faut prendre soin de ne pas oublier que seuls les slashes directs doivent être utilisés, même si la plate-forme autorise l'emploi d'anti-slashes. D'une manière générale, c'est une bonne idée que de n'utiliser que des slashes directs dans les fichiers de configuration.

provider
  Les messages CustomLog peuvent aussi utiliser comme cible les modules qui implémentent des fournisseurs ErrorLog. A cet effet, utilisez la syntaxe "provider:argument". Comme fournisseur, vous pouvez par exemple utiliser `mod_journald` ou `mod_syslog` :

      # Journalisation CustomLog vers journald
      CustomLog "journald" "%h %l %u %t \"%r\" %>s %b"

      # Journalisation CustomLog vers syslog avec l'option "user"
      CustomLog "syslog:user" "%h %l %u %t \"%r\" %>s %b"

Le second argument permet de définir ce qui va être écrit dans le fichier journal. Il peut contenir soit un alias prédéfini par une directive `LogFormat`, soit une chaîne de format explicite comme décrit dans la section formats de journaux.

Par exemple, les deux blocs de directives suivants produisent le même effet :

    # Journal personnalisé avec alias de format
    LogFormat "%h %l %u %t \"%r\" %>s %b" common
    CustomLog "logs/access_log" common

    # Journal personnalisé avec chaîne de format explicite
    CustomLog "logs/access_log" "%h %l %u %t \"%r\" %>s %b"

Le troisième argument est optionnel et permet de contrôler si une requête doit être ou non journalisée. Dans le cas d'une clause '`env=!nom`', la condition peut être la présence ou l'absence d'une variable particulière dans l'environnement du serveur. Dans le cas d'une clause 'expr=expression', la condition consiste en une expression booléenne quelconque. Si la condition n'est pas vérifiée, la requête ne sera pas journalisée. D'éventuelles références à des en-têtes HTTP dans l'expression rationnelle n'entraîneront pas l'ajout des noms d'en-tête correspondants à l'en-tête Vary.

Les variables d'environnement peuvent être définies au niveau de chaque requête en utilisant les modules `mod_setenvif` et/ou `mod_rewrite`. Par exemple, si vous voulez enregistrer les requêtes pour toutes les images GIF sur votre serveur dans un fichier journal séparé, et pas dans votre journal principal, vous pouvez utiliser :

    SetEnvIf Request_URI \.gif$ gif-image
    CustomLog "gif-requests.log" common env=gif-image
    CustomLog "nongif-requests.log" common env=!gif-image

Ou, pour reproduire le comportement de l'ancienne directive RefererIgnore, vous pouvez utiliser :

    SetEnvIf Referer example\.com localreferer
    CustomLog "referer.log" referer env=!localreferer

## Directive GlobalLog ¶

Description: | Définit le nom et le format du fichier journal
Syntaxe: | `GlobalLog file|pipe|provider format|nickname [env=[!]environment-variable| expr=expression]`
Contexte: | configuration globale
Statut: | Base
Module: | mod_log_config
Compatibilité: | Disponible à partir de la version 2.4.19 du serveur HTTP Apache

La directive `GlobalLog` permet de spécifier un journal partagé entre le serveur principal et tous les serveurs virtuels définis.

Elle est identique à la directive `CustomLog` à ces différences près :

- Elle n'est pas valide dans un contexte de serveur virtuel.
- A la différence d'une directive `CustomLog` définie globalement, elle est prise en compte par les serveurs virtuels qui définissent leur propre directive `CustomLog`.

## Directive LogFormat ¶

Description: | Décrit un format utilisable dans un fichier journal
Syntaxe: | `LogFormat format|alias [alias]`
Défaut: | `LogFormat "%h %l %u %t \"%r\" %>s %b"`
Contexte: | configuration globale, serveur virtuel
Statut: | Base
Module: | mod_log_config

Cette directive permet de spécifier le format du fichier journal des accès.

La directive `LogFormat` se présente sous deux formes. Sous la première forme, qui ne possède qu'un seul argument, la directive définit le format qui sera utilisé dans les journaux spécifiés par les directives `TransferLog` ultérieures. L'argument unique peut contenir un format explicite comme décrit dans la section formats de journaux personnalisés ci-dessus. Il peut aussi contenir un alias faisant référence à un format de journal prédéfini par une directive `LogFormat` comme décrit plus loin.

Sous sa seconde forme, la directive `LogFormat` associe un format explicite à un alias. Cet alias peut ensuite s'utiliser dans les directives `LogFormat` ou `CustomLog` ultérieures, ce qui évite d'avoir à répéter l'ensemble de la chaîne de format. Une directive `LogFormat` qui définit un alias ne fait rien d'autre -- c'est à dire qu'elle ne fait que définir l'alias, elle n'applique pas le format et n'en fait pas le format par défaut. Par conséquent, elle n'affecte pas les directives `TransferLog` ultérieures. En outre, la directive `LogFormat` ne peut pas utiliser un alias pour en définir un autre. Notez que l'alias ne doit pas contenir de caractère pourcent (`%`).

### Exemple

    LogFormat "%v %h %l %u %t \"%r\" %>s %b" serveur_virtuel_commun

## Directive TransferLog ¶

Description: | Spécifie l'emplacement d'un fichier journal
Syntaxe: | `TransferLog fichier|pipe`
Contexte: | configuration globale, serveur virtuel
Statut: | Base
Module: | mod_log_config

Cette directive possède exactement les mêmes arguments et produit les mêmes effets que la directive `CustomLog`, à l'exception qu'elle ne permet pas de spécifier un format de journal explicite ou la journalisation conditionnelle des requêtes. En l'occurrence, le format de journal est déterminé par la dernière définition d'une directive `LogFormat` qui ne définit pas d'alias. Si aucun format particulier n'a été spécifié, c'est le Common Log Format qui sera utilisé.

### Exemple

    LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
    TransferLog "logs/access_log"