.. _Reports:

Traffic Reports
===============

When ClickHouse is enabled, a Reports page becomes available in the ntopng web GUI under the Dashboard > Reports menu.

This section describes how to use this functionality to build traffic reports on demand or automatically/periodically and get notified about their availability.

.. note::

   Historical Flows Explorer and Reports are only available ntopng Enterprise M or above with ClickHouse enabled.

Reports contain charts of monitored interfaces overall traffic, local versus remote traffic, local networks traffic, as well as the traffic grouped by:

- Application Protocols (e.g., HTTPS, Skype)
- Countries
- Local Hosts (hosts belonging to local networks) and Remote Hosts
- Autonomous Systems

The picture below shows an example of report generate by ntopng:

.. figure:: ../../img/report-preview.png
  :align: center
  :alt: Report Preview

  Report Preview

ntopng implements a flexible dashboarding engine that allows you to define custom reports by means of graphical components and data sources.
This means that multiple templates can be defined, according to the user requirements, to build reports with charts and data which is meaningful
for the specific user, network and use case. A dropdown at the top of the Reports page lets you select the desired template to be used to build
the report out of those available.

.. figure:: ../../img/report-templates.png
  :align: center
  :alt: Report Templates

  Report Templates

The report is build using traffic information in a selected time frame. It is possible to select an arbitrary time interval by using the
dropdown and the range picker at the top of the Reports page. Fixed-width temporal intervals are also available (e.g. for the last one hour,
day, weeek, etc.) producing a report that spans a time range that starts at the present and that goes backwards in time until the clicked 
interval is reached.

.. figure:: ../../img/report-time-interval.png
  :align: center
  :alt: Report Time Interval

  Report Time Interval

Save/Open Reports on ntopng
---------------------------

After selecting a report template and a time window, a report is generated and displayed. It is possible to save it by clicking on the
Save button.

.. figure:: ../../img/report-save-button.png
  :align: center
  :alt: Report Save Button

  Report Save Button

A dialog will ask for a name for the report. By clicking Save, the report is stored on disk the same machine running ntopng as a JSON file
containing all the information required to reload the same report in future for further analysis.

.. figure:: ../../img/report-save.png
  :align: center
  :alt: Report Save

  Report Save

In order to reload a previously-saved report, an Open button is available.

.. figure:: ../../img/report-open-button.png
  :align: center
  :alt: Report Open Button

  Report Open Button

A dialog will let you select the report, out of those previously saved in ntopng.

.. note:: 

   In case of multiple users, reports generated by an administrator is visible by all administrators, instead reports generated by a non-privileged user is visible only to
   the same user (and traffic visibility restrictions will apply according to the configured user permissions), and the non-privileged user cannot see reports generated by administrators.

Through the same dialog it is also possible to delete a report (the selected one) or all reports.

.. figure:: ../../img/report-open.png
  :align: center
  :alt: Report Open and Delete

  Report Open and Delete

.. warning::

   Reports are automatically deleted after some time according to the configured data retention. Please read the Data Retention section for further information.

Backup/Load Reports Locally
---------------------------

In addition to saving reports on the machine running ntopng, it is also possible to download a report locally to keep a backup or forward it to someone else.
In order to dowload a report backup click on the Download button. This will download a JSON file containing all the information required to reload the report
on the same or a different ntopng installation for visualization.

.. figure:: ../../img/report-download-button.png
  :align: center
  :alt: Report Download Button

  Report Download Button

In order to reload a report from a JSON file previously downloaded, click on the Upload button.

.. figure:: ../../img/report-upload-button.png
  :align: center
  :alt: Report Upload Button

  Report Upload Button

A dialog allows you to upload a report backup in JSON format and visualize it in ntopng. Please note this report is just visualized, no copy is stored on
the machine running ntopng. However it is also possible to save it by clicking on the Save button as described in the previous section. 

.. figure:: ../../img/report-upload.png
  :align: center
  :alt: Report Upload

  Report Upload

Print Report (PDF)
------------------

A print functionality is also available to actually print or generate a PDF from a reports, this is possible by clicking on the Print button.

.. figure:: ../../img/report-print-button.png
  :align: center
  :alt: Report Print Button

  Report Print Button

When printing a report the rendering engine does its best to fit all the graphical components in standard printing formats (e.g. A4).

.. figure:: ../../img/report-print.png
  :align: center
  :alt: Report Print

  Report Print

Automatic Reports and Notifications
-----------------------------------

In addition to the manual Report generation, automatic reports can also be enabled in ntopng. This means that ntopng can build
for instance daily reports every night, with traffic information for the last 24h.

.. note::

   Periodic Reports are only available in ntopng Enterprise L or above.

In order to enable this, a global setting is
available under Settings -> Preferences -> Reports -> Daily Reports Generation. 

.. figure:: ../../img/report-preferences-daily.png
  :align: center
  :alt: Automatic Report Preference

  Automatic Report Preference

By enabling Daily Reports Generation, ntopng generates a report for every interface, every day. It is possible to disable automatic
reports on selected interfaces through the Interface -> Details -> Settings -> Create Daily Reports setting, which is enabled by
default after enabling the global setting.

.. figure:: ../../img/report-interface-preferences-daily.png
  :align: center
  :alt: Automatic Report Interface Preference

  Automatic Report Interface Preference

When a new report has been generated and it is available, ntopng can also send a notification to inform the user, e.g. by sending an
email. In order to enable notifications, a Notification Endpoint and Recipient should be configured. In the Recipient configuration,
Traffic Reports should be selected as Notification Type.

.. figure:: ../../img/report-notifications-recipient.png
  :align: center
  :alt: Report Notification Recipient

  Report Notification Recipient

Below you can find an example of email notification sent by ntopng to notify the user about the availability of a new daily report,
with a direct link to go to the actual report.

.. figure:: ../../img/report-email-preview.png
  :align: center
  :alt: Report Email Notification Preview

  Report Email Notification Preview

Data Retention
--------------

All the reports stored on ntopng, both manually or automatically created, can be automatically deleted by ntopng after some time
in order to implement a data retention policy and avoid filling the disk due to the number of reports growing undefinitely.
There is a default data retention time configured in ntopng, this can be changed from the  Settings -> Preferences -> Reports -> 
Reports Data Retention section.

.. figure:: ../../img/report-preferences-retention.png
  :align: center
  :alt: Report Data Retention Preference

  Report Data Retention Preference


Reports Editor
--------------

The reports editor allows you to build custom reports by creating new templates.
A collection of widgets is available, they can be combined to define a template.

.. note::

   The Reports Editor is only available in ntopng Enterprise XL.


The Dashboard -> Traffic Report page includes a button in the toolbar to create
a new template, as shown in the picture below.

.. figure:: ../../img/report_editor_new_template_button.png
  :align: center
  :alt: New Template Button

  New Template Button

A dialog appears to configure the Template name.

.. figure:: ../../img/report_editor_new_template_dialog.png
  :align: center
  :alt: New Template Dialog

  New Template Dialog

After creating the new template, it becomes available and can be selected
from the reports selector dropdown. 

.. figure:: ../../img/report_editor_new_template_select.png
  :align: center
  :alt: Report Template Selector

  Report Template Selector

By seleting a new template, an empty report is shown as the template is
initially empty and need to be customized.

.. figure:: ../../img/report_editor_empty_template.png
  :align: center
  :alt: Empty Report Template

  Empty Report Template

A Template Editor toggle is available in the toolbox when a custom
template is selected. This allows you to enter the edit mode.

.. figure:: ../../img/report_editor_button.png
  :align: center
  :alt: Report Editor Button

  Report Editor Button

When entering the edit mode, a new toolbox for the Template Editor appears.
The toolbox includes buttons for adding Widgets to the template, or deleting
the template. By clicking on the Add Widget button, a dialog appears with a
list of available Widgets that can be added to the template.

.. figure:: ../../img/report_editor_widgets.png
  :align: center
  :alt: Report Widgets

  Report Widgets

When adding a Widget, this is appended to the template, with a default configuration.

.. figure:: ../../img/report_editor_sample.png
  :align: center
  :alt: Report Template

  Report Template

Widget can be organized and sorted by dragging and dropping them around.

.. figure:: ../../img/report_editor_drag.png
  :align: center
  :alt: Widgets Drag and Drop

  Widgets Drad and Drop

In edit mode, a few controls appear on the widgets themselves, including buttons
for editing the widget configuration or removing them from the template.

.. figure:: ../../img/report_editor_widget_actions.png
  :align: center
  :alt: Widget Actions in Edit Mode

  Widget Actions in Edit Mode

By clicking on the edit button on a widget, it is possible to configure them,
including changing:

- displayed title
- widget size (heigth and width)
- time reference (the Time Offset is used to show traffic information with a time shift with respect to the time selected for the report, e.g. show traffic information 1 week ago, to compare it with the current traffic)

.. figure:: ../../img/report_editor_edit.png
  :align: center
  :alt: Widget Settings

  Widget Settings

An Advanced Settings toggle is also available. This allows to deeply customize
the content of the Widget, by changing settings including the REST API URL and
parameters, which are encoded in JSON format.

Special tokens are also supported in the JSON configuration to dynamically pass
arguments to the widgets, e.g. $IFID$ is dynamically replaced with the current
interface ID selected in ntopng while rendering the report.

.. figure:: ../../img/report_editor_advanced_edit.png
  :align: center
  :alt: Widget Advanced Settings

  Widget Advanced Settings

Any change to the template is automatically saved (there is no Save button in
the template editor).

