Serveur Apache HTTP Version 2.2

Apache > Serveur HTTP > Documentation > Version 2.2

# Fichiers journaux

Langues Disponibles: en | fr | ja | ko | tr

Pour véritablement gérer un serveur web, il est nécessaire de disposer d'un retour d'informations à propos de l'activité et des performances du serveur, ainsi que de tout problème qui pourrait survenir. Le serveur HTTP Apache propose des fonctionnalités de journalisation souples et très complètes. Ce document décrit comment configurer ces fonctionnalités de journalisation et interpréter le contenu des journaux.

## Avertissement à propos de la sécurité

Tout utilisateur qui dispose de droits en écriture sur le répertoire dans lequel Apache écrit ses journaux pourra quasi certainement avoir accès à l'uid sous lequel le serveur est démarré, en l'occurrence habituellement root. N'accordez PAS aux utilisateurs l'accès en écriture au répertoire dans lequel les journaux sont stockés sans savoir exactement quelles en seraient les conséquences ; voir le document conseils sur la sécurité pour plus de détails.

En outre, les journaux peuvent contenir des informations fournies directement par un client, sans caractères d'échappement. Des clients mal intentionnés peuvent donc insérer des caractères de contrôle dans les journaux, et il convient par conséquent être très prudent lors de la manipulation des journaux bruts.

## Journal des erreurs

Modules Apparentés | Directives Apparentées
--- | ---

- `ErrorLog`
- `LogLevel`

Le journal des erreurs du serveur, dont le nom et la localisation sont définis par la directive `ErrorLog`, est le journal le plus important. C'est dans celui-ci que le démon Apache httpd va envoyer les informations de diagnostic et enregistrer toutes les erreurs qui surviennent lors du traitement des requêtes. Lorsqu'un problème survient au démarrage du serveur ou pendant son fonctionnement, la première chose à faire est de regarder dans ce journal, car il vous renseignera souvent sur le problème rencontré et la manière d'y remédier.

Le journal des erreurs est habituellement enregistré dans un fichier (en général `error_log` sur les systèmes de type Unix et `error.log` sur Windows et OS/2). Sur les systèmes de type Unix, le serveur peut aussi enregistrer ses erreurs dans `syslog` ou les rediriger vers un programme par l'intermédiaire d'un tube de communication (pipe).

Le format du journal des erreurs est descriptif et de forme relativement libre. Certaines informations apparaissent cependant dans la plupart des entrées du journal. Voici un message typique à titre d'exemple :

`[Wed Oct 11 14:32:52 2000] [error] [client 127.0.0.1] client denied by server configuration: /export/home/live/ap/htdocs/test`

Le premier champ de l'entrée du journal est la date et l'heure du message. Le second champ indique la sévérité de l'erreur rapportée. La directive `LogLevel` permet de restreindre le type des erreurs qui doivent être enregistrées dans le journal des erreurs en définissant leur niveau de sévérité. Le troisième champ contient l'adresse IP du client qui a généré l'erreur. Vient ensuite le message proprement dit, qui indique dans ce cas que le serveur a été configuré pour interdire l'accès au client. Le serveur indique le chemin système du document requis (et non son chemin web).

Une grande variété de messages différents peuvent apparaître dans le journal des erreurs. La plupart d'entre eux sont similaires à l'exemple ci-dessus. Le journal des erreurs peut aussi contenir des informations de débogage en provenance de scripts CGI. Toute information qu'un script CGI écrit sur la sortie d'erreurs standard `stderr` sera recopiée telle quelle dans le journal des erreurs.

Il n'est pas possible de personnaliser le journal des erreurs en ajoutant ou en supprimant des informations. Cependant, les entrées du journal des erreurs qui concernent certaines requêtes possèdent des entrées correspondantes dans le journal des accès. Ainsi, l'entrée de l'exemple ci-dessus correspond à une entrée du journal des accès avec un code de statut 403. Etant donné qu'il est possible de personnaliser le journal des accès, vous pouvez obtenir d'avantage d'informations sur les circonstances d'une erreur en consultant ce journal.

Pendant la phase de test, il est souvent utile de visualiser en continu le journal des erreurs afin de détecter tout problème éventuel. Sur les systèmes de type Unix, ceci s'effectue à l'aide de la commande :

`tail -f error_log`

## Journal des accès

Modules Apparentés | Directives Apparentées
--- | ---

- `mod_log_config`
- `mod_setenvif`

- `CustomLog`
- `LogFormat`
- `SetEnvIf`

Le journal des accès au serveur enregistre toutes les requêtes que traite ce dernier. La localisation et le contenu du journal des accès sont définis par la directive `CustomLog`. La directive `LogFormat` permet de simplifier la sélection du contenu du journal. Cette section décrit comment configurer le serveur pour l'enregistrement des informations dans le journal des accès.

Bien évidemment, le stockage d'informations dans le journal des accès n'est que le point de départ de la gestion de la journalisation. L'étape suivante consiste à analyser ces informations de façon à pouvoir en extraire des statistiques utiles. L'analyse de journaux en général est hors du cadre de ce document et ne fait pas vraiment partie intégrante du travail du serveur web lui-même. Pour plus d'informations à propos de ce sujet et des applications dédiées à l'analyse de journaux, vous pouvez vous référer à Open Directory ou Yahoo.

Différentes versions du démon Apache httpd utilisaient d'autres modules et directives pour contrôler la journalisation des accès, à l'instar de mod_log_referer, mod_log_agent, et de la directive `TransferLog`. La directive `CustomLog` rassemble désormais les fonctionnalités de toutes les anciennes directives.

Le format du journal des accès est hautement configurable. Il est défini à l'aide d'une chaîne de format qui ressemble sensiblement à la chaîne de format de style langage C de printf(1). Vous trouverez quelques exemples dans les sections suivantes. Pour une liste exhaustive de ce que peut contenir une chaîne de format, vous pouvez vous référer au chapitre chaînes de format de la documentation du module `mod_log_config`.

### Format habituel du journal

Voici une configuration typique pour le journal des accès :

`LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common`

Ici est définie l'identité `common` qui est ensuite associée à une chaîne de format de journalisation particulière. La chaîne de format est constituée de directives débutant par le caractère %, chacune d'entre elles indiquant au serveur d'enregistrer un élément particulier d'information. Des caractères littéraux peuvent également être insérés dans la chaîne de format ; il seront copiés tels quels dans le flux de sortie destiné à la journalisation. Les guillemets (`"`) doivent être protégées en les faisant précéder d'un anti-slash (`\`) afin qu'ils ne soient pas interprétés comme la fin de la chaîne de format. La chaîne de format peut aussi contenir les caractères de contrôle spéciaux "`\n`" et "`\t`" pour insérer respectivement un passage à la ligne et une tabulation.

La directive `CustomLog` définit un nouveau fichier journal en l'associant à l'identité précédemment définie. Le chemin du nom de fichier associé au journal des accès est relatif au chemin défini par la directive `ServerRoot`, sauf s'il débute par un slash.

La configuration ci-dessus va enregistrer les entrées de journalisation selon un format connu sous le nom de Common Log Format (CLF) pour "Format de journalisation standard". Ce format standard peut être produit par de nombreux serveurs web différents et lu par de nombreux programmes d'analyse de journaux. Les entrées de fichier journal générées selon le format CLF ressemblent à ceci :

`127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326`

Chaque partie de cette entrée de journal est décrite dans ce qui suit.

`127.0.0.1` (`%h`)
  Il s'agit de l'adresse IP du client (l'hôte distant) qui a envoyé la requête au serveur. Si la directive `HostnameLookups` est positionnée à `On`, le serveur va essayer de déterminer le nom de l'hôte et de l'enregistrer à la place de l'adresse IP. Cette configuration n'est cependant pas recommandée car elle peut ralentir le serveur de manière significative. Il est par conséquent préférable d'utiliser un processeur d'analyse de journaux a posteriori tel que `logresolve` pour déterminer les noms d'hôte. L'adresse IP indiquée ici n'est pas nécessairement l'adresse IP de la machine devant laquelle se trouve l'utilisateur. Si un serveur mandataire s'intercale entre le serveur et l'utilisateur, l'adresse indiquée sera celle du mandataire et non celle de la machine à l'origine de la requête.
`-` (`%l`)
  Le "trait d'union" indique que la portion d'information correspondante n'est pas disponible. Dans le cas présent, l'information non disponible est l'identité (RFC 1413) du client telle que déterminée par `identd` sur la machine cliente. Cette information est très peu fiable et ne devrait jamais être utilisée, sauf dans le cas de réseaux internes étroitement contrôlés. Le démon httpd ne cherchera d'ailleurs à obtenir cette information que si la directive `IdentityCheck` est positionnée à `On`.
`frank` (`%u`)
  Il s'agit de l'identifiant utilisateur de la personne qui a demandé le document, issu d'une authentification HTTP. Ce même identifiant est en général fourni aux scripts CGI par l'intermédiaire de la valeur de la variable d'environnement `REMOTE_USER`. Si le statut de la requête (voir plus loin) est 401, cette identifiant n'est pas fiable car l'utilisateur n'est pas encore authentifié. Si le document n'est pas protégé par mot de passe, cette partie d'information sera représentée par "`-`", comme la partie précédente.
`[10/Oct/2000:13:55:36 -0700]` (`%t`)
  L'heure à laquelle la requête a été reçue. Le format est le suivant :

  `[jour/mois/année:heure:minutes:secondes zone]
  jour = 2*chiffre
  mois = 3*lettre
  année = 4*chiffre
  heure = 2*chiffre
  minutes = 2*chiffre
  secondes = 2*chiffre
  zone = (`+' | `-') 4*chiffre`

  Il est possible de modifier le format d'affichage de l'heure en spécifiant `%{format}t` dans la chaîne de format du journal, où `format` est une chaîne de format de même forme que celle de la fonction `strftime(3)` de la bibliothèque C standard.
`"GET /apache_pb.gif HTTP/1.0"` (`\"%r\"`)
  La ligne de la requête du client est placée entre guillemets. Elle contient de nombreuses informations utiles. Tout d'abord, la méthode utilisée par le client est `GET`. Ensuite, le client a demandé la ressource `/apache_pb.gif`, et enfin, le client a utilisé le protocole `HTTP/1.0`. Il est également possible d'enregistrer séparément une ou plusieurs parties de la requête. Par exemple, la chaîne de format "`%m %U %q %H`" va enregistrer la méthode, le chemin, la chaîne de la requête et le protocole, ce qui donnera le même résultat que "`%r`".
`200` (`%>s`)
  C'est le code de statut que le serveur retourne au client. Cette information est très importante car elle indique si la requête a fait l'objet d'une réponse positive (codes commençant par 2), une redirection (codes commençant par 3), une erreur due au client (codes commençant par 4), ou une erreur due au serveur (codes commençant par 5). Vous trouverez la liste complète des codes de statut possibles dans la specification HTTP (RFC2616 section 10).
`2326` (`%b`)
  La dernière partie indique la taille de l'objet retourné au client, en-têtes non compris. Si aucun contenu n'a été retourné au client, cette partie contiendra "`-`". Pour indiquer l'absence de contenu par "`0`", utilisez `%B` au lieu de `%b`.

### Combined Log Format (Format de journalisation combiné)

Une autre chaîne de format couramment utilisée est le "Combined Log Format" (Format de journalisation combiné). Il s'utilise comme suit :

`LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" combined
CustomLog log/access_log combined`

Ce format est identique au Common Log Format, avec deux champs supplémentaires. Chacun de ces deux champs utilise la directive commençant par le caractère "%" `%{header}i`, où header peut être n'importe quel en-tête de requête HTTP. Avec ce format, le journal des accès se présentera comme suit :

`127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326 "http://www.example.com/start.html" "Mozilla/4.08 [en] (Win98; I ;Nav)"`

Les champs supplémentaires sont :

`"http://www.example.com/start.html"` (`\"%{Referer}i\"`)
  L'en-tête "Referer" (sic) de la requête HTTP. Il indique le site depuis lequel le client prétend avoir lancé sa requête. (Ce doit être la page qui contient un lien vers `/apache_pb.gif` ou inclut ce dernier fichier).
`"Mozilla/4.08 [en] (Win98; I ;Nav)"` (`\"%{User-agent}i\"`)
  L'en-tête User-Agent de la requête HTTP. C'est une information d'identification que le navigateur du client envoie à propos de lui-même.

### Journaux d'accès multiples

Plusieurs journaux d'accès peuvent être créés en spécifiant tout simplement plusieurs directives `CustomLog` dans le fichier de configuration. Par exemple, les directives suivantes vont créer trois journaux d'accès. Le premier contiendra les informations de base CLF, le second les informations du Referer, et le troisième les informations sur le navigateur. Les deux dernières directives `CustomLog` montrent comment simuler les effets des directives `ReferLog` et `AgentLog`.

`LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common
CustomLog logs/referer_log "%{Referer}i -> %U"
CustomLog logs/agent_log "%{User-agent}i"`

Cet exemple montre aussi qu'il n'est pas obligatoire d'associer une chaîne de format à un alias au moyen de la directive `LogFormat`. Elle peut être définie directement dans la ligne de la directive `CustomLog`.

### Journalisation conditionnelle

Il est parfois souhaitable d'exclure certaines entrées des journaux d'accès en fonction des caractéristiques de la requête du client. On peut facilement y parvenir à l'aide des variables d'environnement. Tout d'abord, une variable d'environnement doit être définie pour indiquer que la requête remplit certaines conditions. Pour ceci, on utilise en général la directive `SetEnvIf`, puis la clause `env=` de la directive `CustomLog` pour inclure ou exclure les requêtes pour lesquelles la variable d'environnement est définie. Quelques exemples :

`# Marque les requêtes en provenance de l'interface loop-back
SetEnvIf Remote_Addr "127\.0\.0\.1" dontlog
# Marque les requêtes pour le fichier robots.txt
SetEnvIf Request_URI "^/robots\.txt$" dontlog
# Journalise toutes les autres requêtes
CustomLog logs/access_log common env=!dontlog`

Autre exemple, imaginons l'enregistrement des requêtes en provenance d'utilisateurs de langue anglaise dans un journal, et celles des autres utilisateurs dans un autre journal.

`SetEnvIf Accept-Language "en" english
CustomLog logs/english_log common env=english
CustomLog logs/non_english_log common env=!english`

Bien que nous venions de montrer que la journalisation conditionnelle est souple et très puissante, cette méthode de contrôle du contenu des journaux n'est pas la seule. Les fichiers journaux sont plus utiles quand ils contiennent un enregistrement complet de l'activité du serveur, et il est souvent plus aisé de simplement traiter a posteriori les fichiers journaux pour supprimer les requêtes que vous ne voulez pas y voir apparaître.

## Rotation des journaux

Même dans le cas d'un serveur modérément sollicité, la quantité d'informations stockées dans les fichiers journaux est très importante. Le fichier journal des accès grossit en général d'1 Mo ou plus toutes les 10000 requêtes. Il est par conséquent nécessaire d'effectuer périodiquement la rotation des journaux en déplaçant ou supprimant les fichiers correspondants. On ne peut pas le faire pendant que le serveur est en cours d'exécution, car Apache va continuer à écrire dans l'ancien fichier journal aussi longtemps qu'il le maintiendra ouvert. C'est pourquoi le serveur doit être redémarré après le déplacement ou la suppression des fichiers journaux de façon à ce qu'il en ouvre de nouveaux.

Avec un redémarrage graceful, on peut faire en sorte que le serveur ouvre de nouveaux fichiers journaux sans perdre de connexions existantes ou en cours avec les clients. Cependant, pour que ceci soit possible, le serveur doit continuer à écrire dans les anciens fichiers journaux pendant qu'il termine le traitement des requêtes en cours. Il est donc nécessaire d'attendre un certain temps après le rédémarrage avant d'effectuer tout traitement sur les fichiers journaux. Voici un scénario typique dans lequel on effectue une simple rotation des journaux en compressant les anciens fichiers correspondants afin de gagner de l'espace disque :

`mv access_log access_log.old
mv error_log error_log.old
apachectl graceful
sleep 600
gzip access_log.old error_log.old`

La section suivante présente une autre méthode de rotation des journaux qui consiste à utiliser les journaux redirigés.

## Journaux redirigés

Nous avons vu que le démon httpd écrivait les informations de journalisation des erreurs et des accès dans un fichier journal ; il peut également rediriger ces informations vers un autre processus par l'intermédiaire d'un tube de communication (pipe). Cette fonctionnalité améliore considérablement la souplesse de la journalisation, sans ajouter de code au serveur principal. Pour rediriger les informations de journalisation vers un tube de communication, remplacez simplement le nom de fichier journal par le caractère pipe "`|`", suivi du nom de l'exécutable qui va recueillir les entrées de journal sur son entrée standard. Apache va lancer le processus de redirection des journaux au moment du démarrage du serveur, et le relancera s'il cesse de fonctionner pendant l'exécution du serveur. (Nous dénommons cette technique "journalisation redirigée fiable" grâce à cette dernière fonctionnalité.)

Les processus de journalisation redirigée sont lancés par le processus httpd parent, et héritent de l'UID de ce dernier. Cela signifie que les programmes de journalisation dirigée s'exécutent généralement en tant que root. Il est donc très important que ces programmes soient simples et sécurisés.

Un des grands avantages de la journalisation redirigée est la possibilité d'effectuer la rotation des journaux sans avoir à redémarrer le serveur. Pour accomplir cette tâche, le serveur HTTP Apache fournit un programme simple appelé `rotatelogs`. Par exemple, pour une rotation des journaux toutes les 24 heures, ajoutez ces lignes :

`CustomLog "|/usr/local/apache/bin/rotatelogs /var/log/access_log 86400" common`

Notez que l'ensemble de la commande qui sera appelée par le tube de communication a été placée entre guillemets. Cet exemple concerne le journal des accès, mais la même technique peut être utilisée pour le journal des erreurs.

Il existe un autre programme de rotation des journaux similaire mais beaucoup plus souple : il s'agit de "cronolog", non fourni par Apache, mais disponible ici.

Comme la journalisation conditionnelle, la journalisation redirigée est un outil très puissant, mais si elle existe, il est préférable d'utiliser une solution plus simple comme le traitement a posteriori hors ligne.

Par défaut, le processus de redirection du journal est lancé en invoquant un shell(en général avec `/bin/sh -c`). Selon les spécificités du shell, l'invocation via un shell peut générer un processus shell supplémentaire pour toute la durée du programme de redirection du journal, et induire des problèmes de gestion de signaux au cours du redémarrage.

Pour lancer le programme sans invoquer un shell, utilisez "`||`" au lieu de "`|`" :

`# Invocation de "rotatelogs" sans utiliser de shell
CustomLog "||/usr/local/apache/bin/rotatelogs /var/log/access_log 86400" common`

## Hôtes virtuels

Lorsqu'un serveur possède plusieurs hôtes virtuels, il existe de nombreuses solutions pour gérer les fichiers journaux. Par exemple, on peut utiliser les journaux comme s'il s'agissait d'un serveur avec un seul hôte. Il suffit pour cela de placer les directives de journalisation en dehors des sections `<VirtualHost>` au niveau du serveur principal, ce qui a pour effet de journaliser toutes les requêtes dans le même journal des accès et des erreurs. Cette technique est cependant inappropriée pour recueillir des statistiques sur chaque hôte virtuel individuellement.

Si des directives `CustomLog` ou `ErrorLog` sont placées dans une section `<VirtualHost>`, toutes les requêtes ou erreurs pour cet hôte virtuel ne seront enregistrées que dans le fichier spécifié. Tout hôte virtuel qui ne possède pas de directives de journalisation verra ses requêtes enregistrées dans le journal du serveur principal. Cette technique est appropriée pour un petit nombre d'hôtes virtuels, mais si ce nombre est important, elle peut devenir compliquée à gérer. En outre, des problèmes de nombre de descripteurs de fichiers insuffisant peuvent rapidement apparaître.

Il existe un très bon compromis pour le journal des accès. En intégrant les informations à propos de l'hôte virtuel à la chaîne de format du journal, il est possible de journaliser tous les hôtes dans le même journal, puis de séparer ultérieurement le journal en plusieurs journaux individuels. Considérons par exemple les directives suivantes :

`LogFormat "%v %l %u %t \"%r\" %>s %b" comonvhost
CustomLog logs/access_log comonvhost`

Le champ `%v` sert à enregistrer le nom de l'hôte virtuel qui traite la requête. Un programme tel que split-logfile peut ensuite être utilisé pour générer "à froid" autant de journaux que d'hôtes virtuels.

## Autres fichiers journaux

Modules Apparentés | Directives Apparentées
--- | ---

- `mod_logio`
- `mod_log_forensic`
- `mod_cgi`
- `mod_rewrite`
- `mod_log_config`

- `LogFormat`
- `BufferedLogs`
- `ForensicLog`
- `PidFile`
- `RewriteLog`
- `RewriteLogLevel`
- `ScriptLog`
- `ScriptLogBuffer`
- `ScriptLogLength`

### Enregistrement du nombre réel d'octets envoyés et reçus

Le module `mod_logio` fournit deux champs `LogFormat` supplémentaires (%I et %O) qui permettent d'enregistrer le nombre réel d'octets reçus et envoyés sur le réseau.

### Journalisation de style investigation judiciaire (forensic logging)

Le module `mod_log_forensic` permet la journalisation à des fins d'investigation judiciaire des requêtes des clients. La journalisation est effectuée avant et après le traitement de la requête, qui fait donc l'objet de deux entrées dans le journal. Le générateur de journaux d'investigation est très strict et ne permet aucune personnalisation. C'est un inestimable outil de débogage et de sécurité.

### Fichier PID

Au démarrage, le démon httpd Apache enregistre l'identifiant du processus httpd parent dans le fichier `logs/httpd.pid`. Le nom de ce fichier peut être modifié à l'aide de la directive `PidFile`. Cet identifiant permet à l'administrateur de redémarrer et arrêter le démon en envoyant des signaux au processus parent ; sous Windows, vous devez utiliser l'option de ligne de commande -k. Pour plus de détails, consulter la page Arrêt et redémarrage.

### Journal des scripts

Afin de faciliter le débogage, la directive `ScriptLog` vous permet d'enregistrer les entrées et sorties des scripts CGI. Elle ne doit être utilisée que pendant la phase de test, et en aucun cas sur un serveur en production. Vous trouverez plus d'informations dans la documentation du module mod_cgi.

### Journal de réécriture

Lorsqu'on utilise les fonctionnalités puissantes et complexes du module mod_rewrite, il est presque toujours nécessaire d'utiliser la directive `RewriteLog` afin de faciliter le débogage. Ce fichier journal fournit une analyse détaillée de la transformation des requêtes par le moteur de réécriture. Le niveau de détail est contrôlé par la directive `RewriteLogLevel`.

Langues Disponibles: en | fr | ja | ko | tr