Document Type Definition for the Lire Report Specification Markup Language. This DTD defines a grammar that is used to specify reports that can be generated by Lire. Elements of this DTD uses the http://www.logreport.org/LRSML/ namespace that is usually mapped to the lire prefix. The latest version of that DTD is 2.1 and its public identifier is -//LogReport.ORG//DTD Lire Report Specification Markup Language V2.1//EN. Its canonical system identifier is http://www.logreport.org/LRSML/2.1/lrsml.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/LRSML/'"> <!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. <!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 V2.0//EN" "lire-desc.mod"> %lire-desc.mod; Each report specification is a XML document which has one report-spec as its root element. This DTD can also be used for filter specification which have one global-filter-spec as root element. <!ENTITY % LIRE.report-spec "%LIRE.pfx;report-spec" > <!ENTITY % LIRE.global-filter-spec "%LIRE.pfx;global-filter-spec"> <!ENTITY % LIRE.display-spec "%LIRE.pfx;display-spec" > <!ENTITY % LIRE.param-spec "%LIRE.pfx;param-spec" > <!ENTITY % LIRE.param "%LIRE.pfx;param" > <!ENTITY % LIRE.chart-configs "%LIRE.pfx;chart-configs" > <!ENTITY % LRCML.param "%LRCML.pfx;param" > <!ENTITY % LIRE.filter-spec "%LIRE.pfx;filter-spec" > <!ENTITY % LIRE.report-calc-spec "%LIRE.pfx;report-calc-spec" > <!ELEMENT %LRCML.param; (#PCDATA|%LRCML.param;)* > <!ATTLIST %LRCML.param; name NMTOKEN #REQUIRED value CDATA #IMPLIED >

Root element of a report specification. It contains descriptive elements about the report specification (title, description). It contains the display elements that will be in the generated report (display-spec). It contains specification for the parameters that can be used to customize the report generated from this specification (param-spec). Finally, it contains elements to specify a filter expression which can be used to select a subset of the records (filter-spec) and the expression to build the report (report-calc-spec). id the name of the superservice for which this report is available : i.e. email, www, dns, etc. schema The DLF schema used by the report. This defaults to the superservice's schema, but can be one of its derived or extended schema. joined-schemas A whitespace delimited list of additional schemas that will be joined for this report. This will make all fields define in these schemas available for the operators. The schemas that can be joined depends on the specification's schema. id An unique identifier for the report specification <!ELEMENT %LIRE.report-spec; (%LIRE.title;, %LIRE.description;, (%LIRE.param-spec;)?, %LIRE.display-spec;, (%LIRE.filter-spec;)?, (%LIRE.chart-configs;)?, %LIRE.report-calc-spec;) > <!ATTLIST %LIRE.report-spec; id ID #REQUIRED superservice %superservice.type; #REQUIRED schema NMTOKEN #IMPLIED joined-schemas NMTOKENS #IMPLIED %LIRE.xmlns.attr; %LRCML.xmlns.attr; >

Root element of a filter specification. It contains descriptive elements about the filter specification (title, description). It contains the display elements that will be used when that filter is used in a generated report (display-spec). It contains specification for the parameters that can be used to customize the filter generated from this specification (param-spec). Finally, it contains element to specify the filter expression which can be used to select a subset of the records (filter-spec). superservice the name of the superservice for which this filter is available : i.e. email, www, dns, etc. schema the DLF schema used by the report. This defaults to the superservice's schema, but can be one of its derived or extended schema. joined-schemas A whitespace delimited list of additional schemas that will be joined for this report. This will make all fields define in these schemas available for the operators. The schemas that can be joined depends on the specification's schema. id An unique identifier for the filter specification <!ELEMENT %LIRE.global-filter-spec; (%LIRE.title;, %LIRE.description;, (%LIRE.param-spec;)?, %LIRE.display-spec;, (%LIRE.filter-spec;)) > <!ATTLIST %LIRE.global-filter-spec; id ID #REQUIRED superservice %superservice.type; #REQUIRED schema NMTOKEN #IMPLIED joined-schemas NMTOKENS #IMPLIED %LIRE.xmlns.attr; >

This element contains the descriptive element that will appear in the generated report. It contains one title and may contains one description which will be used as help message This element has no attribute. <!ELEMENT %LIRE.display-spec; (%LIRE.title;, (%LIRE.description;)?) >

This element contains the parameters than can be customized in this report specification. This element doesn't have any attribute. <!ELEMENT %LIRE.param-spec; (%LIRE.param;)+ >

This element contains the specification for a parameter than can be used to customize this report. This element can contains a description element which can be used to explain the parameter's purpose. It is an error to define a parameter with the same name than one of the superservice's field. name the name of the parameter. type the parameter's data type default the parameter's default value <!ELEMENT %LIRE.param; (%LIRE.description;)? > <!ATTLIST %LIRE.param; name ID #REQUIRED type (%lire.types;) #REQUIRED default CDATA #IMPLIED >

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

<!ENTITY % LIRE.eq "%LIRE.pfx;eq" > <!ENTITY % LIRE.ne "%LIRE.pfx;ne" > <!ENTITY % LIRE.gt "%LIRE.pfx;gt" > <!ENTITY % LIRE.ge "%LIRE.pfx;ge" > <!ENTITY % LIRE.lt "%LIRE.pfx;lt" > <!ENTITY % LIRE.le "%LIRE.pfx;le" > <!ENTITY % LIRE.and "%LIRE.pfx;and" > <!ENTITY % LIRE.or "%LIRE.pfx;or" > <!ENTITY % LIRE.not "%LIRE.pfx;not" > <!ENTITY % LIRE.match "%LIRE.pfx;match" > <!ENTITY % LIRE.value "%LIRE.pfx;value" > <!ENTITY % expr "%LIRE.eq; | %LIRE.ne; | %LIRE.gt; | %LIRE.lt; | %LIRE.ge; | %LIRE.le; | %LIRE.and; | %LIRE.or; | %LIRE.not; | %LIRE.match; | %LIRE.value;" >

This element is used to select the subset of the records that will be used to generate the report. If this element is missing, all records will be used to generate the report. The content of this element are expression element which defines an expression which will evaluate to true or false for each record. The subset used for to generate the report are all records for which the expression evaluates to true. The value used to evaluate the expressions are either literal, value of parameter or value of one of the field of the record. Parameter and field starts with a $ followed by the name of the parameter or field. All other values are interpreted as literals. This element doesn't have any attribute. <!ELEMENT %LIRE.filter-spec; (%expr;) >

This expression element to false if the 'value' attribute is undefined, the empty string or 0. It evaluate to true otherwise. value The value that should be evaluated for a boolean context. <!ELEMENT %LIRE.value; EMPTY > <!ATTLIST %LIRE.value; value CDATA #REQUIRED >

<!ELEMENT %LIRE.eq; EMPTY > <!ATTLIST %LIRE.eq; arg1 CDATA #REQUIRED arg2 CDATA #REQUIRED >

<!ELEMENT %LIRE.ne; EMPTY > <!ATTLIST %LIRE.ne; arg1 CDATA #REQUIRED arg2 CDATA #REQUIRED >

<!ELEMENT %LIRE.gt; EMPTY > <!ATTLIST %LIRE.gt; arg1 CDATA #REQUIRED arg2 CDATA #REQUIRED >

<!ELEMENT %LIRE.ge; EMPTY > <!ATTLIST %LIRE.ge; arg1 CDATA #REQUIRED arg2 CDATA #REQUIRED >

<!ELEMENT %LIRE.lt; EMPTY > <!ATTLIST %LIRE.lt; arg1 CDATA #REQUIRED arg2 CDATA #REQUIRED >

<!ELEMENT %LIRE.le; EMPTY > <!ATTLIST %LIRE.le; arg1 CDATA #REQUIRED arg2 CDATA #REQUIRED >

The match expression element tries to match a POSIX 1003.2 extended regular expression to a value and return true if there is a match and false otherwise. value the value which should matched re A POSIX 1003.2 extended regular expression. case-sensitive Is the regex sensitive to case. Defaults to true. <!ELEMENT %LIRE.match; EMPTY > <!ATTLIST %LIRE.match; value CDATA #REQUIRED re CDATA #REQUIRED case-sensitive (%bool.type;) 'true' >

<!ELEMENT %LIRE.not; (%expr;) >

<!ELEMENT %LIRE.and; (%expr;)+ >

<!ELEMENT %LIRE.or; (%expr;)+ >

<!ENTITY % LIRE.timegroup "%LIRE.pfx;timegroup" > <!ENTITY % LIRE.group "%LIRE.pfx;group" > <!ENTITY % LIRE.rangegroup "%LIRE.pfx;rangegroup" > <!ENTITY % LIRE.timeslot "%LIRE.pfx;timeslot" > <!ENTITY % LIRE.field "%LIRE.pfx;field" > <!ENTITY % LIRE.sum "%LIRE.pfx;sum" > <!ENTITY % LIRE.avg "%LIRE.pfx;avg" > <!ENTITY % LIRE.min "%LIRE.pfx;min" > <!ENTITY % LIRE.max "%LIRE.pfx;max" > <!ENTITY % LIRE.first "%LIRE.pfx;first" > <!ENTITY % LIRE.last "%LIRE.pfx;last" > <!ENTITY % LIRE.count "%LIRE.pfx;count" > <!ENTITY % LIRE.records "%LIRE.pfx;records" > <!-- Empty group operator --> <!ENTITY % LIRE.empty-ops "%LIRE.sum; | %LIRE.avg; | %LIRE.count; | %LIRE.min; | %LIRE.max; | %LIRE.first; | %LIRE.last; | %LIRE.records;" > <!-- Group operations that are also aggregators --> <!ENTITY % LIRE.nestable-aggr "%LIRE.group; | %LIRE.timegroup; | %LIRE.timeslot; | %LIRE.rangegroup;" > <!-- Group operations --> <!ENTITY % LIRE.group-ops "%LIRE.empty-ops;| %LIRE.nestable-aggr;" > <!-- Containers for group operations --> <!ENTITY % LIRE.aggregator "%LIRE.nestable-aggr;" >

This element describes the computation needs to generate the report. It contains one aggregator element. This element doesn't have any attributes. <!ELEMENT %LIRE.report-calc-spec; (%LIRE.aggregator;) >

All elements which will create a column in the resulting report have a label attribute that will be used as the column label. When this attribute is omitted, the name attribute content will be used as column label. <!ENTITY % label.attr "label CDATA #IMPLIED"> All operation elements may have a name attribute which can be used to reference that column. (It is required in the case of aggrage functions). The primary usage is for controlling the sort order of the rows in the generated report. <!ENTITY % name.attr "name ID #IMPLIED"> <!ENTITY % name.attr.req "name ID #REQUIRED">

The group element generates a report where records are grouped by some field values and aggregate statistics are computed on those group of records. It contains the field that should be used for grouping and the statistics that should be computed. The sort order in the report is controlled by the 'sort' attribute. name An identifier that can be used to reference this operation from other elements. This name will most often be used in the parent's sort attribute. If omitted a default name will be generated. sort whitespace delimited list of fields name that should used to sort the records. Field names can be prefixed by - to specify reverse sort order, otherwise ascending sort order is used. The name can also refer to the name attribute of the statistics element. limit limit the number of records that will be in the generated report. It can be either a positive integer or the name of a user supplied param. <!ELEMENT %LIRE.group; ((%LIRE.field;)+, (%LIRE.group-ops;)+) > <!ATTLIST %LIRE.group; %name.attr; sort NMTOKENS #IMPLIED limit CDATA #IMPLIED >

The timegroup element generates a report where records are grouped by time range (hour, day, etc.). Statistics are then computed on these records grouped by period. name An identifier that can be used to reference this operation from other elements. This name will most often be used in the parent's sort attribute. If omitted a default name will be generated. label Sets the column label that will be used for column generated by this element. If omitted a default label will be generated. field the name of the field which is used to group records. This should be a field which is of one of the time types (timestamp, date, time). It defaults to the default timestamp field if unspecified. period This is the timeperiod over which records should be grouped. Valid period looks like (hour, day, 1h, 30m, etc). It can also be the name of a user supplied param. <!ELEMENT %LIRE.timegroup; (%LIRE.group-ops;)+ > <!ATTLIST %LIRE.timegroup; %name.attr; %label.attr; field NMTOKEN #IMPLIED period CDATA #REQUIRED >

The timeslot element generates a report where records are grouped according to a cyclic unit of time. The duration unit used won't fall over to the next higher unit. For example, this means that using a unit of 1d will generate a report where the stats will be by day of the week, 8h will generate a report by third of day, etc. The statistics are then computed over the records in the same timeslot. Using a specification like: <lire:timeslot unit="1d"> ... </lire:timeslot> would generate a report like: Sunday ...Monday ...Tuesday ...... ...Saturday... where data will be summed over all Sunday's, Monday's, ..., and Saturdays found in the log. Specifying unit="2m" would generate a line for each two months, giving a yearly view. name An identifier that can be used to reference this operation from other elements. This name will most often be used in the parent's sort attribute. If omitted a default name will be generated. label Sets the column label that will be used for column generated by this element. If omitted a default label will be generated. field the name of the field which is used to group records. This should be a field which is of one of the time types (timestamp, date, time). It defaults to the default 'timestamp' field if unspecified. unit This is the cyclic unit of time in which units the records are aggregated. It can be any duration value. (hour, day, 1h, 30m, etc). It can also be the name of a user supplied param. <!ELEMENT %LIRE.timeslot; (%LIRE.group-ops;)+ > <!ATTLIST %LIRE.timeslot; %name.attr; %label.attr; field NMTOKEN #IMPLIED unit CDATA #REQUIRED >

The rangegroup element generates a report where records are grouped into distinct class delimited by a range. This element can be used to aggregates continuous numeric values like duration or bytes. Statistics are then computed on these records grouped in range class. name An identifier that can be used to reference this operation from other elements. This name will most often be used in the parent's sort attribute. If omitted a default name will be generated. label Sets the column label that will be used for column generated by this element. If omitted a default label will be generated. field the name of the field which is used to group records. This should be a field which is of a continuous numeric type (bytes, duration, int, number). Time types aggregation should use the timegroup element or timeslot. range-start The starting index of the first class. Defaults to 0. This won't be used a the lower limit of the class. It is only used to specify relatively at which values the classes delimitation start. For example, if the range-start is 1, and the range-size is 5, a class ranging -4 to 0 will be created if values are in that range. It can be supplied in any continuous unit (i.e 10k, 5m, etc.) This can also be the name of a user supplied param. range-size This is the size of class. It can be supplied in any continuous unit (i.e 10k, 5m, etc.) It can also be the name of a user supplied param. min-value All value lower then this boundary value will be considered to be equal to this value. If this parameter isn't set, the ranges won't be bounded on the left side. max-value All value greater then this boundary value will be considered to be equal to this value. If this parameter isn't set, the ranges won't be bounded on the right side. size-scale The rate at which the size scale from one class to another. If it is different then 1, this will create a logarithmic distribution. For example, setting this to 2, each successive class will be twice larger then the precedent : 0-9, 10-29, 30-69, etc. <!ELEMENT %LIRE.rangegroup; (%LIRE.group-ops;)+ > <!ATTLIST %LIRE.rangegroup; %name.attr; %label.attr; field NMTOKEN #REQUIRED range-start CDATA #IMPLIED range-size CDATA #REQUIRED min-value CDATA #IMPLIED max-value CDATA #IMPLIED size-scale CDATA #IMPLIED >

This element reference a DLF field which value will be displayed in a separate column in the resulting report. Its used to specify the grouping fields in the group element and to specify the fields to output in the records element. name The name of the DLF field that will be used as key for grouping. label Sets the column label that will be used for column generated by this element. If omitted a default label will be generated. <!ELEMENT %LIRE.field; EMPTY > <!ATTLIST %LIRE.field; name NMTOKEN #REQUIRED %label.attr; >

The sum element sums the value of a field in the group. name An identifier that can be used to reference this operation from other elements. This name will most often be used in the parent's sort attribute. label Sets the column label that will be used for column generated by this element. If omitted a default label will be generated. field the field that should be summed. ratio This attribute can be used to display the sum as a ratio of the group or table total. If the attribute is set to group the resulting value will be the ratio on the group's total sum. If the attribute is set to table, it will be expressed as a ratio of the total sum of the table. The defaults is none which will not convert the sum to a ratio. weight This optional attribute can be used to create a weighted sum. It should contain a numerical DLF field name. The content of that field will be used to multiply each field value before summing them. <!ELEMENT %LIRE.sum; EMPTY > <!ATTLIST %LIRE.sum; %name.attr.req; %label.attr; ratio (none | group |table) 'none' field NMTOKEN #REQUIRED weight NMTOKEN #IMPLIED >

The avg element calculate average of all value of a field in the group. The average will be computed either on the number of records if the by-field attribute is left empty, or by the number of different values that there are in the by-fields. name An identifier that can be used to reference this operation from other elements. This name will most often be used in the parent's sort attribute. label Sets the column label that will be used for column generated by this element. If omitted a default label will be generated. field the field that should be averaged. If left unspecified the number of record will be counted. by-fields the fields that will be used to dermine the count over which the average is computed. weight This optional attribute can be used to create a weighted average. It should contain a numerical DLF field name. The content of that field will be used to multiply each field value before summing them. Its that weighted sum that will be used to calculate the average. <!ELEMENT %LIRE.avg; EMPTY > <!ATTLIST %LIRE.avg; %name.attr.req; %label.attr; field NMTOKEN #IMPLIED by-fields NMTOKENS #IMPLIED weight NMTOKEN #IMPLIED >

The max element calculates the maximum value for a field in all the group's records. name An identifier that can be used to reference this operation from other elements. This name will most often be used in the parent's sort attribute. label Sets the column label that will be used for column generated by this element. If omitted a default label will be generated. field the field for which the maximum value should found. <!ELEMENT %LIRE.max; EMPTY > <!ATTLIST %LIRE.max; %name.attr.req; %label.attr; field NMTOKEN #REQUIRED >

The min element calculates the minimum value for a field in all the group's records. name An identifier that can be used to reference this operation from other elements. This name will most often be used in the parent's sort attribute. label Sets the column label that will be used for column generated by this element. If omitted a default label will be generated. field the field for which the minimum value should found. <!ELEMENT %LIRE.min; EMPTY > <!ATTLIST %LIRE.min; %name.attr.req; %label.attr; field NMTOKEN #REQUIRED >

The first element will display the value of the value of one field of the first DLF record within its group. The sort order is controlled through the sort attribute.. name An identifier that can be used to reference this operation from other elements. This name will most often be used in the parent's sort attribute. label Sets the column label that will be used for column generated by this element. If omitted a default label will be generated. field the DLF field which will be displayed. sort whitespace delimited list of fields name that should used to sort the records. Field names can be prefixed by - to specify reverse sort order, otherwise ascending sort order is used. If this attribute is omitted, the records will be sort in ascending order of the default timestamp field. <!ELEMENT %LIRE.first; EMPTY > <!ATTLIST %LIRE.first; %name.attr.req; %label.attr; field NMTOKEN #REQUIRED sort NMTOKENS #IMPLIED >

The last element will display the value of the value of one field of the last DLF record within its group. The sort order is controlled through the sort attribute.. name An identifier that can be used to reference this operation from other elements. This name will most often be used in the parent's sort attribute. label Sets the column label that will be used for column generated by this element. If omitted a default label will be generated. field the DLF field which will be displayed. sort whitespace delimited list of fields name that should used to sort the records. Field names can be prefixed by - to specify reverse sort order, otherwise ascending sort order is used. If this attribute is omitted, the records will be sort in ascending order of the default timestamp field. <!ELEMENT %LIRE.last; EMPTY > <!ATTLIST %LIRE.last; %name.attr.req; %label.attr; field NMTOKEN #REQUIRED sort NMTOKENS #IMPLIED >

The count element counts the number of records in the group if the fields attribute is left empty. Otherwise, it will count the number of different values in the fields specified. name An identifier that can be used to reference this operation from other elements. This name will most often be used in the parent's sort attribute. label Sets the column label that will be used for column generated by this element. If omitted a default label will be generated. fields Which fields to count. If unspecified all records in the group are counted. If not, only different fields' value will be counted. ratio This attribute can be used to display the frequency as a ratio of the group or table total. If the attribute is set to group the resulting value will be the ratio on the group's total frequency. If the attribute is set to table, it will be expressed as a ratio of the total frequency of the table. The defaults is none which will not convert the frequency to a ratio. <!ELEMENT %LIRE.count; EMPTY > <!ATTLIST %LIRE.count; %name.attr.req; %label.attr; ratio (none | group |table) 'none' fields NMTOKENS #IMPLIED >

The records element will put the content of selected fields in the report. This can be used in reports that shows events matching certain criteria. The fields that will be included in the report for each record is specified by the field element. fields whitespace delimited list of fields name that should included in the report. <!ELEMENT %LIRE.records; EMPTY > <!ATTLIST %LIRE.records; fields NMTOKENS #REQUIRED >