Let's take an example where you want to create a dashboard that monitors status codes for the different hosts available in the data, and you want to match these codes within a certain range — subnet — of these hosts. Let's assume that events are attributed with the following fields:

You can also set one of the two parameters to * as its default value, meaning that it matches everything, e.g. all status codes.

The above is an example where ?Subnet, and ?StatusCode are used as single-value parameters that is, you can input just one value for those parameters.

It is a common scenario to have multiple parameters, with one parameter depending on another. For example, a dashboard used to see how a specific host is doing may have a parameter which selects which region or data center to look at (e.g. ?region), and then a second parameter to list the hosts available to choose from (e.g. ?host).

In that scenario, the second parameter should naturally only show the hosts within the region you've selected previously.

You can reference other parameters if you are using either a Query Parameter or a File Parameter types. That is, all types of parameters can be referenced, but only query and file-based parameters can contain references.

For example, if the ?host parameter is a query-based parameter, it might be populated by a query similar to:

groupBy(hostName, function=[])

in which case referencing the ?region parameter becomes a matter of using that parameter in the query, same as you would reference it in other queries:

hostRegion = ?region 
| groupBy(hostName, function=[])

For file-based parameters, you can also reference another parameter simply by referring to it. Say ?host is a file-based parameter, based on a CSV file like this:

|-----------------------|
| regionName | hostName | 
| us         | host-1   |
| us         | host-2   |
| eu         | host-3   |
|-----------------------|

For this file-based parameter, you can add a value filter, which can reference another parameter. In other words, you can specify that the regionName column must match what is selected in the ?region parameter, as shown in the parameter configuration here depicted:

Figure 120. Multiple Parameters in a File Parameter

Figure 121. Referenced Parameter Configuration

A parameter can only be assigned a fixed value, the value from a parameter cannot be used within a regex, for example:

/error="?error"/i

One way to work-around this is to use the parameter as the entire regex to the regex() function:

regex(?regex, field="message")

In the above example we use a parameter to represent the string used as a regular expression that is matched against the field message.

You also cannot provide an array:

["foo","bar"]

Or a subquery

foo AND bar

Usually you will want to fill in the Query String field with a LogScale query that uses an aggregate function like top() and find the most frequent values that appear in a certain field. For example, you could find all hosts in your production cluster using:

env=PROD
| top(host)

You will need to then set host as the value in Dropdown Value Field, meaning it is the value of this field (host) in the search results from the query env=PROD | top(host) that should be bound to the parameters.

Using top() like in the example above is useful to get the most frequent values. If instead you want all possible values from the data, you can use the groupBy() function to get those values.

The most efficient way to do so is by calling groupBy() with no aggregation function, using:

groupBy(fieldName, function=[])

This will make groupBy() just gather the unique values without doing any operations on those values (like counting how many times they occur).

You can use the same parameter names in different queries for different widgets, so that the parameters shown in the dashboard will apply to any widget in that dashboard.

Parameters can be used in case-insensitive searches; in the example below the field Username is filtered based on the inputUserName parameter value:

| inputUserName := ?parameterUserName
| test(lower(inputUserName) == lower(UserName))