Events widget

You can use the Events widget to get analytics based on SQL queries.

When creating this widget, you must specify the settings described in the tables below.

General tab

The following table describes the settings on the General tab.

Description of parameters

Setting	Description
Graph	Graph type. The following graph types are available: Pie chart. Bar chart. Counter. Line chart. Table. Date Histogram. Stacked Bar chart Speedometer chart
Format	Data display format: Absolute values or Relative values, %. The setting is available for a Stacked Bar chart. If you select the Absolute values format, the heights of the bars correspond to the sum of the values of the measured indicator. If you select the Relative values, % format, all bars have the same height of 100%, and the relative heights of colored zones on the bars correspond to the ratios of indicator values. By default, Absolute values is selected.
Timeline view	Time data display format: Bar chart or Line chart. This setting is available for charts of the Date Histogram type. When you select the Bar chart format, the data is displayed as vertical bars by default. If the SQL query contains an additional field with the `category` alias, the chart becomes a stacked bar chart, that is, each bar is divided into stripes in accordance with the values of this field. When you select the Line chart format, the data is displayed as one or more (depending on the query) polylines drawn through points on the time axis. The Bar chart format is selected by default.
Tenant	The tenant for which data is displayed in the widget. You can select multiple tenants. By default, data is displayed for tenants selected in layout settings.
Time period	Period for which data is displayed in the widget. The default is As layout, meaning that data is displayed for the period selected for the layout. You can also specify a period for the widget in one of the following ways: Select the exact start and end date and time of the period in the calendar and click Apply. Select a period relative to the present time in the Relative period list. Specify a value manually: select an exact date and time or a relative period, or a combination of both. For details, see the Configuring a period subsection below.
Show data for previous period	Enable the display of data for two periods at the same time: for the current period and for the previous period. When using a Stacked Bar chart, the Show data for previous period setting is taken into account if the query contains standard aliases: `value`, `category`, `metric`. However, if instead of the standard `metric`, the query uses a custom metric calculation with non-standard aliases, the Show data for previous period is not taken into account.
Available variables	Local or global variables that you can use to filter widget data. Click Add. If you are adding a local variable, enter an arbitrary name for the variable, then enter the value of the variable. If you are adding a global variable, in the list, select the name of the variable that you specified in the dashboard properties.
Storage	Storage that is searched for events. The list displays the available spaces. You can select only one storage, but you can select one or more spaces. The values in the Storage field are independent of the selected tenants in the Tenant field. The field displays storages and spaces, like in the Events section. When a new space is created in the storage, this new space is not selected by default in the widget settings. You must manually select the new space. If the user has access to all spaces listed in the widget, the widget can display the event information for tenants specified in the space set in the user's permissions. If the user does not have access rights to one or more spaces of the storage, the widget cannot display information; the user cannot edit the widget, but can duplicate the widget using the Duplicate button. Duplication does not depend on access rights to spaces. If a template is duplicated in widgets that have spaces specified that are not accessible to the user, the value in the Storage field is reset. Such widgets display an error: Access denied (Operation returns no results because of allowed and selected event spaces). To save the template, you need to specify spaces in widgets. In widgets that have spaces that are accessible to the user, the value of the Storage field is not reset and is saved when the template is duplicated. When the user downloads the template, the data of inaccessible files are hidden in the downloaded file. If the user's email address is included in the list of recipients of the scheduled report, the user gets the full version of the report, regardless of which spaces are accessible.
SQL query field	Query for filtering and searching for events manually. You can create a query in Builder by clicking Use SQL builder. You can use extended event schema fields to create a chart of the table type. Example with extended schema fields Prerequisite: Events are coming from a FWSaaS system. 10.08.2023 12:12:12 src=10.10.10.10 ReqUrls=[https://google.com, https:/ya.ru] 10.08.2023 12:12:23 src=10.10.10.20 ReqUrls=[https://google.com, https:/yndex.ru] 10.08.2023 12:12:33 src=10.10.10.30 ReqUrls=[https://google.com, https:/ya.ru, https://mail.ru] The KUMA General administrator has added an extended event schema field in KUMA in the Settings → Other → Advanced event schema fields section. At the KUMA normalizer, field mapping is configured for the ReqUrls and SA.urls fields. In KUMA, normalized events look as follows: DeviceReceiptTime=10.08.2023 12:12:12 SourceAddress=10.10.10.10 SA.urls=[https://google.com, https:/ya.ru] DeviceReceiptTime=10.08.2023 12:12:23 SourceAddress=10.10.10.20 SA.urls=[https://google.com, https:/yandex.ru] DeviceReceiptTime=10.08.2023 12:12:30 SourceAddress=10.10.10.30 SA.urls=[https://google.com, https:/ya.ru, https://mail.ru] You want to build a "Top URLs for 30 minutes" dashboard. Here is an example of a request in the Events section and in widgets: SELECT res.1 AS url, res.2 AS count FROM ( SELECT arrayJoin(groupArray((url, count))) AS res FROM ( SELECT url, count() AS count FROM ( SELECT SA.urls AS urls FROM `events` ) ARRAY JOIN urls AS url GROUP BY url ) GROUP BY url ) Result: url count google.com 3 ya.ru 2 mail.ru 1 yandex.ru 1 You can use variables in the SQL query. You can specify variables only when creating the query manually. You cannot use variables in the SQL builder. Example with variables Example SQL query with a local variable: `SELECT count(ID) AS 'metric', Name AS 'value', TenantID AS 'category' FROM 'events' WHERE filter(Name = $Name) GROUP BY Name, TenantID ORDER BY metric DESC LIMIT 250` This query uses the local variable `$Name`. Value of the Name event field are substituted into this variable. You can apply the variable by clicking the funnel icon () on the widget. This opens a window; in that window, you can specify a value for the variable. The widget filters the selection by the selected value of the Name field. Note that if in the SQL query you specify a variable for a field that takes a numeric value, such a value must be converted to a string. You can do this using the `toString` function. Otherwise, the SQL query returns an error. Example: SELECT count(ID) AS `metric`, SourcePort AS `value` FROM `events` WHERE (filter(toString(SourcePort) like $SourcePort)) GROUP BY SourcePort ORDER BY value ASC LIMIT 250 In this query, the SourcePort event field has a numeric value, therefore it is converted to a string: `toString(SourcePort)`. For detailed information on creating an SQL query in the query constructor, see below. The following limitations apply: The `metric` and `value` aliases in SQL queries cannot be edited for any type of event analytics widget, except tables. Aliases in widgets with charts of the Table type can contain Latin and Cyrillic characters, as well as spaces. When using spaces or Cyrillic, the alias must be enclosed in quotation marks: `"An alias with a space"`, `Another alias`. `ARRAY JOIN` SQL queries are not supported. When displaying data for the previous period, sorting by the `count(ID)` parameter may not work correctly. We recommend sorting by the `metric` parameter. For example, SELECT count(ID) AS "metric", Name AS "value" FROM `events` GROUP BY Name ORDER BY metric ASC LIMIT 250. In widgets with charts of the Counter type, you must specify the method of data processing for the values of the `SELECT` function: `count`, `max`, `min`, `avg`, `sum`. In widgets with charts of the Table type, the gradient is drawn based on the values of a number or time field (for example, `Timestamp`) specified in the SQL query. This field can be selected from the Field for gradient indicator drop-down list (if the query contains multiple number or time fields, any one of these can be selected). After this, the cells of the selected column are highlighted with gradient fill markers. If a field is not present in the query, the Appearance tab does not display the Gradient and Field for gradient indicator fields.

Configuring a period

To configure the data display period, do one of the following:

If necessary, change the date and time in the Time period setting in one of the following ways:
- If you want to specify an exact date, in the calendar on the left, select the start and end date of the period and click Apply.
  You can select a date up to and including the current date. The date and time format depends on your browser settings. If the Date from or Date to field has a value and you have not edited the time value manually, when you select a date in the calendar, the Date from field is automatically populated with 00:00:00.000, and the Date to field with 23:59:59.999. If you have manually deleted the value in the Date from or Date to field, when you select a date in the calendar, the field is automatically populated with the current time. After you select a value in one of the fields, the focus switches to the other field. If your Date to is earlier than your Date from, this earlier value is automatically inserted into the Date from field.
- If you want to specify a relative period, select one of the available periods in the Relative period list on the right.
  The period is calculated relative to the current time.
- If you want to specify a custom period, edit the value of the Date from and Date to fields.
  You can enter an exact date and time in the DD.MM.YYYY HH:mm:ss.SSS format for the Russian localization and YYYY-MM-DD HH:mm:ss.SSS for the English localization or a period relative to the current time as a formula. You can also combine these methods if necessary. If you do not specify milliseconds when entering the exact date, 000 is substituted automatically. If you have edited the time in the Date from or Date to fields, picking a date in the calendar does not change the time component.
  
  In the relative period formulas, you can use the now parameter for the current date and time and the interval parameterization language: + (only in the Date to field), -, / (rounding to the nearest), as well as time units: y (year), M (month), w (week), d (day), h (hour), m (minute), s (second). For example, you can specify the period now-5d to get data for the last five days, or now/w to get data from the beginning of the first day of the current week (00:00:00:000 UTC) to the current time (now).
  
  The Date from field is required, and its value cannot exceed the value of the Date from field, and also cannot be earlier than 1970-01-01 (if specifying an exact date or a relative period). The Date to cannot be earlier than the Date from. If you do not specify a value in the Date from field, now is specified automatically.
KUMA stores time values in UTC, but in the user interface time is converted to the time zone of your browser. This is relevant to the relative periods: Today, Yesterday, This week, and This month. For example, if the time zone in your browser is UTC+3, and you select Today as the data display period, data will be displayed for the period from 03:00:00.000 until now, not from 00:00:00.000 until now.

If you want to take your time zone into account when selecting a relative data display period, such as Today, Yesterday, This week, or This month, you need to manually add a time offset in the Date from and Date to fields (if a value other than now is specified) by adding or subtracting the correct number of hours. For example, if your browser's time zone is UTC+3 and you want to display data for Yesterday, you need to change Date from to now-1d/d-3h and Date to to now/d-3h. If you want to display data for the Today period, you only need to change the value in the Date from field to now/d-3h.

If you need results up to 23:59:59:999 UTC of yesterday, you can use an SQL query with a filter by Timestamp or specify an exact date and time.

The bounds of the period are inclusive: for example, for the Today time range, events are displayed from the beginning (00:00:00:000 UTC) of the current day to the current time (now) inclusive, and for the Yesterday period, events are displayed from the beginning (00:00:00:000 UTC) of the previous day to 00:00:00:000 UTC of the current day. You can view the date and time of the last data update and the exact period for which the data is displayed by hovering over the period icon in the widget.

If the Show data for previous period setting is enabled for the widget, and the widget is displaying data for a relative period, the tooltip also displays the previous period. The previous period is calculated relative to the current period as start and end values of the current period minus the duration of the current period. For example, if data is updated daily and displayed for a month, but only the first 10 days of the month have passed, the previous period is taken to be the last 10 days of the previous month.
If you want the widget to display data for the period selected for the layout, click the Reset button. Changing the displayed period on the layout also changes the period displayed in the widget.

How to create a query in Builder

To create a query in Builder:

Specify the values of the following parameters:
1. SELECT—event fields that should be returned. The number of available fields depends on the selected graph type.
  - In the drop-down list on the left, select the event fields for which you want to display data in the widget.
  - The middle field displays what the selected field is used for in the widget: metric or value.
    If you selected the Table graph type, in the middle fields, you must specify column names using ANSII-ASCII characters.
  - In the drop-down list on the right, you can select an operation to be performed on the data:
    - count—event count. This operation is available only for the ID event field. Used by default for line charts, pie charts, bar charts, and counters. This is the only option for date histogram.
    - max is the maximum value of the event field from the event selection.
    - min is the minimum value of the event field from the event selection.
    - avg is the average value of the event field from the event selection.
    - sum is the sum of event field values from the event selection.
2. SOURCE is the type of the data source. Only the events value is available for selection.
3. WHERE—conditions for filtering events.
  - In the drop-down list on the left, select the event field that you want to use for filtering.
  - Select the necessary operator from the middle drop-down list. The available operators depend on the type of value of the selected event field.
  - In the drop-down list on the right, enter the value of the condition. Depending on the selected type of field, you may have to manually enter the value, select it from the drop-down list, or select it on the calendar.
  You can add search conditions by clicking Add condition or remove search conditions by clicking .
  
  You can also add groups of conditions by clicking Add group. By default, groups of conditions are added with the AND operator, but you can change the it if necessary. Available values: AND, OR, NOT. Group conditions are deleted using the Delete group button.
4. GROUP BY—event fields or aliases to be used for grouping the returned data. This parameter is not available for Counter graph type.
5. ORDER BY—columns used as the basis for sorting the returned data. This parameter is not available for the Date Histogram and Counter graph types.
  - In the drop-down list to the left, select the value that will be used for sorting.
  - Select the sort order from the drop-down list on the right: ASC for ascending, DESC for descending.
  - For Table type graphs, you can add sorting conditions by clicking Add column.
6. LIMIT is the maximum number of data points for the widget. This parameter is not available for the Date Histogram and Counter graph types.
Click Apply.

Example of search conditions in the query builder

Axes tab

The following table describes the settings on the Axis tab.

The tab is displayed if on the General tab in the Graph field you have selected one of the following values: Bar chart, Line chart, Date Histogram.

Description of parameters

Setting	Description
Point size	Point size on the graph. This field is displayed for the Line chart graph type.
Line-width	Width of the line on the graph. This field is displayed for the Line chart graph type.
Minimum and maximum values for the Y-axis	Scale of the Y axis. Negative values can be displayed on chart axes. This is due to the scaling of charts on the widget and can be fixed by setting zero as the minimum chart values instead of Auto.
Minimum and maximum values for the X-axis	Scale of the X axis. Negative values can be displayed on chart axes. This is due to the scaling of charts on the widget and can be fixed by setting zero as the minimum chart values instead of Auto.
Decimals	Number of decimals to which the displayed value must be rounded off.

Appearance tab

The following table describes the settings on the Appearance tab.

Description of parameters

Setting	Description
Name	Name of the widget.
Description	Description of the widget.
Show legend	Displays a legend for the analytics. The toggle switch is turned on by default.
Show nulls in legend	Displays parameters with a null value in the legend for analytics. The toggle switch is turned on by default. Null values are displayed only when the Show data for previous period setting is enabled and there is no data for the current period, but there was some data for the previous period.
Color	The color used for displaying the information: default for your browser's default font color green red blue yellow This setting is available for graphs such as Bar chart, Counter, Line chart, Date Histogram.
Gradient	Gradient fill of the chart: Two colors (red and green) Three colors (red, yellow, and green) This setting is available for charts such as Bar chart, Date Histogram(with the Bar chart type), Table. You can adjust the direction of the fill by clicking the toggle direction icon (); you can also set thresholds. If not set manually, gradient thresholds are calculated automatically from the data. If there is no data between the specified thresholds, the gradient is not applied. Instead, two colors are used: one for values below the lower threshold, and the other for values above the upper threshold.
Field for gradient indicator	The column in which the gradient fill indicators are displayed. This setting is available for charts of the Table type.
Horizontal	Makes the histogram horizontal instead of vertical. When this option is enabled, when a widget displays a large amount of data, horizontal scrolling is not available and all available information is fit into the fixed size of the widget. If there is a lot of data to display, it is recommended to increase the widget size.
Show total	Shows sums total of the values.
Period segments length	Duration of the segments into which you want to divide the period. Available for graphs of the Date Histogram type.
Scale	Scale for displaying data. Available for a Stacked Bar chart. The following values are possible: Linear Square Logarithm The default is Linear.
Regression	An option for indicating the average value on the chart. The following values are possible: Not set Linear LOESS (curve with locally estimated scatterplot smoothing). Available for the Date Histogram and Line chart types.

Actions tab

Settings on this tab let you configure left-click actions on various elements of widgets, for example, on a chart segment or the text of a legend item. You can select the following actions:

Go to events.
Filter by variable.
The settings are described in the scenario for filtering data in multiple widgets.
Drill down to another dashboard.
The settings are described in the scenario for drilling down to another dashboard.

Page top