Adding parameters to a workbook allows you to change values in your queries such as workspace without having to manually edit the query. This makes workbooks much easier to use and widens the potential audience.
Lets look at how to add parameters, some common ones and a little cheat sheet I use to quickly start a new workbook.
Adding Parameters
Parameters can be added into a KQL query by including the parameter name in braces, for example if I have a parameter for Time I can reference it in my KQL query as {Time}
There are currently four different supported parameters:
Text – An editable text box
Drop Down – Choose from a defined set of values
Time Range Picker – Choose from a predefined set of time range values
Resource Picker – Choose from resources selected for the workbook
Example Parameters for our Quick Start Template
Time
Adding a time parameter is relatively straight forward as it is a pre-defined parameter type, click add parameter and give it a name, select Time range picker from the type field and select the times ranges you want to be available. Then click Save
Subscription
Adding a subscription parameter is very useful as it allows your workbook to be able to query across subscriptions easily. After giving the parameter a name, choose Subscription picker from the type. Tick Allow multiple selection and also include the All option below then
you can select from Default Subscriptions and All Subscriptions. Then click save.
Workspace
Workspace is useful for the same reasons Subscription is, this will allow a workbook to easily query across multiple workspaces from a single location.
This one is a little more complex to configure as it you’ll need to reference the workspaces through a KQL query, there are several ways to do this and i’ll share the one I am currently using.
As before name your parameter, this time choose Resource picker, allow multiple selection and All as options and then select Get data from Query, set your source to Azure Resource Graph and Subscription, the query I use is below:
where type =~ ‘microsoft.operationalinsights/workspaces’
| order by name asc
| summarize Selected = makelist(id, 10), All = makelist(id, 1000)
| mvexpand All limit 100
| project value = tostring(All), label = tostring(All), selected = iff(Selected contains All, true, false)
Servers
Not all Workbooks will require Servers but I use it often enough that I include in my Quick Start Template. This time choose Drop down, as before allow Multiple selection and All. We are going to populate our list from a query and a simple way to get a list of Servers is:
Heartbeat
| distinct Computer
Once you have saved this workbook with your populated parameters it is now a simple matter to reuse this every time we want to create a new workbook with parameters. All you need to do is edit this one and Save As to start a fresh workbook with pre-done parameters.
Json Template
Below is the template to create your own easy quick start workbook, just create a blank one and paste the json code into the Advanced Editor in the Gallery Template section and click apply.
{
“version”: “Notebook/1.0”,
“items”: [
{
“type”: 9,
“content”: {
“version”: “KqlParameterItem/1.0”,
“query”: “”,
“crossComponentResources”: [
“{Subscription}”
],
“parameters”: [
{
“id”: “ff24505c-2099-43a4-a8a3-3456bed78eb5”,
“version”: “KqlParameterItem/1.0”,
“name”: “TimeRange”,
“type”: 4,
“isRequired”: true,
“value”: {
“durationMs”: 604800000
},
“typeSettings”: {
“selectableValues”: [
{
“durationMs”: 3600000
},
{
“durationMs”: 14400000
},
{
“durationMs”: 43200000
},
{
“durationMs”: 86400000
},
{
“durationMs”: 172800000
},
{
“durationMs”: 259200000
},
{
“durationMs”: 604800000
},
{
“durationMs”: 1209600000
},
{
“durationMs”: 2419200000
},
{
“durationMs”: 2592000000
},
{
“durationMs”: 5184000000
},
{
“durationMs”: 7776000000
}
]
}
},
{
“id”: “bfe50469-7469-4c4d-a33e-0edbb43546c4”,
“version”: “KqlParameterItem/1.0”,
“name”: “Subscription”,
“type”: 6,
“isRequired”: true,
“multiSelect”: true,
“quote”: “‘”,
“delimiter”: “,”,
“value”: [
“value::all”
],
“typeSettings”: {
“additionalResourceOptions”: [
“value::all”
],
“includeAll”: true
}
},
{
“id”: “fb861784-4609-49f2-9f58-427fcc547677”,
“version”: “KqlParameterItem/1.0”,
“name”: “Workspace”,
“type”: 5,
“isRequired”: true,
“multiSelect”: true,
“quote”: “‘”,
“delimiter”: “,”,
“query”: “where type =~ ‘microsoft.operationalinsights/workspaces’\r\n| order by name asc\r\n| summarize Selected = makelist(id, 10), All = makelist(id, 1000)\r\n| mvexpand All limit 10000\r\n| project value = tostring(All), label = tostring(All), selected = iff(Selected contains All, true, false)”,
“crossComponentResources”: [
“{Subscription}”
],
“value”: [
“value::all”
],
“typeSettings”: {
“resourceTypeFilter”: {
“microsoft.operationalinsights/workspaces”: true
},
“additionalResourceOptions”: [
“value::all”
]
},
“timeContext”: {
“durationMs”: 0
},
“timeContextFromParameter”: “TimeRange”,
“queryType”: 1,
“resourceType”: “microsoft.resourcegraph/resources”
},
{
“id”: “b2627475-cef7-4e91-97b9-b70bf00164e6”,
“version”: “KqlParameterItem/1.0”,
“name”: “Servers”,
“type”: 2,
“multiSelect”: true,
“quote”: “‘”,
“delimiter”: “,”,
“query”: “Heartbeat\r\n| distinct Computer”,
“crossComponentResources”: [
“{Workspace}”
],
“value”: [
“value::all”
],
“typeSettings”: {
“additionalResourceOptions”: [
“value::all”
]
},
“timeContext”: {
“durationMs”: 0
},
“timeContextFromParameter”: “TimeRange”,
“queryType”: 0,
“resourceType”: “microsoft.operationalinsights/workspaces”
}
],
“style”: “pills”,
“queryType”: 1,
“resourceType”: “microsoft.resourcegraph/resources”
},
“name”: “parameters – 1”
}
],
“styleSettings”: {},
“$schema”: “https://github.com/Microsoft/Application-Insights-Workbooks/blob/master/schema/workbook.json”
}