Fichiers journaux

Vue d'ensemble

Modules Apparentés	Directives Apparentées
mod_log_config mod_log_forensic mod_logio mod_cgi

Le serveur HTTP Apache fournit toute une variété de mécanismes différents pour la journalisation de tout ce qui peut se passer au sein de votre serveur, depuis la requête initiale, en passant par le processus de mise en correspondance des URLs, et jusqu'à la fermeture de la connexion, y compris toute erreur pouvant survenir au cours du traitement. De plus, certains modules tiers fournissent des fonctionnalités de journalisation ou insèrent des entrées dans les fichiers journaux existants, et les applications comme les programmes CGI, les scripts PHP ou autres gestionnaires peuvent envoyer des messages vers le journal des erreurs du serveur.

Ce document décrit le fonctionnement des modules de journalisation fournis en standard avec le serveur httpd.

Avertissement à propos de la sécurité

Tout utilisateur qui a les droits en écriture sur le répertoire dans lequel Apache httpd é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 d'être très prudent lors de la manipulation des journaux bruts.

Journal des erreurs

Modules Apparentés	Directives Apparentées
core	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 par défaut 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 :

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.

La directive ErrorLogFormat vous permet de personnaliser le format du journal des erreurs, et de définir les informations à journaliser. Si mod_unique_id est présent, vous pouvez utiliser le drapeau %L à la fois dans le journal des erreurs et dans le journal des accès, ce qui aura pour effet de générer un identifiant d'entrée qui vous permettra de corréler les entrées du journal des erreurs avec celles du journal des accès.

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 :

Journalisation par module

La directive LogLevel permet de spécifier un niveau de sévérité de journalisation pour chaque module. Vous pouvez ainsi résoudre un problème propre à un module particulier en augmentant son volume de journalisation sans augmenter ce volume pour les autres modules. Ceci est particulièrement utile lorsque vous voulez obtenir des détails sur le fonctionnement de modules comme mod_proxy ou mod_rewrite.

Pour ce faire, vous devez spécifier le nom du module dans votre directive LogLevel :

LogLevel info rewrite:trace5

Dans cet exemple, le niveau de journalisation général est défini à info, et à trace5 pour mod_rewrite.

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 en dehors du sujet 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.

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 aussi ê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 échappées en les faisant précéder d'un anti-slash (\) afin qu'elles ne soient pas interprétées 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 :

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 la forme de celle de la fonction strftime(3) de la bibliothèque C standard, ou choisie parmi les formats spéciaux supportés. Pour plus de détails, reportez-vous aux. chaînes de format de mod_log_config.

"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 aussi 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 :

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 aisément accomplir ceci à 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 autr