Analisando os ficheiros de log das suas aplicações de internet II -- configurando os relatórios

ArticleCategory:

AuthorImage:

TranslationInfo:

original in en Egon Willighagen

en to pt Bruno Sousa

AboutTheAuthor:

Abstract:

ArticleIllustration:

ArticleBody:

Introdução

Este artigo é baseado na última apresentação do Lire, sendo lire-20011017. note que a configuração foi alterada imenso desde a versão anterior e que basicamente, o primeiro artigo desta série já está desactualizado. Contudo a ideia geral do lr_config não foi alterada.

As novas especificações entre outras, são: dois novos super serviços (FTP e firewall), imensos relatórios (total > 68), novos formatos de saída (XHTML e RTF) e correcção de alguns bugs. Mas a mais importante modificação nesta versão é o motor. O processo de geração de um ralatório foi completamente rescrito para utilizar a tecnologia XML.

Este artigo introduzirá um dos formatos XML que são usados no Lire e como é usado para especificar relatórios. Não será um tutorial em como fazer novos relatórios, mas mostrar-lhe-á como pode alterar os relatórios pré-definidos num baixo nível. Mas antes, este artigo explicará como pode dizer ao Lire os relatórios que deve gerar e como os parâmetros para estes relatórios podem ser definidos.

Seleccionando Relatórios

Cada super serviço (por exemplo `email' é um super serviço, os serviços `postfix' e o `sendmail' pertencem a este super serviço) tem um número de relatórios disponíveis que extraem a informação de log para si. O super serviço WWW tem, por exemplo, 31 relatórios. Nem todos os relatórios são interessantes para toda a gente. Alguns são mais específicos. Por omissão, muitos destes relatórios são seleccionados, mas é útil personalizar isto.

Os relatórios que serão usados para gerar o relatório são dados no ficheiro <prefix>/etc/lire/<superservice>.cfg (assumindo que o Lire está instalado no directório <prefix>). Por exemplo, o ficheiro de configuração para o super serviço FTP assemelha-se:

# 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

O super serviço FTP tem oito relatórios definidos e todos, excepto um são seleccionados. O "top-files" está deseleccionado devido ao caracter "#". Removendo o caracter "#" seleccionará, novamente o relatório.

Note que nem todas as linhas começadas por "#" são relatórios. Neste ficheiro de configuração as linhas "Report configuration for the FTP super service", "Top X reports", "By day reports" e "Transfers by X reports" são comentários. Coisas semelhantes podem ser esperadas noutros ficheiros de configuração.

Sortindo Relatórios

A ordenação é bastante simples. A ordem pela qual as linhas de relatório aparecem nos ficheiros de configuração é a ordem pela qual os relatórios serão dados na saída. Um novo arranjo das linhas nestes ficheiros de configuração reordena-os na saída. Por exemplo, no exemplo acima, transfers-by-type será o último relatório dado no output.

Personalizando Relatórios

Muitos relatórios podem ser parcialmente personalizados com os ficheiros de configuração explicados na secção anterior. Por exemplo, considere a configuração do super serviço 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'

Todos os quinze relatórios são seleccionados, mas para além disto os relatórios tendo um X topo na saída permitem definir esse X. Com a configuração corrente o relatório top-requesting-hosts dará um topo de 10.

Estes relatórios são gerados a partir de 8 especificações de relatórios. O uso de parâmetros (period, method, hosts_to_show,e names_to_show) torna isto possível. Isto é uma das poderosas características do novo motor à base do XML.

Importante: todas as definições de variáveis devem ser colocadas na mesma linha do nome do relatório!

Um exemplo mais exótico vem do ficheiro de configuração do super serviço WWW:

top-referers-by-page referer_to_show=5 page_to_show=10 referer_exclusion='^-$'

Neste exemplo é utilizada uma expressão regular do Perl como conteúdo para a variável referer_exclusion. Esta expressão condiz com todas as referências "-". Tais referências são encontradas no ficheiro de log quando, por exemplo, o URL da sua página web foi digitado pelo utilizador cliente. (Quando os utilizadores visitam a sua página clicando num link de uma página que aponta para a sua página, a página de ligação será dada no campo de referência). Todas as referências que condizem com "-" serão excluídas da análise.

Personalização a baixo nível dos relatórios

Esta nova versão é o inicio de um novo ramo do Lire. A geração do relatório e o processo de especificação foram novamente escritos para utilizarem a tecnologia XML. Os relatórios são especificados em XML, mas a definição das variáveis é feita em pleno formato ASCII. A especificação do relatório anterior utilizava uma script em Perl que tinha de saber quer o formato de entrada bem como o de saída. Com este novo formato XML, a implementação é separada da especificação, não precisando de saber qual o formato de entrada e de saída; somente precisa de saber a informação a ser processada.

Assim, ao personalizar os relatórios a um baixo nível, precisa de saber um pouco de XML. Um exemplo de relatório retirado do directório <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>

O "Namespace" do lire

A primeira coisa que devia ter notado é que, quase todos os elementos XML neste relatório começam com lire:. Isto é usado para atribuir um "namespace" ao elemento. Cada elemento com o namespace do lire, está definido no XML DTD http://www.logreport.org/LRSML/1.0/lrsml.dtd (link inválido!), que pode ser pesquisado em http://www.logreport.org/pub/docs/dtd/lrsml/.

Todos os outros elementos são supostos pertencer ao DocBook XML 4.2 DTD. Como o elemento <para> na décima linha deste exemplo.

Alterando o título que aparece nos relatórios gerados do Lire

Se quiser alterar o título que aparece no relatório, precisa de alterar o conteúdo de <lire:title> na <lire:display-spec>. Tenha em mente que strings começadas em "$" são variáveis de Perl onde o nome corresponde a um dos parâmetros especificados na secção <lire:param-spec>.

A coisa mais delicada é que dele escolher o elemento <lire:title> correcto. Precisa do elemento que seja o conteúdo do nodo <lire:display-spec>. O último elemento contém informação que é apresentado no output do relatório. O primeiro elemento <lire:title> contém o título do relatório utilizado na documentação do software Lire.

O próximo exemplo mostra um fragmento da especificação requests-by-result do relatório WWW. Nele pode ver que o <lire:display-spec> agora, não só apresenta um título no output mas também alguma explicação. Nem todo o conteúdo do elemento <lire:description> está a utilizar o "namespace" lire, sendo assim conteúdo do 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>

O output do relatório assemelha-se a algo como (somente o topo é mostrado):

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

Alterando o tipo de imagem para um relatório

Muitos programas têm gráficos associados aos dados. Estas imagens são geradas a partir dos dados e da especificação do relatório que também define o formato no qual a imagem é gerada. Tome para exemplo o seguinte extracto de um relatório transfers-by-type de FTP.

Para este relatório os dados são visualizados num gráfico circular como pode ser visto no atributo @charttype do código acima. O resultado parece algo como:

Alterando o tipo de gráfico para bars, ou seja 'charttype="bars"', o output altera-se para:

Note que o título do relatório contém um bug. O relatório está no tipo de transferência e não no tipo de ficheiro. Este bug foi já reportado.

Especificações

Mais informação específica acerca da linguagem XML utilizada para a especificação de relatórios pode ser encontrada no web site da LogReport. Verá que a linguagem é de fácil compreensão, mas por agora sugiro que utilize a especificação dos relatórios que vêm na distribuição como o seu guia principal.

Elementos que não foram falados neste artigo mas que são usados nos relatórios para especificação dos parâmetros (<lire:param-spec>) e cálculo dos dados de output (<lire:report-calc-spec>). Especialmente, o último tem imensas opções utilizando conhecimento previsível do formato interno (chamado DLF) no qual os dados de log são guardados. Isto será explicado num futuro artigo.

Conclusão

Este artigo introduziu o motor de geração de relatórios baseado em XML e explicou como personalizar os relatórios que obtém. Pode ser encontrada mais informação no web site da LogReport: http://www.logreport.org/.

Se quiser entrar em contacto com o equipar do LogReport, pode-se juntar ao IRC. Os programadores podem, muito frequentemente, ser encontrados no canal #logreport do OpenProjects.org IRC network. Questões, comentários e pedidos de suporte são bem-vindos. Se preferir o email, pode alcançar a equipar na lista pública de mailing questions@logreport.org.