Filtering and searching events
The Events section of the KUMA web interface does not show any data by default. To view events, you need to define an SQL query in the search field and click the Run query button. The SQL query can be entered manually or it can be generated using a query builder.
Data aggregation and grouping is supported in SQL queries.
You can search for events across multiple storages. For example, you can find events to determine where a user account is being blocked or which IP addresses were used to log in to which URLs. Example query for finding a blocked user account:
SELECT * FROM `events` WHERE DestinationUserName = 'username' AND DeviceEventClassID = '4625' LIMIT 250
To search for events in multiple storages, in the drop-down list in the upper-right part of the Events section, select check boxes next to the storages you want to search.
The list displays the following storages:
- Storages of the Main tenant.
- Available storages of tenants that satisfy one of the following conditions:
- The tenant that owns the storage is enabled in the tenant filter and the user has permissions to read events in this tenant.
- The user has access to the tenant of one of the partitions of the storage and has permissions to read events in this tenant.
For example, if you have access to the collector tenant, but do not have access to the storage tenant, by default, the inaccessible tenant's storage is not displayed in the list of available storages. If a destination in the storage of a tenant that is not available to you is added to the collector of an available tenant, after an event arrives in the partition of the tenant of the collector, the storage of the unavailable tenant appears in the list of storages in the Events section.
The drop-down list of storages in the upper-right part of the Events section displays the name of the first of the selected storages and the number of selected storages, if there are several. You can hover over the drop-down list to display all of the selected storages. If a space in a storage is deleted, the storage drop-down list shows "deleted<ID of deleted space>", and the events remain searchable for the duration of the TTL.
The tenants selected in the tenant filter affect which storages are displayed in the drop-down list of storages. If you disable tenants whose storages are available to you in the tenant filter, these storages are no longer displayed in the drop-down list of storages. If these storages had been selected in the drop-down list of storages, their check boxes are cleared and events from these storages are not displayed. If only one storage is selected in the drop-down list of storages that is not from the Main tenant, and if in tenant selection you disabled the tenant that owns the selected storage, this storage is not displayed in the list of storages and KUMA automatically changes the selection to one of the storages of the Main tenant.
A simple query to all selected storages is allowed, as in the example above. If at least one of the selected storages is not available for the query, KUMA returns an error.
Limitations for searching events across multiple storages:
- When querying multiple storages, export to TSV, retroscan, or REST API requests are not available.
- A SELECT can contain only * and/or names of event fields. Aliases, functions, expressions are not allowed.
- An ORDER BY clause must also contain only event fields (no functions, constants, expressions, and so on). If a field is not present in the list of fields for the SELECT, such a field is automatically added when sending to a specific cluster. You cannot set an ORDER BY ClusterID.
- GROUP BY is not available.
Complex queries with grouping and aggregation are allowed for a single selected storage.
You can add filter conditions to an already generated SQL query in the window for viewing statistics, the events table, and the event details area:
- Changing a query from the Statistics window
To change the filtering settings in the Statistics window:
- Open Statistics details area by using one of the following methods:
- In the
drop-down list in the top right corner of the events table select Statistics. - In the events table click any value and in the opened context menu select Statistics.
The Statistics details area appears in the right part of the web interface window.
- Open the drop-down list of the relevant parameter and hover your mouse cursor over the necessary value.
- Use the plus and minus signs to change the filter settings by doing one of the following:
- If you want the events selection to include only events with the selected value, click the
icon. - If you want the events selection to exclude all events with the selected value, click the
icon.
As a result, the filter settings and the events table will be updated, and the new search query will be displayed in the upper part of the screen.
- Changing a query from the events table
To change the filtering settings in the events table:
- In the Events section of the KUMA web interface, click any event parameter value in the events table.
- In the opened menu, select one of the following options:
- If you want the table to show only events with the selected value, select Filter by this value.
- If you want to exclude all events with the selected value from the table, select Exclude from filter.
As a result, the filter settings and the events table are updated, and the new search query is displayed in the upper part of the screen.
- Changing a query from the Event details area
To change the filter settings in the event details area:
- In the KUMA web interface, in the Events section, click the relevant event.
The Event details area appears in the right part of the window.
- Change the filtering settings by clicking the plus or minus icons:
- If you want to apply the filter instantly and update the events table, click
or
next to the parameters that you need. - If you want to continue to change filtering parameters, hold down the Ctrl key and click
or
. This adds the condition to the body of the query, but does not automatically run the query.When adding a condition to the query, an expression for the selected parameter is added to the WHERE
clause. When adding conditions for multiple parameters, the expressions are joined with the AND
operator. A field to be filtered by is added to the SELECT
clause only if the *
character is not used in the query.
Example:
Original query:
SELECT *
FROM `events`
ORDER BY Timestamp DESC
LIMIT 10
All events are selected without filters, the last 250 events are displayed in descending order by the Timestamp field.
When adding new conditions by Ctrl-clicking the icon, the query looks like this:
SELECT *
FROM `events`
WHERE DeviceProduct = 'Windows' AND StartTime = 1755767943436
ORDER BY Timestamp DESC
LIMIT 250
Conditions are added to the WHERE clause with the AND operator. Fields are not added to the SELECT clause because it contains the * character. The query is not run automatically.
|
- After adding all the necessary filtering conditions, run the query in one of the following ways:
- Add the last condition without holding down the Ctrl key. The query is run automatically.
- Close the event details area and run the query manually by clicking Run query button or pressing Ctrl+Enter.
The filter settings and the events table are updated, and the modified search query is displayed in the upper part of the screen.
After modifying a query, all query parameters, including the added filter conditions, are transferred to the query builder and the search field.
When you switch to the query builder, the parameters of a query entered manually in the search field are not transferred to the builder, so you will need to create your query again. Also, the query created in the builder does not overwrite the query that was entered into the search string until you click the Apply query button in the builder window.
In the SQL query input field, you can enable the display of control characters.
You can also filter events by time period. Search results can be automatically updated.
The filter configuration can be saved. Existing filter configurations can be deleted.
Filter functions are available for users regardless of their roles.
When accessing certain event fields with IDs, KUMA returns the corresponding names.
For more details on SQL, refer to the ClickHouse documentation. For SQL operators and functions supported in KUMA, see also the KUMA operator usage and supported functions.
Page top