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.
The following objects can be referenced from a scripted report:
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).
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.
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.
The following classes are defined in the environment of a scripted report:
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.
Query(String table, String view,
String select, String filter,
String period, int interval, String sort,
boolean decreasingOrder,
boolean sortPerInterval, int n,
boolean allowNullKeys = false)
Query.run()
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, allowNullKeys).
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.
allowNullKeys if false,
then when running a query, if any of the key fields evaluate to
null, then the traffic associated with this
field will be discarded. This is normally the most useful setting;
this parameter to the query is optional, if not specified it will default
to false. However, setting it to true
alows a null value to be selected, which may be useful if you are trying to
view traffic which specifically has null values (eg if an IP address is
selected from layer 2 traffic).
Query.run().
Runs the query, returning a Table.
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();
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])
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.1.5.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.1.5.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.1.5.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.
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 */
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 */
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.
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());