Updated documentation of Hawat`s Timeline pluggable module.

(Redmine issue: #3361)

doc/sphinx/_doclib/hawat_plugin_timeline.rst

@@ -97,8 +97,8 @@ API endpoint: **search**
 The URL for web API interface is available as normal endpoint to the user of the web
 interface. This fact can be used to debug the queries interactively and then simply
 copy them to another application. One might for example start with filling in the
-search form in the ``/events/search`` endpoint. Once you are satisfied with the
-result, you can simply switch the base URL to the ``/api/events/search`` endpoint
+search form in the ``/timeline/search`` endpoint. Once you are satisfied with the
+result, you can simply switch the base URL to the ``/api/timeline/search`` endpoint
 and you are all set.
 
 
@@ -263,6 +263,30 @@ Following parameters may be specified as standard HTTP query parameters:
     * *Description:* Invert class selection
     * *Datatype:* ``boolean``
 
+``aggregations``
+    * *Description:* List of statistical aggregations to perform, default is empty and will perform all
+    * *Datatype:* ``list of strings ['categories','']``
+    * *Default:* ``[]``
+
+    (mentat.stats.idea.ST_SKEY_CATEGORIES,  {}, {"aggr_set": "category"}),
+    (mentat.stats.idea.ST_SKEY_IPS,         {}, {"aggr_set": "source_ip"}),
+    #('', {"aggr_set": "target_ip"}),
+    (mentat.stats.idea.ST_SKEY_SRCPORTS,    {}, {"aggr_set": "source_port"}),
+    (mentat.stats.idea.ST_SKEY_TGTPORTS,    {}, {"aggr_set": "target_port"}),
+    (mentat.stats.idea.ST_SKEY_SRCTYPES,    {}, {"aggr_set": "source_type"}),
+    (mentat.stats.idea.ST_SKEY_TGTTYPES,    {}, {"aggr_set": "target_type"}),
+    (mentat.stats.idea.ST_SKEY_PROTOCOLS,   {}, {"aggr_set": "protocol"}),
+    (mentat.stats.idea.ST_SKEY_DETECTORS,   {}, {"aggr_set": "node_name"}),
+    (mentat.stats.idea.ST_SKEY_DETECTORTPS, {}, {"aggr_set": "node_type"}),
+    (mentat.stats.idea.ST_SKEY_ABUSES,      {}, {"aggr_set": "cesnet_resolvedabuses"}),
+    (mentat.stats.idea.ST_SKEY_CLASSES,     {}, {"aggr_set": "cesnet_eventclass"}),
+    (mentat.stats.idea.ST_SKEY_SEVERITIES,  {}, {"aggr_set": "cesnet_eventseverity"}),
+
+``limit``
+    * *Description:* Perform toplisting for address and port statistics
+    * *Datatype:* ``integer [1..1000]``
+    * *Default:* ``100``
+
 *Common query parameters*
 
 ``submit``
@@ -289,6 +313,12 @@ Parameters ``page``, ``limit`` and ``sortby`` are not supported.
 JSON document, that will be received as a response for the search, can contain
 following keys:
 
+``aggregations``
+    * *Description:* This subkey is present in case search was successfull. It contains
+      list of all aggregations that were actually performed.
+    * *Datatype:* ``list``
+    * *Default: ``["categories", "ips", "source_ports", "target_ports", "source_types", "target_types", "protocols", "detectors", "detector_types", "abuses",  "classes", "severities"]``
+
 ``form_data``
     * *Description:* This subkey is present in case search operation was triggered.
       It contains a dictionary with all query parameters described above and their
@@ -313,21 +343,17 @@ following keys:
       * ``count`` - Number of statistical datasets used to calculate this result dataset
       * ``dt_from`` - Lower time boundary of the result dataset
       * ``dt_to`` - Upper time boundary of the result dataset
-      * ``stats_external`` - Separate statistics calculated for events from external networks
-      * ``stats_internal`` - Separate statistics calculated for events from internal networks
-      * ``stats_overall`` - Overall statistics
       * ``timeline_cfg`` - Pre-calculated optimized timeline configurations
 
-      Each of the ``stats_*`` subkeys may in turn contain following subkeys: ``abuses``,
-      ``analyzers``, ``asns``, ``categories``, ``category_sets``, ``classes``, ``countries``,
-      ``detectors``, ``detectorsws``, ``ips``, ``severities``. Each of these subkeys
-      represents aggregation of events by particular attribute. Additionally there
-      are following counters: ``cnt_alerts`` and ``cnt_events`` (synonyms, total number
-      of original events), ``cnt_recurring`` (number of recurring events) and ``cnt_unique``
-      (number of new unique events). Finally there is a ``timeline`` subkey, which contains
+      Additionally there are following subkeys: ``abuses``, ``categories``, ``classes``,
+      ``detectors``, ``detector_types``, ``ips``, ``protocols``, ``severities``,
+      ``source_ports``, ``source_types``, ``target_ports``, ``target_types``.
+      Each of these subkeys represents aggregation of events by particular attribute.
+      Additionally there is a counter ``cnt_events`` (total number of original events),
+      which is an integer. Finally there is a ``timeline`` subkey, which contains
       eveything that was described so far, but rendered to the timeline.
 
-    * *Datatype:* ``list of dictionaries``
+    * *Datatype:* ``dictionary``
 
 ``items_count``
     * *Description:* This subkey is present in case search operation was triggered.