<html><head>
<!-- lfparser will add this: -->
<style type="text/css">
p.code { width:80%; alignment:center; background-color:#aedbe8; border-style:none; border-width:medium; border-color:#aedbe8; padding:0.1cm ; text-align:left }
</style>
</head><body>
<h1>Het analyseren van de logbestanden van je internetapplicaties II -
het configureren van je rapporten</h1>
<h4>ArticleCategory:</h4>
Applications
<h4>AuthorImage:</h4>
<img src="../../common/images/EgonWillighagen.jpg" alt="Foto van Egon" width="79" height="102">
<h4>TranslationInfo:</h4>
<p>original in en <a href="mailto:egonw@logreport.org">Egon Willighagen</a></p>
<p>en to nl <a href="mailto:hjh@passys.nl">Hendrik-Jan Heins</a></p>
<h4>AboutTheAuthor:</h4>
<p>Naast zijn werk voor het LinuxFocus-project, werkte Egon voor de Stichting
Logreport tot de eerste november van dit jaar. Een deel van het doel van de
stichting was het schrijven van software voor loganalyse met een GPL-licentie.</p>
<h4>Abstract:</h4>
<p>Dit artikel is het tweede in een serie over het gebruik van Lire om logbestanden
van internet-serverapplicaties te analyseren. Dit artikel laat je zien hoe je de
gegenereerde rapporten kunt aanpassen aan je eigen voorkeuren. Het
<a href="../September2001/article213.shtml">
eerste artikel</a> uit deze serie legt uit hoe Lire moet worden geïnstalleerd.</p>
<h4>ArticleIllustration:</h4>
<img src="../../common/images/illustration213.png" width="300" height="65" alt="[illustration]">
<h4>ArticleBody:</h4>
<h2>Inleiding</h2>
<p>Dit artikel is gebaseerd op de laatste release van Lire, op dit moment is dat
<a href="http://www.logreport.org/">lire-20011017</a>.
Let erop dat de configuratie erg veranderd is sinds de vorige uitgave en dat in
feite het eerste artikel uit de serie nu al verouderd is. Het idee van lr_config
is echter niet veranderd.
</p>
<p>Nieuwe features in deze release zijn, onder andere: twee nieuwe superservices
(FTP en firewall), veel nieuwe rapporten (totaal > 68), nieuwe opmaakmethoden voor uitvoer
(XHTML en RTF) en een heleboel bugfixes. Maar de belangrijkste verandering in deze
uitgave zit onder de motorkap. Het rapport-generatieproces is compleet herschreven
om gebruik te kunnen maken van XML technologie.</p>
<p>Dit artikel zal een van de XML-opmaakmethoden die nu in Lire gebruikt worden introduceren en
uitleggen hoe deze gebruikt kunnen worden om rapporten te specificeren. Het zal geen handboek zijn
over het maken van nieuwe rapporten maar het zal je laten zien hoe je de voorgedefiniëerde
rapporten kunt veranderen op een laag niveau. Maar allereerst zal dit artikel uitleggen
hoe je Lire kunt vertellen welke rapporten hij moet genereren en hoe de parameters voor
deze rapporten moeten worden ingesteld.</p>
<h2>Rapporten selecteren</h2>
<p>Iedere <i>superservice</i> (bijvoorbeeld `email' is een <i>superservice</i>,
de `postfix' en `sendmail' <i>services</i> behoren tot deze <i>super service</i>)
heeft een aantal rapporten beschikbaar die extra informatie voor je uit de logs
halen. De www superservice heeft bijvoorbeeld 31 rapporten. Niet alle rapporten
zijn interresant voor iedereen; sommige zijn erg specifiek. Standaard worden de
meeste van deze rapporten geselecteerd, maar het is handig om dit in te stellen
naar je eigen wensen.</p>
<p>De rapporten die zullen worden gebruikt bij het genereren van een rapport worden
ingesteld in het bestand <prefix>/etc/lire/<superservice>.cfg (aangenomen
dat Lire geïnstalleerd is de directory <prefix>).
Voor de FTP superservice bijvoorbeeld ziet het configuratiebestand er als volgt
uit:</p>
<p class="code">
# Report configuration for the FTP super service<br>
<br>
# Top X reports<br>
top-remote-host hosts_to_show=10<br>
#top-files files_to_show=10<br>
top-files-in files_to_show=10<br>
top-files-out files_to_show=10<br>
top-users users_to_show=10<br>
<br>
# By day reports<br>
bytes-by-day<br>
<br>
# Transfers by X reports<br>
transfers-by-direction<br>
transfers-by-type</p>
<p>De FTP-superservice heeft dus acht rapporten gedefiniëerd en alle behalve één
zijn geselecteerd. De "top-files" wordt gedeselecteerd door gebruik te maken van
het karakter "#". Het verwijderen van het karakter "#" zal het rapport opnieuw
selecteren.</p>
<p>Let erop dat niet alle regels die beginnen met een "#" rapporten zijn. In dit
configuratiebestand zijn de regels "Report configuration for the FTP super service",
"Top X reports", "By day reports" en "Transfers by X reports" commentaar.
Gelijkaardig commentaar kan je ook tegenkomen in de andere configuratiebestanden.</p>
<h2>Rapporten sorteren</h2>
<p>Ordenen is zeer eenvoudig. De volgorde waarin de rapportregels verschijnen in de
configuratiebestanden is ook de volgorde waarin de rapporten zullen worden weergegeven
in de uitvoer. Het herschikken van de regels in deze configuratiebestanden zal ze dus
ook herordenen in de uitvoer. Bijvoorbeeld, in het bovenstaande voorbeeld zullen de
'transfers-by-type' als laatste worden weergegeven.</p>
<h2>Rapporten aanpassen aan de eigen wensen</h2>
<p>Veel rapporten kunnen gedeeltelijk worden aangepast aan de eigen wensen met de configuratiebestanden.
Dit gaat zoals in het voorgaande deel is uitgelegd. Bijvoorbeeld deze DNS-superservice-configuratie:</p>
<p class="code"># Rapport configuratie voor de DNS-superservice<br>
<br>
# Top reports<br>
top-requesting-hosts hosts_to_show=10<br>
top-requesting-hosts-by-method hosts_to_show=10 method='recurs'<br>
top-requesting-hosts-by-method hosts_to_show=10 method='nonrec'<br>
top-requested-names names_to_show=10<br>
top-requested-names-by-method names_to_show=10 method='recurs'<br>
top-requested-names-by-method names_to_show=10 method='nonrec'<br>
requesttype-distribution<br>
requesttype-distribution-by-method method='recurs'<br>
requesttype-distribution-by-method method='nonrec'<br>
<br>
# By Day reports<br>
requests-by-period period=1d<br>
requests-by-period-by-method period=1d method='recurs'<br>
requests-by-period-by-method period=1d method='nonrec'<br>
<br>
# By Hour reports<br>
requests-by-period period=1h<br>
requests-by-period-by-method period=1h method='recurs'<br>
requests-by-period-by-method period=1h method='nonrec'</p>
<p>Alle vijftien rapporten zijn geselecteerd, maar bovendien is het voor de rapporten
met een top X output mogelijk het nummer X te definiëren. Met de bovenstaande configuratie
geeft het rapport <i>top-requesting-hosts</i> een Top 10.</p>
<p>Deze rapporten worden gegenereerd uit slechts acht rapportspecificaties.
Het gebruik van de parameters (<i>period</i>, <i>method</i>, <i>hosts_to_show</i>,
en <i>names_to_show</i>) maakt dit mogelijk. Dit is een van de nieuwe krachtige eigenschappen
van de nieuwe, op XML gebaseerde motor.</p>
<p><b>Belangrijk: alle instellingen van variabelen moeten op dezelfde regel worden geplaatst als de
rapportnaam!</b></p>
<p>Een meer exotisch voorbeeld kan gegeven worden aan de hand van het
WWW-superservice-configuratiebestand:</p>
<p class="code">top-referers-by-page referer_to_show=5 page_to_show=10 referer_exclusion='^-$'</p>
<p>In dit voobeeld wordt een Perl <a href="../July1998/article53.html">
reguliere expressie</a> gebruikt als inhoud voor de <i>referer_exclusion</i>-variabele. Deze expressie
komt overeen met alle referers "-". Zulke referers kunnen worden gevonden in het logbestand
in gevallen waarbij bijvoorbeeld de URL van een web pagina is ingetikt door de gebruiker.
(Wanneer gebruikers je pagina bezoeken door op een link in een pagina te klikken die doorverwijst naar
je pagina, dan wordt de pagina waar de link vandaan komt gegeven in het refererveld.) Alle referers die
hetzelfde zijn als "-" worden uit de analyse gehouden.</p>
<h2>Rapporten aanpassen op laag niveau</h2>
<p>Deze nieuwe uitgave is het begin van een heel nieuwe tak van Lire. De rapportgeneratie en de
specificatieprocessen zijn compleet herschreven om gebruik te kunnen maken van XML-technologie.
Rapporten worden
gespecificeerd in XML, maar de instelling van de variabelen werkt in gewoon ASCII-formaat. De vorige
rapportspecificatie was een Perl-script dat zowel de opmaak van de invoer als die van de uitvoer moest kennen.
Met de nieuwe XML-opmaak is de implementatie gescheiden van de specificatie en hoef je niet meer zowel
de invoer- als de uitvoeropmaak te kennen maar alleen de gegevens die verwerkt kunnen worden.</p>
<p>Dus, als je rapporten op laag niveau aanpast,
hoef je allen maar een beetje XML te kennen. Een voorbeeldrapport, genomen uit de
<prefix>/share/lire/reports/firewall directory:</p>
<p class="code"><?xml version="1.0" encoding="ISO-8859-1"?><br>
<!DOCTYPE lire:report-spec PUBLIC<br>
"-//LogReport.ORG//DTD Lire Report Specification Markup Language V1.0//EN"<br>
"http://www.logreport.org/LRSML/1.0/lrsml.dtd"><br>
<lire:report-spec xmlns:lire="http://www.logreport.org/LRSML/"<br>
superservice="firewall" id="bytesperfrom" charttype="bars"><br>
<br>
<lire:title>Top Bytes per From-IP Report</lire:title><br>
<lire:description><br>
<para><br>
This report lists the IP addresses sending the highest data volume.<br>
</para><br>
</lire:description><br>
<br>
<lire:param-spec><br>
<lire:param name="ips_to_show" type="int" default="10"><br>
<lire:description><br>
<para>This parameter controls the number of sending IP adresses to<br>
display in the report.<br>
</para><br>
</lire:description><br>
</lire:param><br>
</lire:param-spec><br>
<br>
<lire:display-spec><br>
<lire:title>Volume per sending IP, Top $ips_to_show</lire:title><br>
</lire:display-spec><br>
<br>
<lire:report-calc-spec><br>
<lire:group sort="-rcvd_volume" limit="$ips_to_show"><br>
<lire:field name="from_ip"/><br>
<lire:sum name="rcvd_volume" field="length"/><br>
</lire:group><br>
</lire:report-calc-spec><br>
<br>
</lire:report-spec><br>
</p>
<h3>De <i>lire</i> Naamruimte</h3>
<p>Het eerste dat je zou moeten opvallen is dat vrijwel ieder XML-element in dit rapport begint met
<i>lire:</i>. Dit wordt gebruikt om een naamruimte (namespace) toe te wijzen aan dat element. Ieder element met de
<i>lire</i>-naamruimte is gedefiniëerd in XML DTD
http://www.logreport.org/LRSML/1.0/lrsml.dtd (lege link!), die kan worden doorgespit op
<a href="http://www.logreport.org/pub/docs/dtd/lrsml/">http://www.logreport.org/pub/docs/dtd/lrsml/</a>.</p>
<p>Alle andere elementen zouden moeten toebehoren aan de
<a href="http://docbook.sourceforge.net/">DocBook XML 4.2 DTD</a>. Zoals het element
<para> op de tiende regel bijvoorbeeld.</p>
<h3>Het veranderen van de titel die bovenaan in de rapporten verschijnt</h3>
<p>Als je de titel die verschijnt in het rapport wilt wijzigen, dan moet je de <lire:title>
inhoud in de <lire:display-spec> veranderen. Onthoud hierbij dat strings die starten met
"$" Perlvariabelen zijn waar de naam correspondeert met een van de gespecificeerde parameters
in de <lire:param-spec>-sectie.</p>
<p><b>Het lastige deel is dat je het juiste <lire:title> element moet nemen.</b>
Je moet het element nemen dat de inhoud is van de <lire:display-spec>-knoop. Dat
element bevat de gegevens die verschijnen in het uitvoerrapport. Het eerste <lire:title>-element
bevat de titel van het rapport die gebruikt wordt in de documentatie van de Lire-software.</p>
<p>Het volgende voorbeeld laat een fragment van de requests-by-result WWW-rapportspecificatie
zien. Je kunt zien dat de <lire:display-spec> nu niet alleen een titel als uitvoer geeft,
maar ook wat meer uitleg. Let er op dat alle inhoud in het <lire:description>-element geen
gebruik maakt van de <i>lire</i> naamruimte, en dus DocBook-inhoud is.
</p><p class="code">
<lire:display-spec><br>
<lire:title>Requests By HTTP Result</lire:title><br>
<br>
<lire:description><br>
<para><br>
The most common HTTP status codes are given below:<br>
<variablelist><br>
<br>
<varlistentry><br>
<term>200</term><br>
<listitem><br>
<para>OK (The request has succeeded.)</para><br>
</listitem><br>
</varlistentry><br>
<br>
<!-- rest is cut out --><br>
</variablelist><br>
</para><br>
</lire:description><br>
</lire:display-spec><br>
</p>
<p>Het rapport zal er ongeveer uitzien als (alleen het bovenste deel hier):
</p><p class="code">
Requests By HTTP Result<br>
<br>
The most common HTTP status codes are given below:<br>
<br>
200 OK (The request has succeeded.)<br>
<br>
201 Created (The request has been fulfilled and resulted in a new resource being created.)<br>
<br>
206 Partial Content (The server has fulfilled the<br>
</p>
<h3>Het veranderen van het type afbeelding voor een rapport</h3>
<p>De meeste rapporten bevatten afbeeldingen die afhankelijk zijn van de gegevens. Deze afbeeldingen
worden gegenereerd met behulp van de gegevens en hun opmaak wordt bepaald door
de rapportspecificatie. Neem bijvoorbeeld het volgende stuk uit het FTP transfers-by-type rapport.</p>
<div class="programlisting">
<lire:report-spec xmlns:lire="http://www.logreport.org/LRSML/"
superservice="ftp" id="transfers-by-type" charttype="pie">
</div>
<p>Voor dit rapport worden de gegevens gevisualiseerd in een taartdiagram zoals te zien is aan het
@charttype attribuut in de bovenstaande code. Het resultaat ziet er zo uit:</p>
<p align="center"><img src="../../common/images/article218/t_art218_ftp1.png" width="350" height="303" alt="[charttype pie]"></p>
<p>Door het diagramtype te veranderen in <i>staaf</i> zoals in 'charttype="bars"'
verandert de uitvoer in:</p>
<p align="center"><img src="../../common/images/article218/t_art218_ftp2.png" width="350" height="296" alt="[charttype bars]">
</p>
<p>Let erop dat dit rapport een bug bevat. Het rapport gaat op het transfertype,
niet over het bestandstype. Deze bug is al gemeld.</p>
<h2>Specifieke informatie</h2>
<p>Meer specifieke informatie over de XML-taal die gebruikt is voor de rapportspecificatie
kan worden gevonden op de LogReport
<a href="http://www.logreport.org/pub/docs/dtd/lrsml/index.html">web site</a>.
Je zult zien dat de taal vrij uitgebreid is, en voorlopig kan ik je aanraden om gebruik te maken
van de rapportspecificatie die als gids bij de distributie wordt geleverd.</p>
<p>Elementen die niet besproken zijn in dit artikel maar die wel worden gebruikt in deze
rapporten voor de specificatie van parameters zijn (<lire:param-spec>) en de
berekening van de uitgedraaide gegevens (<lire:report-calc-spec>). Vooral de laatste heeft veel
opties en maakt gebruik van bestaande kennis van het interne formaat (genaamd DLF)
waarin de loggegevens worden opgeslagen. Dit zal worden besproken in een toekomstig artikel.</p>
<h2>Conclusie</h2>
<p>Dit artikel heeft de XML-gebaseerde rapport engine geïntroduceerd en uitgelegd
hoe je de rapporten die je krijgt kan aanpassen. Meer informatie kan worden gevonden op
de LogReport web site: <a href="http://www.logreport.org/">http://www.logreport.org/</a>.</p>
<p>Als je contact op wilt nemen met het team achter LogReport kun je IRC op gaan.
De ontwikkelaars kunnen vaak worden gevonden op het #logreport kanaal op het
<a href="http://www.openprojects.org/">OpenProjects.org IRC netwerk</a>.
Vragen, commentaar en ondersteuningsvragen zijn welkom. Als je liever gebruik maakt van
e-mail kun je het team bereiken via de openbare mailinglijst
<a href="mailto:questions@logreport.org">questions@logreport.org</a>.</p>
</body></html>