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.

You can use multivalued parameters to select more options from a list of available values:

Figure 143. Multivalue Parameters Selection

Multiple values can be added at once to a multi-value parameter by using comma as a delimiter for the list of values, so that the values can be used individually. Syntax options for adding values to multi-value parameters are described at Multi-Value Dashboard Parameters Syntax.

Use the Clear all button to remove the selected values from the list in one click.

The example in figure above is produced from the query:

in(field=loglevel, values=[?loglevels])

A dashboard parameter of any type automatically becomes a multi-value parameter only when it appears inside brackets ([ ]) in all queries on that dashboard. For example, the parameter ?loglevels in the query above is inside brackets to indicate multi-value support, meaning it enables to submit the values of the loglevel field e.g., INFO and WARN.

If any query on the dashboard uses the same parameter without brackets, the parameter does not support multi-value functionality for that dashboard.

When the query is executed, the selected values are combined in the query into a comma-separated string. Using the same example, the query becomes:

in(field=loglevel, values=["INFO", "WARN"])

As mentioned above, if the same parameter appears as both single-value and multi-value in two queries within a dashboard, the dashboard treats it as a single-value parameter for compatibility.

For example, consider a dashboard with two queries using the ?loglevel parameter. The first query uses ?loglevel as a multi-value parameter (inside brackets):

in(field=loglevel, values=[?loglevels])

The second query uses ?loglevel as a single-value parameter (without brackets):

loglevel=?loglevel
| groupby(loglevel)

Another example of query serving well for a multi-value parameter would use the field method with its values counted in a timeChart() function:

in(method, values=[?method]) 
| timeChart()

With GET and POST selected for the ?method parameter in the Time Chart widget, the query will be executed as:

in(method, values = ["GET", "POST"])
| timeChart(method)

and will produce a visualization limited to the selected methods:

Figure 144. Widget with Multivalued Parameter in TimeChart

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 145. Multiple Parameters in a File Parameter

Figure 146. 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))