Creating widgets from a Kusto Query Language (KQL) data source

Use Kusto Query Language (KQL) to fetch event and alert data from the database.

1. Click Configure dashboard.

   The Configure dashboard screen displays a library of available widgets, with details about each widget.

2. Click Create new widget.
3. On the New Dashboard Item page, enter a name and a description for the widget.
4. In the Query section, select KQL from the data source list and enter a KQL query.

   Example 1

   The following KQL query returns the total number of events and the total number of unparsed events over the last hour. Using these numbers, it calculates the percentage of unparsed events to provide insight into how much of your data is being normalized. The results could be displayed in a pie or bar chart:

   events
       | project event_uuid, low_level_categories, original_time
       | where original_time > ago(1h)
       | mv-expand category=low_level_categories to typeof(int)
       | summarize TotalEvents=count_distinct(event_uuid), UnparsedEvents=count_distinctif(event_uuid, category > 10000 and category < 11000)
       | project TotalEvents, UnparsedEvents, PctUnparsed=(UnparsedEvents/TotalEvents)*100

   Example 2

   The following KQL query returns the total number of events with a severity greater than 8, by user, over the last hour. The results could be displayed in a time series chart:

   events
   | project
       unix_time=original_time,
       severity,
       User =user_id,
       Time=bin(unix_time, 60)
   | where unix_time > ago(1h) and severity > 8 and isnotempty(User)
   | summarize Events=count() by User, Time
   | order by Time, Events desc

5. Optional: Add parameters to the KQL query. Using common parameters and default values can reduce the time that it takes to create or edit individual queries for your widgets.
   • To insert existing parameters into the statement, click the Insert Parameter icon, and then click Insert for each parameter.
   • To add a parameter to your workspace, click Add, give the parameter a name and default value and then click Save.

     After you add parameters to a widget on a dashboard for the first time, the Parameters card appears on the dashboard. If you remove parameters from the widget, and no other widget in that dashboard uses the parameter, the Parameters card disappears.

   • To change the default value of the parameter, click the View Parameters icon, and click Save after you set the default value.

     When you change the default value for a parameter, you're changing the value everywhere the parameter is used in your workspace. However, if you set the value as the default, the current session value also uses that value. If you don't set the value as the default value, the updated change applies only to the current session.

   • The predefined SYSTEM:accountId parameter returns the account ID of the user who is logged in. The parameter is read-only and you cannot change the default value.
   • The predefined SYSTEM:time range parameter enables the user to use a time selector to display a particular time range in time-based charts on the dashboard. The following table compares examples of KQL queries that contain time criteria using specific time ranges versus using the SYSTEM:time range parameter:

     Table 1. Examples of KQL statements that contain time criteria, using the current relative time range and the SYSTEM:timerange parameter

     KQL examples that contain a specific time range	KQL examples that contain the SYSTEM:time range parameter
     events_all | where  original_time > ago(1h)  | summarize dcount(data_source_id)	events_all | where  original_time {SYSTEM:timerange}  | summarize dcount(data_source_id)
     events_all | where  original_time between( ago(2h) .. ago(1h) )  | summarize dcount(data_source_id)	events_all | where  original_time {SYSTEM:timerange}  | summarize dcount(data_source_id)
     events_all | where  original_time > ago(2h) and original_time < ago(1h)  | summarize dcount(data_source_id)	events_all | where  original_time > {SYSTEM:timerange:start} and original_time < {SYSTEM:timerange:end}  | summarize dcount(data_source_id)

6. Click Run Query.
   When you first create the widget, you can't configure charts if no data results are returned. Change the criteria in the fields to be less strict and run the query again.
7. In the Views section, create a dashboard chart.
   Because you can create multiple views and charts from the same query, give the view a unique name. By default, the chart's title and status on the title bar are displayed; to hide them, click the More options icon and switch the settings to Off.
8. Select a chart type and configure the properties. For use cases to help you decide which chart type to use, see Widget chart types.

   Chart type	Instructions
   Bar	Creating a bar chart
   Big Number	Creating a big number chart
   Geographic	Creating a geographic chart
   Pie	Creating a pie chart
   Scatter	Creating a scatter chart
   Tabular	Creating a tabular chart
   Time Series	Creating a time series chart

9. Preview how the chart looks and then click Save.
   Tip: The labels for the chart come from the queries that are used. If they are unintelligible in the preview, edit the labels in the View section.