Chapter 12. The Lire Report Markup Language
Prev | Part III. Developer's Reference | Next

## Chapter 12. The Lire Report Markup Language

## The Report Markup Language

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 >

### `report` element

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.

`report`'s attributes

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;                                       >

### Meta-information elements

#### `date` element

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.

``'s attribute

time

  The date in epoch time.

    <!ELEMENT %LIRE.date;    (#PCDATA)                                   >
    <!ATTLIST %LIRE.date;
                 time        %number.type;                      #REQUIRED>

#### `timespan` element

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.

`timespan`'s attributes

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   >

### `section` element

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;)*) >

### `subreport` element

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.

`subreport`'s attributes

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 >

### `missing-subreport` element

`missing-subreport`'s attributes

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 >

### `table` element

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).

`table`'s attributes

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 >

### `table-info` element

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;)+ >

### `group-info` element

The `group-info` element play a similar role to the `table-info` element. Its used to group the columns defined by particular subgroup.

`group-info`'s attribute

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 >

### `column-info` element

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.

`column-info`'s attributes

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 >

### `group-summary` element

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.

`group-summary`'s attribute

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 >

### `group` element

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.

`group`'s attributes

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 >

### `entry` element

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.

`entry`'s attribute

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 >

### `name` element

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.)

`name`'s attributes

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 >

### `value` element

The value`` element contains numerical column value..

`value`'s attributes

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 >

### `chart-configs` element

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;)+                      >

Prev | Up | Next
Chapter 11. The Lire Report Specification Markup Language | Home | Part IV. Lire Developers' Conventions