This document documents the mechanisms for generating (and managing) reports one-off (instead of via schedules, which are described here).
Generating Reports from the GUI
You find the report generating interface under the menu Views >> Report Schedules page using the Create one-off Report button.
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.
Report Naming and Storage Locations
Reports generated from the GUI are saved in
/usr/local/omk/var/reports (but this is configurable, see <omk_reports> in
Reports generated by the scheduler are saved in the output directory that was set for the particular schedule. The GUI lets you select from any directory that is listed under
opreports_output_dirs 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
.2 and so on. This de-clashing also applies to your custom report name!
Old one-off reports are pruned based on the configuration setting
default_report_keep_for, subsection one-off (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 one-off 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:
Most of its options correspond closely to the ones described on the page on Scheduling Reports.
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.8 ... usage: ./opreports-cli.pl type=<report type> days=<N> from=<HH> to=<HH> start_date=<date_time> end_date=<date_time> node_group=<NMIS_GROUP>|All|Each group_regexp=<regexp> node_regexp=<regexp> node_intf_regexp=<regexp> node=NAME1 [node=NAME2 node=NAME3...] node_intf_list=<listfile> node_list=<listfile> node_intf_type_list=<listfile> firstname.lastname@example.org [email@example.com...] output_file_<html|csv|xlsx>=<path>... output_dir=<path> format=<html|csv|xlsx> [format=...] actual_name=<report file name> target_audience_group=NMIS_GROUP options.<optname>=<value>... type: the report to create, (availability|avgcpu|buffer|capacity|config|freemem|groupedav|groupedcap|health|jcos|mempool|node |qos|response|snapshot|summary|unicastpacket|uptime|usage|util|wan|wan_util_dist,wan_util_dist_sum) node_regexp: a regular expression for matching the node name (not with group) node_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 target_audience_group: limits viewing in the GUI to members of this group
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!
Precise Output Selection
To generate a report in a format X (html, csv, xlsx), use the options
output_file_N (N being a number); e.g.
format_1=html output_file_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"). If you choose separate output directories, then the resulting report cannot be visible in the GUI.
output_file_N option value must be a full path pointing to the file to create or replace. Please note that opreports-cli overwrites existing files without warning!
Report formats csv and html can also be printed to stdout, using
output_file_N=- (minus sign); Please note that this can not work for xlsx, only one format can be sent to stdout, and such reports cannot be visible in the GUI.
Simplified Output Selection
In versions 3.0.10 and newer, there is an optional, simpler mechanism for setting up outputs:
- Pass the option
output_dir=<your desired target directory>,
- pass the option
actual_name=<the short file name>,
- and pass one or more
format_X options, e.g.
and opReports will automatically name the files suitably and put them in the given output directory.
In addition to file-based outputs you can also specify email recipients using the
firstname.lastname@example.org,email@example.com option. Please note that a file-based output setup 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:
output_file_Noptions must point to the same directory, and it must be one of the configured report directories (or the one-off report directory).
If you use the simplified setup with
output_dir, then that must be one of the configured report directories.
Output to STDOUT (using
output_file_1=-) is not allowed in this situation.
- All the relative file names given in
output_Nmust be identical (but for the extension).
format_1=HTML output_file_1=/usr/local/omk/var/reports/testme.html format_2=XLSX output_2=/usr/local/omk/var/reports/testme.xlsx
whereas this doesn't:
- You must add the option
actual_name=<the name of your report files minus extension>.
For the example from step 2 this would be
- You must add the option
The uuid should follow the UUID V4 standard format , but any globally unique string will do.
You can use the
uuidprogram to create a a proper uuid.
- If you want your report to be treated as an instance of a scheduled report, then you must pass the schedule's
- If you want report aging, then you have to add a
If any of the requirements 1 to 5 are not met, then no report metadata json file is created and the GUI will not pick up the manually created report.
In version 3.0.7 and newer, the opReport scheduler logs the actual command line arguments that it uses for generating reports, which should provide a good example of how the parameters line up.
Overview of opreports-cli parameters
What report to generate. Required.
|The period the report should span.|
End date defaults to now, days defaults to 7.
|Business-hour/Business-week reporting. Optional.|
Business week selection is supported in opReports version 3.0.8 and above.
|Node selection by group name. All means one combined report, Each means one report per group.|
|group_regexp=<regexp>||Group selection by regular expression.|
node_regexp=<regexp> AND node_intf_regexp=<regexp> are also required when group_regexp=<regexp> is provided.
|Node selection by name, either by regular expression or as a list of explicitly given node names.|
|node_intf_regexp=<regexp>||Interface selection by regular expression. node_regexp=<regexp> is also required when node_intf_regexp=<regexp> is provided.|
|Node selection by list file. |
See How to select Nodes (and Interfaces) for reporting in opReports 3 for file formats and details.
|What formats to generate and where to store the resulting files. |
At least one format must be selected.
|email=<address,address,...>||Optional recipients of the report. Only the selected output formats are emailed out.|
|target_audience_group=<group>||If set, only members of this NMIS group can see the report in the GUI. Optional.|
|actual_name=<report file name>||The base name shared by all output files for this report instance. Required for GUI visibility.|
|actual_uuid=<uuid>||The globally unique identifier for this report instance. Required for GUI visibility.|
|uuid=<uuid of a report schedule>||The unique identifier of the report schedule this report should be marked as belonging to. Optional.|
|keep_for=<N>||How many days to keep this report instance. Optional.|
|title=<text>||Custom report title. Optional.|
|description=<text>||Custom report description. Optional.|
|homelink=<html text>||Custom report header for HTML output. Optional.|
|debug=N|verbose|true||If set, more verbose debug logging and output is produced. Optional. N can take values 1 to 9.|
|Optional parameters that are specific to particular report types.|
Please see the Report Types page for details.
If set to an NMIS property name, the node's value for this property will be used for displaying the node's name. Optional.
If the option is not set or if the given property is not present for a particular node, the node's plain name is shown.
If set to an NMIS interface property name, that interface's value for this property is used for displaying the interface name. Optional.
|pages.*=<value>||Page definition for Traffic Snapshot report (in opReports 3.0.14 and up).|
These parameters describe a deep structure, serialised in dot-notation. Please check the Report Types page for details.