You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

Overview

This document documents the mechanisms for generating (and managing) reports on demand (instead of via schedules, which are described here).

Generating Reports from the GUI

You find the report generating interface under the menu Views, On-Demand Reports or from the dashboard page.

The interface is mostly self-explanatory, and has a number of tooltips for documenting some of the non-obvious items.

When you hit the Generate button the report creation is started in the background, and you will be shown a message with a link to the report display; if your report covers lots of nodes or a long period, then it may take some time until generation is complete, but the GUI will be completely usable in the meantime. Your new report will show up as "in progress" on the report list until it's finished.

Naming

Reports generated from the GUI are saved in /usr/local/omk/var/reports/on-demand (but this is configurable, see <omk_reports_ondemand> in opCommon.nmis).

If you don't select a report name (under advanced options), then the report name will be generated from report type, date and a few other properties. If a name clash is detected, then newer reports will be named <originalname>.1,  .2 and so on. This de-clashing also applies to your custom report name!

Aging

Old on-demand reports are pruned based on the configuration setting default_report_keep_for, subsection on-demand (in opCommon.nmis) by default that is set to 42 days.

Generating Reports from the Command Line

We recommend that you primarily use the report scheduling system and the GUI on-demand report creation for maximum robustness, but if utmost flexibility is required (at the expense of fewer safeguards) then there's a tool available for that, too: opReports ships with a command line tool for report generation: opreports-cli.pl (in /usr/local/omk/bin/).

If you run the tool with "-h" or "–help" or "-?" you'll see the brief help text:

./bin/opreports-cli.pl -?
opReports Version 3.1.0
...
usage: ./bin/opreports-cli.pl act=<report type> days=<N> from=<HH> to=<HH>
       start_date=<date_time> end_date=<date_time>

       group=<NMIS_GROUP>|All|Each
       noderegex=<regexp>
       nodes=NAME1 node=NAME2...
       node_intf_list=<listfile>
       node_list=<listfile>
       node_intf_type_list=<listfile>
       
       email=<user@domain.com,user2@domain.com...>
       output_file=<path> output_file_2=<path>
       format=HTML|CSV|XLSX format_2=...

act:        the report to create, (avgcpu|buffer|freemem|health|mempool|node|qos|response|summary|uptime|usage|util|wan)
noderegex:  a regular expression for matching the node name (not with group)
group:      group of devices to report on, either NMIS group name, 
  "All", "Each" or nothing
  "All" (or nothing) means all nodes in all groups will produce a report containing all devices in all groups
  "Each" produces a separate report for each group.
email:      send report to the listed email addresses (comma separated list)
days:       Number of days to report
start_date: The starting date and time e.g. "1-Apr-2012 14:35:00"
end_date:   The end date and time e.g. "5-Apr-2012 17:00:00"
from:       Business hours reporting, the daily start time in hours
to:         Business hours reporting, the daily end time in hours
format:     Desired Output Format, "HTML", "CSV", "XLSX"

Selecting output formats and destinations

With opreports-cli you have total control over what formats your reports are generated in, and where they are saved. Please note that reports created by opreports-cli are generally not visible in the GUI, and are not aged!

To generate a report in a format X (html, csv, xlsx), use the options format_N and output_N (N being a number); e.g. format_1=html output_1=/tmp/xyz.html. You can use up to three format/output options (and if you want just one format, then you can leave off the "_N").

Report formats csv and html can also be printed to stdout, using output_N=- (minus sign); Note that this does not work for xlsx, and only one format can be sent to stdout.

The output_N option must be a path pointing to a file. Please note that opreports-cli overwrites existing files without warning!

In addition to file-based outputs you can also specify email recipients using the email=some@addre.ss,other@addr.ess option. Please note that output_N is still required. The report will be emailed to all recipients with all selected formats as attachments.

Making command-line generated reports visible to the GUI

To make manually generated reports show up in the GUI, and be aged by the scheduler, all the following conditions must be met:

  1. All output_N options must point to the same directory, and it must be the configured on-demand directory.
  2. All the relative file names given in output_N must be identical (but for the extension).
    this works: format_1=HTML output_1=/usr/local/omk/var/reports/on-demand/testme.html format_2=XLSX output_2=/usr/local/omk/var/reports/on-demand/testme.xlsx
    whereas this doesn't: output_1=.../test_one.html output_2=..../test_two.csv
  3. You must add the option actual_name=<the name of your report files minus extension>.
    For the example from step 2 this would be actual_name=testme.
    You must add the option actual_uuid=<unique identifier>.
    The uuid should follow the UUID V4 standard format , but any globally unique string will do.
  4. If you want report aging, then you have to add a keep_for=<days> option.




  • No labels