Document Type Definition for the XML Lire Report Markup Language as generated by lr_dlf2xml. Elements of that DTD are defined in the namespace http://www.logreport.org/LRML/ which will be usually mapped to the lire prefix. The latest version of that DTD is 2.1 and its public identifier is -//LogReport.ORG//DTD Report Markup Language V2.1//EN. Its canonical system identifier is http://www.logreport.org/LRML/2.1/lrml.dtd. <!-- Namespace prefix for validation using the DTD --> <!ENTITY % LIRE.xmlns.pfx "lire" > <!ENTITY % LIRE.pfx "%LIRE.xmlns.pfx;:" > <!ENTITY % LIRE.xmlns.attr.name "xmlns:%LIRE.xmlns.pfx;" > <!ENTITY % LIRE.xmlns.attr "%LIRE.xmlns.attr.name; CDATA #FIXED 'http://www.logreport.org/LRML/'"> <!ENTITY % LRCML.xmlns.pfx "lrcml" > <!ENTITY % LRCML.pfx "%LRCML.xmlns.pfx;:" > <!ENTITY % LRCML.xmlns.attr.name "xmlns:%LRCML.xmlns.pfx;" > <!ENTITY % LRCML.xmlns.attr "%LRCML.xmlns.attr.name; CDATA #FIXED 'http://www.logreport.org/LRCML/'"> This DTD uses the common modules lire-types.mod which defines the data types recognized by Lire and lire-desc.mod which is used to include a subset of DocBook in description and text elements. <!-- Include needed modules --> <!ENTITY % lire-types.mod PUBLIC "-//LogReport.ORG//ENTITIES Lire Data Types V1.0//EN" "lire-types.mod"> %lire-types.mod; <!ENTITY % lire-desc.mod PUBLIC "-//LogReport.ORG//ELEMENTS Lire Description Elements V3.0//EN" "lire-desc.mod"> %lire-desc.mod; Each report is an XML document of which the top-level element is the report element. The report's data is contained in subreport elements (these hold the results of each report specification that was used to generate the report). <!-- Parameter entities which defines qualified names of the elements --> <!ENTITY % LIRE.report "%LIRE.pfx;report" > <!ENTITY % LIRE.section "%LIRE.pfx;section" > <!ENTITY % LIRE.subreport "%LIRE.pfx;subreport" > <!ENTITY % LIRE.missing-subreport "%LIRE.pfx;missing-subreport" > <!ENTITY % LIRE.table "%LIRE.pfx;table" > <!ENTITY % LIRE.table-info "%LIRE.pfx;table-info" > <!ENTITY % LIRE.group-info "%LIRE.pfx;group-info" > <!ENTITY % LIRE.column-info "%LIRE.pfx;column-info" > <!ENTITY % LIRE.group-summary "%LIRE.pfx;group-summary" > <!ENTITY % LIRE.entry "%LIRE.pfx;entry" > <!ENTITY % LIRE.group "%LIRE.pfx;group" > <!ENTITY % LIRE.name "%LIRE.pfx;name" > <!ENTITY % LIRE.value "%LIRE.pfx;value" > <!ENTITY % LIRE.date "%LIRE.pfx;date" > <!ENTITY % LIRE.timespan "%LIRE.pfx;timespan" > <!ENTITY % LIRE.chart-configs "%LIRE.pfx;chart-configs" > <!ENTITY % LRCML.param "%LRCML.pfx;param" > <!ELEMENT %LRCML.param; (#PCDATA|%LRCML.param;)* > <!ATTLIST %LRCML.param; name NMTOKEN #REQUIRED value CDATA #IMPLIED >

A report starts with the report's meta-informations: title, timespan and description. The report's actual data is contained in one or more subreports. version The version of the DTD to which this report complies. New report should use the 2.1 value. <!ELEMENT %LIRE.report; ((%LIRE.title;)?, (%LIRE.date;)?, (%LIRE.timespan;)?, (%LIRE.description;)?, (%LIRE.section;)+) > <!ATTLIST %LIRE.report; version %number.type; #REQUIRED %LIRE.xmlns.attr; %LRCML.xmlns.attr; >

The date element contains the date on which the report was generated. The content of this element should be the timestamp in a format suitable for display. time The date in epoch time. <!ELEMENT %LIRE.date; (#PCDATA) > <!ATTLIST %LIRE.date; time %number.type; #REQUIRED>

The timespan element contains the starting and ending date which delimits the period of the report. The content of this element should be formatted for display purpose. The starting and ending time of the timespan can be read in epoch time in the attributes. The period attribute contains the timespan period. period Optional attribute which contains the period for which the report was generated. start The start time of the timespan in epoch time. end The end time of the timespan in epoch time. <!ELEMENT %LIRE.timespan; (#PCDATA) > <!ATTLIST %LIRE.timespan; period (hourly|daily|weekly|monthly|yearly) #IMPLIED start %number.type; #REQUIRED end %number.type; #REQUIRED >

The section element group common subreports together. The section's description will usually contains informations about the filters that were applied in this section. It contains a title, a description if some global filters were applied and the section's subreports. This element doesn't have any attribute. <!ELEMENT %LIRE.section; ( %LIRE.title;, (%LIRE.description;)?, (%LIRE.subreport;|%LIRE.missing-subreport;)*) >

The subreport element contains data for a certain report. It can contains meta-information elements, it they are different from the one of the report. Example of subreports for the email superservice are : Message delay by relay in seconds. Per hour traffic summary. Top 10 messages delivery. etc. The data is contains in a table element. If charts should be generated from the table's data, their configuration is contained in the chart-configs element. id A unique identifier that can be used to link to this element. superservice the name of the superservice from which the report's data comes from : i.e. email, www, dns, etc. type This is the name of the report specification that was used to generated this subreport. schemas A space delimited list of the schemas used by this subreport. <!ELEMENT %LIRE.subreport; ( %LIRE.title;, (%LIRE.description;)?, %LIRE.table;, (%LIRE.chart-configs;)?) > <!ATTLIST %LIRE.subreport; id ID #REQUIRED superservice %superservice.type; #REQUIRED type CDATA #REQUIRED schemas NMTOKENS #REQUIRED >

id A unique identifier that can be used to link to this element. superservice the name of the superservice from which the report's data comes from : i.e. email, www, dns, etc. type This is the name of the report specification that was used to generated this subreport. schemas A space delimited list of the schemas used by this subreport. reason The reason why this subreport is missing. <!ELEMENT %LIRE.missing-subreport; (EMPTY) > <!ATTLIST %LIRE.missing-subreport; id ID #IMPLIED superservice %superservice.type; #REQUIRED reason CDATA #IMPLIED type CDATA #REQUIRED schemas NMTOKENS #REQUIRED >

The table element contains the data of the subreport. It starts by a table-info element which contains information on the columns defined in the subreport. Following the table structure, there is a group-summary element which contains values computed over all the records. A table element can contains the subreport data directly or the data can be subdivided into groups. An example of a subreport which would contains directly the data would be "messages per to-domain, top-10". This would contains ten entries, one for each to-domain. An example of a subreport which would contains data in group would be "deliveries to users, per to-domain, top 30, top 5 users". It would contain 30 groups (one per to-domain) and each group would contain 5 entries (one per user). Group can be nested to arbitrary depth (but logic don't recommend to nest too much). show the number of entry to display. By default all entries should be displayed. <!ELEMENT %LIRE.table; (%LIRE.table-info;, %LIRE.group-summary;, (%LIRE.entry;)*) > <!ATTLIST %LIRE.table; show %int.type; #IMPLIED >

The table-info element contains information on the table structure. It contains one column-info element for each columns defined. It will also contains one group-info element for every grouping operation used in the report specification. This element doesn't have any attribute. <!ELEMENT %LIRE.table-info; (%LIRE.column-info;|%LIRE.group-info;)+ >

The group-info element play a similar role to the table-info element. Its used to group the columns defined by particular subgroup. name This attribute holds the name of the operation in the report specification which was responsible for the creation of this group data. row-idx Specify the row index of the table header in which this group's categorical labels should be displayed. <!ELEMENT %LIRE.group-info; (%LIRE.column-info;|%LIRE.group-info;)+ > <!ATTLIST %LIRE.group-info; name NMTOKEN #REQUIRED row-idx %int.type; #REQUIRED >

The column-info element describes a column of the table. It holds information related to display purpose (label, class, col-start, col-end, col-width) as well as information needed to use the content of the column as input to other computation (type, name). The col-start, col-end and col-width can be used to render the data in grid. name This attribute contains the name of the operation in the report specification which was used to generata data in this column. type The Lire data type of this column. class This attribute can either be categorical or numerical. Categorical data is held in name element and numerical data is held in value element. Also, numerical column will have column-summary element associated to them. label This optional attribute contains the column's label. If omitted, the name attribute's content will be used. col-start The column number in which this column start. The first column being column 0. col-end The column number in which this column ends. The first column being column 0. Spans are used to cover padding columns to indent grouped entries under their parent entry. col-width The suggested column width (in characters) to use for this column. max-chars The maximum entry's length in that column (this includes the label). avg-chars The average entry's length in that column (this includes the label). This value is rounded up to the nearest integer. <!ELEMENT %LIRE.column-info; EMPTY > <!ATTLIST %LIRE.column-info; name NMTOKEN #REQUIRED class (categorical|numerical) #REQUIRED type (%lire.types;) #REQUIRED label CDATA #IMPLIED col-start %int.type; #REQUIRED col-end %int.type; #REQUIRED col-width %int.type; #IMPLIED max-chars %int.type; #IMPLIED avg-chars %int.type; #IMPLIED >

The group-summary contains one value element for all the columns that contains numerical data. These elements will contains the statistics computed over all the DLF records which were processed by the group or the subreport. nrecords The number of DLF records that were processed by this group or subreport. missing-cases This attribute contains the number of LIRE_NOTAVAIL values found when computing the statistic. This number represents the number of records which didn't have the required information to group the records appropriately. If ommited or equals to 0, it means that all records had all the required information. row-idx Specify the row index in the table at which the group's summary value should be displayed. If this is attribute is omitted, the summary values won't be displayed. <!ELEMENT %LIRE.group-summary; (%LIRE.value;)* > <!ATTLIST %LIRE.group-summary; nrecords %int.type; #REQUIRED missing-cases %int.type; #IMPLIED row-idx %int.type; #IMPLIED >

The group element can be used to subdivide logically a report. It's used for aggregate reports like message per user per domain. It contains a group-summary element which contains the group's values for the whole group followed by the entries that makes the group. Groups can be nested more than once, but too much nesting augments information clutter and isn't useful for the user. id A unique identifier that can be used to link to this element. show the number of entry to display. By default all entries should be displayed. <!ELEMENT %LIRE.group; (%LIRE.group-summary;, (%LIRE.entry;)*)> <!ATTLIST %LIRE.group; id ID #IMPLIED show %int.type; #IMPLIED >

The entry contains the data from the report. It is similar to a row in a table altough one entry may represents several rows when it includes nested groups. The name elements contain categorical items of data like user name, email, browser type, url. Note that numeric ranges (like time period for example) are also considered categorical data items. The value elements contain numericical data which are the result of a descriptive statistical operation: message count, bytes transferred, average delay, etc. id A unique identifier that can be used to link to this element. row-idx Specify the row index in the table at which this entry's name and value elements should be rendered. If this is attribute is omitted, the entry won't be displayed. <!-- --> <!ELEMENT %LIRE.entry; (%LIRE.name;, (%LIRE.name;|%LIRE.value;|%LIRE.group;)+)> <!ATTLIST %LIRE.entry; id ID #IMPLIED row-idx %int.type; #IMPLIED >

The name elements contains categorical data column value. Its also used for numerical values that represents a class of values (like produced by the rangegroup or timegroup operations for example.) id A unique identifier that can be used to link to this element. col The column's name. It should be the same than the one in the corresponding column-info element. value When the displayed format is different from the DLF representation, this attribute contains the DLF representation. range In some cases (like in report generated by the timegroup, timeslot or rangegroup specification), this attribute will contains the range's length from the starting value which is in the 'value' attribute. <!ELEMENT %LIRE.name; (#PCDATA) > <!ATTLIST %LIRE.name; id ID #IMPLIED col NMTOKEN #REQUIRED value CDATA #IMPLIED range %number.type; #IMPLIED >

The value element contains numerical column value.. id A unique identifier that can be used to link to this element. col The column's name. It should be the same than the one in the corresponding column-info element. value contains the value in numeric format. This is used when the value was scaled (1k, 5M, etc.) total for average value, this contains the total used to compute the average. n for average value, this contains the n value that was used to compute the average. missing-cases This attribute contains the number of LIRE_NOTAVAIL values found when computing the statistic. When omitted, its assume to have a value of 0, i.e. that the value was defined in each DLF record. <!ELEMENT %LIRE.value; (#PCDATA) > <!ATTLIST %LIRE.value; id ID #IMPLIED col NMTOKEN #REQUIRED missing-cases %int.type; #IMPLIED value %number.type; #IMPLIED total %number.type; #IMPLIED n %number.type; #IMPLIED >

This element contains one or more chart configurations that should be generated from the table's. These chart configurations are specified using the Lire Report Configuration Markup Language. This element has no attribute. <!ELEMENT %LIRE.chart-configs; (%LRCML.param;)+ >