LR_XML_MERGE.IN(1)

NAME
lr_xml_merge - merge XML reports into a new XML report

SYNOPSIS
lr_xml_merge superservice report_cfg_file xml_report+

DESCRIPTION
lr_xml_merge will generate a new XML report on standard out using the report_cfg_file report configuration file. The data in this report will result from the merging of the XML reports specified on the command line.

This tool is useful to generate weekly or monthly reports from daily XML reports without having to reprocess the whole logs. It can be also useful to generate aggregated reports from specific server reports. For example, to generate a report for all the email servers of the network from the individual server reports.

The XML reports you merge should be of the same superservice. For best results, you should merge reports that were generated from the same report configuration file. You can use different parameters value. (For example, change the TOP 20 into TOP 10 or change the 1d period into a 1w or 1M period.)

HOW REPORTS ARE MERGED
For each subreport configured in the report configuration file, lr_xml_merge will use the data in each source XML reports that has the same index and report specification ID.

For example, if the www report configuration file you are using contains

    =section Activity Reports
    requests-by-period          period=1d
    bytes-by-period             period=1d
    user_sessions-by-period     period=1d
    =section Download Reports
    |select-url                 url_match="\\.(gz|tgz|zip|exe|pdf|doc)$"
    requests-by-period          period=1d
The first requests-by-period data will come from the first subreport in the source XML reports with a requests-by-period ID. For the other subreport requests-by-period that is in the "Download Reports" section, its data will come from the second subreport in the source XML reports that has a requests-by-period ID.

You don't have to worry about subreports which are marked missing "shifting" your data. Those subreports are present in the source XML report but don't contain any data, so they will be "merged" at the right place.

When merging results from timegroup, timeslot and rangegroup operation, lr_xml_merge won't do data interpolation. This means that if you changed some of the parameters between the merged XML report configuration and the source XML report configurations, make sure that the merged parameters are even multiple of the source ones. For example, for a timegroup operation, changing a 1d parameter into a 1w will work fine; changing a 1w into a 1d won't. When the parameters aren't compatible, you'll get a warning and the data from the failing subreport won't be included in the merged report.

GOTCHAS
You really don't want to merge reports for which the subreports order was reorgnanized unless you really know what you are doing.

Filters are ignored in the merging process. It is assumed that the source data was filtered accordingly.

For some operations, it is possible to obtain different reports when you process the entire log and when you merge smaller reports. The difference will be greatest for subreports which depends on the analysis window. In the case of the www superservice, such examples are found in subreports that depend on information related to client_host and sessions. A "Different Client Hosts" is related to the time window over which different client hosts are found. For example, when you add two daily reports to produce a weekly report, it's probable you have some overlap in client_hosts between the two days. This information should appear in the explanation message that precedes each subreport. If it doesn't, fill that as a bug.

VERSION
$Id: lr_xml_merge.in,v 1.6 2002/06/21 23:05:09 vanbaal Exp $

COPYRIGHT
Copyright (C) 2002 Stichting LogReport Foundation LogReport@LogReport.org

This program 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 program 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 program (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.

AUTHOR
Francis J. Lacoste <flacoste@logreport.org>