original in en Egon Willighagen
en to fr Jean-Fran�ois Messier
Cet article est bas� sur la derni�re version de Lire, soit : lire-20011017. Veuillez noter que la configuration a beaucoup chang� depuis la pr�c�dente version, et que cet article est d�j� d�pass�. L'id�e g�n�rale de lr_config, toutefois, n'a pas chang�.
Parmi les nouvelles fonctionnalit�s, on retrouve: deux nouveaux super-services (FTP et firewall), de nombreux nouveaux rapports (plus de 68), de nouveaux formats de sortie (XHTML et RTF) et de nombreuses corrections. Mais le changement le plus important de cette version se trouve dans le moteur. Le processus de rapport a �t� enti�rement r��crit, afin d'utiliser la technologie XML.
Cet article pr�sentera un des formats XML utilis�s dans Lire, et comment s'en servir pour sp�cifier des rapports. Ce n'est pas un tutoriel sur la conception de rapports, mais il vous montrera comment modifier des rapports pr�d�finis en d�tail. Mais tout d'abord, cet article expliquera comment vous pouvez demander � Lire de g�n�rer les rapports et comment en sp�cifier les param�tres.
Chaque super service (ex: `email' est un super service, les services `postfix' et `sendmail' appartiennent � ce super service) poss�de un nombre de rapports disponibles, qui extraient l'information des relev�s de transaction pour vous. Le super service WWW, par exemple, poss�de 31 rapports. Tous les rapports ne sont pas int�ressants pour chacun d'entre nous. Par d�faut, la plupart de ces rapports sont s�lectionn�s, mais il est prudent de les personnaliser.
Les fichiers utilis�s dans la g�n�ration de rapports sont dans le fichier <prefix>/etc/lire/<superservice>.cfg (en supposant que Lire est install� dans le r�pertoire <prefix>). Par exemple, le fichier de configuration pour le super service FTP ressemble � ce qui suit :
# Report configuration for the FTP super service
# Top X reports
top-remote-host hosts_to_show=10
#top-files files_to_show=10
top-files-in files_to_show=10
top-files-out files_to_show=10
top-users users_to_show=10
# By day reports
bytes-by-day
# Transfers by X reports
transfers-by-direction
transfers-by-type
Le super service FTP a donc huit rapports d�finis et tous, sauf un, sont s�lectionn�s. Le "top-files" est d�s�lectionn�, en utilisant le caract�re "#". Le retrait de "#" res�lectionne le rapport.
A noter que les lignes commen�ant par "#" ne sont pas toutes des lignes de rapports. Dans ce fichier de configuration, les lignes "Report configuration for the FTP super service", "Top X reports", "By day reports" et "Transfers by X reports" sont des commentaires. Il en est de m�me pour d'autres fichiers de configuration.
Le classement est tr�s simple. L'ordre des lignes de rapports dans le fichier de configuration est l'ordre de sortie des rapports. Un changement dans cet ordre change l'ordre de sortie des rapports. Ainsi, dans l'exemple ci-dessus, "transfers-by-type" sera le dernier rapport en entr�e.
Plusieurs rapports peuvent �tre personnalis�s en partie avec les fichiers de configuration, comme expliqu� dans la pr�c�dente section. Par exemple, pour la configuration du super service DNS:
# Report configuration for the DNS super service
# Top reports
top-requesting-hosts hosts_to_show=10
top-requesting-hosts-by-method hosts_to_show=10 method='recurs'
top-requesting-hosts-by-method hosts_to_show=10 method='nonrec'
top-requested-names names_to_show=10
top-requested-names-by-method names_to_show=10 method='recurs'
top-requested-names-by-method names_to_show=10 method='nonrec'
requesttype-distribution
requesttype-distribution-by-method method='recurs'
requesttype-distribution-by-method method='nonrec'
# By Day reports
requests-by-period period=1d
requests-by-period-by-method period=1d method='recurs'
requests-by-period-by-method period=1d method='nonrec'
# By Hour reports
requests-by-period period=1h
requests-by-period-by-method period=1h method='recurs'
requests-by-period-by-method period=1h method='nonrec'
Les quinze rapports sont s�lectionn�s, mais de plus, pour les rapports ayant un Top X, le nombre X peut �tre d�fini. Avec la configuration ci-dessus, le rapport top-requesting-hosts affichera les 10 h�tes se connectant le plus fr�quemment.
Ces rapports sont g�n�r�s � partir seulement de huit sp�cifications de rapport. C'est l'utilisation des param�tres (period, method, hosts_to_show, et names_to_show) qui permet cela. C'est une des forces du nouveau moteur bas� sur XML.
Important: toutes les d�finitions de variables doivent �tre sur la m�me ligne que le nom du rapport !
Un exemple plus exotique, provient du fichier de configuration du super service WWW:
top-referers-by-page referer_to_show=5 page_to_show=10 referer_exclusion='^-$'
Dans cet exemple, une expression r�guli�re est utilis�e comme contenu de la variable referer_exclusion. Cette expression correspond � toutes les r�f�rences "-". De telles r�f�rences se retrouvent dans le relev� de transaction dans les cas par exemple, o� l'adresse web est entr�e par l'utilisateur client. (Quand des utilisateurs visitent votre page web, en cliquant sur un lien dans une page, la page de provenance figure dans le champ de r�f�rence.) Toutes les r�f�rences qui correspondent � "-" seront exclues de l'analyse.
Cette nouvelle version commence une toute nouvelle branche de Lire. La g�n�ration de rapports et le processus de sp�cification ont �t� enti�rement r��crits pour l'utilisation de la technologie XML. Les rapports sont sp�cifi�s en XML, mais la d�finition de variables est faite en format ASCII. La sp�cification de rapport pr�c�dente �tait un script Perl qui devait conna�tre � la fois le format d'entr�e et le format de sortie. Avec le nouveau format XML, l'impl�mentation est distincte de la sp�cification, et il n'est plus n�cessaire de conna�tre les formats d'entr�e et de sortie; seulement l'information � traiter.
Donc, pour personnaliser des rapports � bas niveau, il faut conna�tre un peu le XML. Un exemple de rapport, extrait du r�pertoire <prefix>/share/lire/reports/firewall :
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE lire:report-spec PUBLIC
"-//LogReport.ORG//DTD Lire Report Specification Markup Language V1.0//EN"
"http://www.logreport.org/LRSML/1.0/lrsml.dtd">
<lire:report-spec xmlns:lire="http://www.logreport.org/LRSML/"
superservice="firewall" id="bytesperfrom" charttype="bars">
<lire:title>Top Bytes per From-IP Report</lire:title>
<lire:description>
<para>
This report lists the IP addresses sending the highest data volume.
</para>
</lire:description>
<lire:param-spec>
<lire:param name="ips_to_show" type="int" default="10">
<lire:description>
<para>This parameter controls the number of sending IP adresses to
display in the report.
</para>
</lire:description>
</lire:param>
</lire:param-spec>
<lire:display-spec>
<lire:title>Volume per sending IP, Top $ips_to_show</lire:title>
</lire:display-spec>
<lire:report-calc-spec>
<lire:group sort="-rcvd_volume" limit="$ips_to_show">
<lire:field name="from_ip"/>
<lire:sum name="rcvd_volume" field="length"/>
</lire:group>
</lire:report-calc-spec>
</lire:report-spec>
Tout d'abord, il faut noter que presque chaque �l�ment XML de ce rapport commence par lire:. Ceci sert � affecter un "namespace" � cet �l�ment. Chaque �l�ment avec le namespace lire est d�fini dans le XML DTD de http://www.logreport.org/LRSML/1.0/lrsml.dtd (lien vide!) qui peut �tre visualis� � http://www.logreport.org/pub/docs/dtd/lrsml/.
Tous les autres �l�ments sont cens�s appartenir au DocBook XML 4.2 DTD. Comme l'�l�ment <para> sur la sixi�me ligne de l'exemple.
Pour changer le titre qui appara�t dans le rapport, vous devez modifier le contenu de <lire:title> dans le <lire:display-spec>. Rappelez-vous que les phrases commen�ant par "$" sont des variables Perl, o� le nom correspond � un des param�tres sp�cifi�s dans la section <lire:param-spec>.
La chose la plus d�licate, c'est d'utiliser le bon �l�ment <lire:title>. Vous avez besoin de l'�l�ment qui est le contenu du noeud <lire:display-spec>. Ce dernier contient l'information � afficher dans le rapport. Le premier �l�ment <lire:title> contient le titre du rapport utilis� dans la documentation du logiciel Lire.
L'exemple suivant montre un fragment des sp�cifications du rapport de WWW requests-by-result. On peut voir que le <lire:display-spec> affiche maintenant non seulement un titre, mais aussi d'autres explications. A noter que tout le contenu de l'�l�ment <lire:description> n'utilise pas le namespace lire et c'est donc un contenu DocBook.
<lire:display-spec>
<lire:title>Requests By HTTP Result</lire:title>
<lire:description>
<para>
The most common HTTP status codes are given below:
<variablelist>
<varlistentry>
<term>200</term>
<listitem>
<para>OK (The request has succeeded.)</para>
</listitem>
</varlistentry>
<!-- rest is cut out -->
</variablelist>
</para>
</lire:description>
</lire:display-spec>
Voici un exemple (partiel) du r�sultat de ce rapport:
Requests By HTTP Result
The most common HTTP status codes are given below:
200 OK (The request has succeeded.)
201 Created (The request has been fulfilled and resulted in a new resource being created.)
206 Partial Content (The server has fulfilled the
La plupart des rapports ont des graphiques associ�s aux donn�es. Ces images sont g�n�r�es � partir des donn�es et les sp�cifications du rapport d�finissent aussi le format de g�n�ration de l'image. Prenons par exemple, l'extrait suivant du rapport FTP transfers-by-type.
Pour ce rapport, les donn�es sont visualis�es sous forme de camembert comme le montre l'attribut @charttype dans le code ci-dessus. Le r�sultat ressemble � :
En changeant le type de graphe par bars comme dans 'charttype="bars" le r�sultat devient:
Il est � noter que le titre du rapport contient un bogue. Le rapport est sur le type de transfert, et non pas sur le type de fichier. Ce bogue a �t� d�j� signal�.
Une information plus d�taill�e sur le langage XML utilis� dans la sp�cification de rapport peut �tre trouv�e sur le site web de LogReport. Vous verrez que le langage est tr�s �tendu, et pour l'instant je peux recommander d'utiliser les sp�cifications de rapport disponibles dans la distribution comme guide principal.
Les �l�ments qui n'ont pas �t� couverts dans cet article, mais utilis�s dans ces rapports, sont destin�s � la sp�cification des param�tres (<lire:param-spec>) et au calcul des donn�es produites (<lire:report-calc-spec>). Plus pr�cis�ment, ce dernier a plusieurs options et utilise une connaissance pr�alable du format interne (nomm� DLF) o� les donn�es de relev� sont stock�es. Nous expliquerons ceci dans un futur article.
Cet article a pr�sent� le moteur de g�n�ration de rapports bas� sur le XML et expliqu� comment vous pouvez personnaliser les rapports obtenus. De plus amples informations sont disponibles sur le site web de LogReport : http://www.logreport.org/.
Pour contacter l'�quipe de LogReport, vous pouvez joindre l'IRC. Les d�veloppeurs se retrouvent souvent sur le canal #logreport du site OpenProjects.org IRC network. Les questions, commentaires et demandes d'aide sont les bienvenus. Si vous pr�f�rez utiliser le courrier �lectronique, vous pouvez contacter l'�quipe sur la liste de diffusion publique questions@logreport.org.