Lire Developer's Manual

Joost van Baal

Egon L. Willighagen

Francis J. Lacoste

This manual is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this manual (see COPYING); if not, check with http://www.gnu.org/copyleft/gpl.html or write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.

Revision History
Revision 2.1.1 $Date: 2008/03/03 06:30:02 $
$Id: dev-manual.dbx,v 1.90 2008/03/03 06:30:02 vanbaal Exp $

Table of Contents

Preface
What This Book Contains
How Is This Book Organized?
Conventions Used
If You Don't Find Something In This Manual
I. Lire Architecture
1. Architecture Overview
Lire's Design Patterns
Log File Normalisation
Log Analysis
Report Generation
Report Formatting and Other Post-Processing
Going Further
II. Using the Lire Framework
2. Writing a New DLF Converter
Prerequisites
The common_syslog Log Format
Creating the DLF Converter Skeleton
Adding a Constructor
The Meta-Data Methods
The DLF Converter Name
Providing Information To Users
Providing Information to the Framework
The Conversion Methods
Registering Your DLF Converter with the Lire Framework
DLF Converter API
3. Writing a DLF Schema
Designing the ftpproto schema
Creating The Schema File
Adding the Schema's Description
Defining the Schema's Fields
Installing The Schema
4. Writing a New DLF Analyser
Writing a Categoriser
Defining The Extended Schema
Defining the Categoriser
Categoriser Configuration
Categoriser Implementation
Writing an Analyser
DLF Analyser API
5. Writing a New Report
Filter Specification
III. Developer's Reference
6. Lire Data Types
Lire Textual Elements
title element
DocBook Elements
description element
7. Common Textual Elements to All XML Formats
Lire Data Types Parameter Entities
Boolean Type
Integer Type
Number Type
String Type
Timestamp type
Time Type
Date Type
Duration Type
IP Type
Port Type
Hostname Type
URL Type
Email Type
Bytes Type
Filename Type
Field Type
Superservice Type
Related Types
8. The Lire Report Configuration Specification Markup Language
The Lire Report Configuration Specification Markup Language
config-spec element
summary element
Parameter Specifiations Elements
9. The Lire Report Configuration Markup Language
The Lire Report Configuration Markup Language
config element
global element
param element
10. The Lire DLF Schema Markup Language
The Lire DLF Schema Markup Language
The dlf-schema element
extended-schema element
derived-schema element
field element
11. The Lire Report Specification Markup Language
The Lire Report Specification Markup Language
report-spec element
global-filter-spec element
display-spec element
param-spec element
param element
chart-configs element
Filter expression elements
Report Calculation Elements
12. The Lire Report Markup Language
The Report Markup Language
report element
Meta-information elements
section element
subreport element
missing-subreport element
table element
table-info element
group-info element
column-info element
group-summary element
group element
entry element
name element
value element
chart-configs element
IV. Lire Developers' Conventions
13. Contributing Code to Lire
14. Developers' Toolbox
Required Tools To Build From CVS
Accessing Lire's CVS
CVS primer
SourceForge
Mailing Lists
15. Coding Standards
Shell Coding Standards
Perl Coding Standards
16. Making Lire Test-infected
Unit Tests in Lire
PerlUnit
Writing Tests
Running Tests
Some Best Practices on Unit Testing
17. Commit Policy
CVS Branches
Hands-on example
Naming, what it looks like
Creating a Branch
Accessing a Branch
Merging Branches on the Trunk
18. Testing and debugging
Test before releasing
Test-installations and test-runs
Using the Perl debugger on Lire code
19. Making a Release
Setting version in NEWS file, checking ChangeLog
Tagging the CVS
Building The Tarball
Building The Debian Package
Building The RPM Package
Making sure the FreeBSD port gets updated
Uploading The Release
The LogReport Webserver
Advertising The Release
SourceForge
Freshmeat.net
20. Website Maintenance
Documentation on the LogReport Website
Publishing the DTD's
21. Writing Documentation
Plain Text
Perl's Plain Old Documentation: maintaining manpages
Docbook XML: Reference Books and Extensive User Manuals
V. Implementation Details
22. Adding a New Superservice in Lire's Distribution
23. Issues with Report Merging
24. Overview of Lire scripts
25. Source Tree Layout
Glossary

List of Figures

1.1. Log Processing in the Lire's Framework
1.2. The Log Normalisation Process
1.3. The Log Analysis Process
1.4. Report Generation Process
1.5. Processing of the XML Report Using The APIs

List of Tables

11.1. weekly overview

List of Examples

11.1. timeslot with 1d unit
11.2. timeslot with 2m unit
3. DNS DLF Excerpts