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 142. 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, thus the values can be used individually. Syntax options for adding values to multi-value parameters are described at Multi-Value Dashboard Parameters Syntax.

The example in figure above is produced from the query:

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

Any parameter becomes multi-value whenever it is used inside brackets in a query — that is, in an array — like the parameter ?loglevels in the example query above. This will allow submitting the values of the loglevel field e.g., INFO and WARN in the parameter.

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

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"])

If the same parameter is used in two queries in a dashboard — once as a single value and once as a multi-value — we will treat it as a single value to keep it compatible with both queries.

In the example below, ?loglevel will be displayed as a standard single-value parameter, because the second query does not use it inside an array:

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

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

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