16.5. Classes and objects defined within scripted reports

Scripted reports use a standard JavaScript environment to execute a script. Additional classes and objects are available within the script to allow the report to be generated. This section is a reference of the classes and objects available.

16.5.1. Objects defined

The following objects can be referenced from a scripted report:

16.5.1.1. report

Synopsis

report

Description

report is the single instance of the Report class available. The report object represents the current report being generated. Invoking any of the methods defined for the Report class on it will have the appropriate result on the report generated (for example, adding a chart).

Example

To add a table of results to a report, use the code

report.table(data);                        
                        

where data is the result of running a previous query.

16.5.1.2. reportVars

Synopsis

reportVars.variable

Description

reportVars is an object with a property defined for each of the report variables specified in the scripted report tab. The name of each property is the name of the variable, and the value of the property is the value defined for that variable. This allows the values of the defined variables to be used from within the report script.

Example

You might want to parameterize the timeframe for the report to run over. To do this, add a variable timeframe, and enter its value as "today". Then from within the report script, refer to this value by reportVars.timeframe; you would probably use this to specify the period for a query. When the report is run, it would generate data for today. If you then changed the variable value to lastHour, then the report would generate data for lastHour, without the script itself having to be changed.

16.5.2. Classes defined

The following classes are defined in the environment of a scripted report:

16.5.2.1. Chart

Synopsis
Chart.setWidth(int width)
Chart.setHeight(int height)
                    
Description

Chart is the class of a chart generated within a report. An instance of a chart is obtained as the return value of the chart and timeChart methods in Report. After a chart has been created, its size can be modified from the default using the setWidth and setHeight methods.

Example

To generate a chart (using the previous data from a query), and change its size, the code

var newChart = report.timeChart("lineChart", data, "sourceAddress, resolve(sourceAddress)",
                                "%1$s(%2$s", "rate(framesTotal)");
newChart.setWidth(1000);
newChart.setHeight(800);                                 
                        

16.5.2.2. Query

Synopsis

Query(String table, String view,
      String select, String filter,
      String period, int interval, String sort,
      boolean decreasingOrder,
      boolean sortPerInterval, int n)
      
Query.run()      
                        

Description

Query is the class which defines a query to run on the database. The methods are:

Query(table, view, select, filter, period, interval, sort, decreasingOrder, sortPerInterval, n). Creates a new Query. The parameters are:

  • table the database table to run the query on. Current valid tables are "flows", "counters", "hostCounters", "serviceCounters", "services", or "events".
  • view the view of the database table required. The view can be thought of as a specific perspective on the data. If the view is the empty string, then all data is included. If it is a list of IP addresses of switches/routers, then only data from these devices is included. If you only want data for one switch interface, then use a string of the form "switch>ifIndex", where switch is the IP address of the switch, and ifIndex the ifIndex of the interface. Finally, a set hosts can be specified. To do this, use a view of the form hosts(host1, host2,..). Each host can be specified by hostname or UUID.
  • select is a string containing a list of the database fields and functions required to select from the database for the query.
  • filter is a JavaScript filter for the query. if not required, leave as the empty string.
  • period the time that the query should run over. This is a string parameter, with values one of "last5Mins", "last10Mins", "last15Mins", "last30Mins", "lastHour", "last6Hours", "last12Hours", "last24Hours", "today", "yesterday", "thisWeek", "lastWeek" Additionally, arbitrary periods can be specified using dates of the form "yyyy-MM-dd HH:mm to yyyy-MM-dd HH:mm". The month and day are specified using digits, and the time is specified using 24-hour clock, for example "2012-10-05 10:00 to 2012-10-05 14:00" would run the query from 10:00 on October 5th, 2012 to 14:00 on the same day. The time is in the local timezone on the client.
  • interval the size of each bucket (in minutes) in the resulting data. If this is set to 0, then only one bucket will be created.
  • sort the field or function which to sort the data by. This field or function must have previously been included in the select statement. If no sorting is required, leave as the empty string.
  • decreasingOrder if true then the data will be sorted with the largest first, if false then the data is sorted smallest first.
  • sortPerInterval if true then sorting will be performed independently per bucket generated in the results. If a value is specified for n, then each bucket will have the top-n for that interval. If false, then the sort will be applied across all of the data in the period. If a value for n is specified, then the top-n is generated over the entire period.
  • n the number of entries to include in the results, before including everything else in an "other" entry. This is used to create top-n queries. If set to 0, then all data is returned. Note that including all data can make the query significantly slower, and use more memory.

Query.run(). Runs the query, returning a Table.

Example

To create a query on the flows table, for top 5 sources by total frames, over the last hour with 1 minute buckets, and then run it, use the code

var query = new Query("flows", "",
                      'timestamp("Timestamp", time), sourceAddress,\
                       resolve("Source name", sourceAddress), rate(framesTotal)',
                      "", "lastHour", 1, "rate(framesTotal)", true, false, 5);
var result = query.run();
                        

16.5.2.3. Report

Synopsis

Report.chart(type, data, categoryFields, categoryFormat, seriesFields, seriesFormat, valueFields [, title])
Report.paragraph(text)
Report.table(data [, title])
Report.timeChart(type, data, seriesFields, seriesFormat, valueFields [, title])
                    

Description

Report is the class of the current report object (see Section 16.5.1.1, “report”). The methods defined within Report allow data to be added to a report. The methods are:

chart(type, data, categoryFields, categoryFormat, seriesFields, seriesFormat, valueFields [, title]) creates a chart (note: not a time-based chart; for this, use a timeChart) in the report. The parameters are:

  • type a string representing the type of chart to be generated in the report. Current valid options are: "barChart", "stackedBarChart", "areaChart", "stackedAreaChart", "lineChart".
  • data a Table, which is obtained from running a query.
  • categoryFields a string containing a list of database key fields and key functions, which should form the categories to be displayed in the chart (ie on the x-axis). Each of the fields must be present in the data by selecting them in the query. The categories formed will be the combination of all of the specified fields in each row of the data. Note that this parameter is of type string, and any embedded strings within it (eg strings within database functions) must be correctly escaped to avoid JavaScript errors.
  • categoryFormat a format string which can be used to make the combination of the category fields more legible (see Section 9.2.2.3, “Editing a query using advanced settings”). If this parameter is empty, then the category fields will be presented as a comma-separated list.
  • seriesFields a string containing a list of database key fields and key functions, which should form the series to be displayed in the chart. Each of the fields must be present in the data by selecting them in the query. The series formed will be the combination of all of the specified fields in each row of the data. Note that this parameter is of type string, and any embedded strings within it (eg strings within database functions) must be correctly escaped to avoid JavaScript errors.
  • seriesFormat a format string which can be used to make the combination of the series fields more legible (see Section 9.2.2.3, “Editing a query using advanced settings”). If this parameter is empty, then the series fields will be presented as a comma-separated list.
  • valueFields a string containing a list of database value fields and value functions, which should form the values to be displayed in the chart. Each of the fields must be present in the data by selecting them in the query. Note that this parameter is of type string, and any embedded strings within it (eg strings within database functions) must be correctly escaped to avoid JavaScript errors.
  • title an optional title for the chart. if this parameter is not provided, then one will be generated automatically.

paragraph(text) inserts the string parameter text into the report, as an html paragraph. This can be used to add additional text to the report.

table(data [, title]) creates an html table containing the results in data. A row will be created in the html table for each row in data, and the columns of the table will be formed from each field present in data. title is an optional string parameter, used for the table title. If this is not present, then a title will be automatically generated.

timeChart(type, data, seriesFields, seriesFormat, valueFields [, title]) creates a time-based chart, with time on the x-axis. Note that for this chart to work, the timestamp(time) function (see Section 16.4.4.2, “timestamp”) must be present in the data, by including this function within the query select. The parameters are:

  • type a string representing the type of chart to be generated in the report. Current valid options are: "barChart", "stackedBarChart", "areaChart", "stackedAreaChart", "lineChart".
  • data a Table, which is obtained from running a query.
  • seriesFields a string containing a list of database key fields and key functions, which should form the series to be displayed in the chart. Each of the fields must be present in the data by selecting them in the query. The series formed will be the combination of all of the specified fields in each row of the data. Note that this parameter is of type string, and any embedded strings within it (eg strings within database functions) must be correctly escaped to avoid JavaScript errors.
  • seriesFormat a format string which can be used to make the combination of the series fields more legible (see Section 9.2.2.3, “Editing a query using advanced settings”). If this parameter is empty, then the series fields will be presented as a comma-separated list.
  • valueFields a string containing a list of database value fields and value functions, which should form the values to be displayed in the chart. Each of the fields must be present in the data by selecting them in the query. Note that this parameter is of type string, and any embedded strings within it (eg strings within database functions) must be correctly escaped to avoid JavaScript errors.
  • title an optional title for the chart. if this parameter is not provided, then one will be generated automatically.

Example

To generate a bar chart (using the previous data from a query, assuming that this data includes the fields sourceAddress and framesTotal), use the code

var newChart = report.chart("barChart", data,
                            "sourceAddress", "", /* Category fields, no need for category format */
                             "", "", /* No need for series */
                            "framesTotal"); /* values */
                        

Example

To generate a time based line chart (using the previous data from a query, assuming that this data includes the fields timestamp(time), sourceAddress and framesTotal), use the code

var newChart = report.timeChart("lineChart", data,
                                "sourceAddress", "", /* No need for series format */
                                "framesTotal"); /* values */
                        

16.5.2.4. Table

Synopsis

Table.getStart()
Table.getEnd()
Table.getInterval()
                    

Description

Table is the class of a database table created by running a query. After running a query, the instance of the Table returned is then used to create a chart or html table. The start and end times of the data contained within a Table can be obtained using the getStart() and getEnd() methods. getInterval() returns the time interval of the data, in milliseconds.

Example

To generate a table of data by running a query, use the code:

var query = new Query("flows", "",
                      'timestamp("Timestamp", time), sourceAddress,\
                       resolve("Source name", sourceAddress), rate(framesTotal)',
                      "", "lastHour", 1, "rate(framesTotal)", true, false, 5);
var data = query.run();
report.paragraph("Start of data: "+data.getStart());