Managing Dashboard Parameters
Dashboard parameters allow you to interact with dashboards doing filtering, and do drill-down for widgets.
Adding and Configuring Parameters
Parameters can be added and configured from the dashboard area of the user interface:
Figure 111. Adding Parameters
Click the pencil icon on the top right to take the dashboard into Edit Mode, see Editing Dashboards.
On the top left of the dashboard, click Parameters and Add Parameter.
A dialog pops up from the settings gear icon next to the
?new-paramfield, where you are prompted to provide:
Parameter Type. You can choose from:
FreeText, free text parameters
Query, search result-based parameters
FixedList, parameters with a fixed set of options
File, file-based parameters
For details on the different parameters types and their usage, see Parameter Types.
Id — is the ID of the parameter e.g.,
userwill mean you use
?userto reference it in a query. When changing the ID of a parameter you will have to manually update any queries using it to reflect the name ID.
Label — is the name displayed in the list of parameters. For example,
Usernamein place of
?userwould best suit to appear on the dashboard.
Default Value — allows you to set the default value the parameter should have. You might want to set, for example,
Use the wildcard
*as the default value to indicate "no filtering", if nothing else is specified.
Order — sets a lower or greater number to display this parameter first or last in the list of parameters for that dashboard. For example,
Other settings which are specifically required for different parameter types. For details on these settings, see Parameter Types.
If you are happy with your parameters, you can save the dashboard as a widget, as explained in Managing Dashboard Widgets: parameters are automatically discovered on the dashboard and will appear at the top of the screen.
By default the input fields are plain text fields that default to
* — as on the search page.
But you can customize parameters to make them easier to use, and to
allow you to select values in a dropdown instead of manually typing.
Parameters with the same name used in different widgets use the same input field, and allow you to change a single field and have it impact the entire dashboard.
There are different types of parameters that can be used in dashboards.
All parameters are added to the query using the
If the dashboard does not have any parameters, parameters found in
?hostname) show up
Free Text Parameter
The FreeText parameter type can be used when you want to filter or aggregate based on any kind of value. Other types of parameters give you options for what value might be worth selecting, but if no such values are available to make suggestions, then a free text parameter allows you to just type a value in.
The Query parameter type can be used when you want to filter or aggregate based on values that appear in your logs. When shown within the dashboard, the option values shown in the dropdown will be taken from the search results.
On top of the settings common to all parameter types, other specific settings needed for the Query parameter are:
Query String — must contain a LogScale query. This is a mandatory field.
Dropdown Value Field — is the field in the results that should be used as the value for items. For example,
userId. This is a mandatory field.
Dropdown Text Field — is the field in the results that should be used as the display text of items. For example,
Search Interval — sets how far back in time to search for values. This is always relative to the current time. For example,
2h. This is a mandatory field.
Use Dashboard Search Interval checkbox — makes the query for this parameter use the same time interval selected for the dashboard.
Fill in the Query String field with a
LogScale query. Usually you will want to use this in conjunction with
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
as the value in Dropdown Value Field,
meaning it is the value of this field
host) in the search results
from the query
top(host) that should be bound to the parameters.
The most efficient way to do so is by calling
groupBy() with no aggregation function, using:
This will make
groupBy() just gather the unique
values without doing any operations on those values (like counting how
many times they occur). If you just want all the unique values to
populate our parameter, then you don’t need any additional work to
If the parameters options are not human readable values you can
assign a Dropdown Text Field and
use, for example, the
match() function and a
file to lookup human readable names.
Where to Use Parameters in a Query
A parameter can only be assigned simple values, you cannot for
instance assign a regex
/error/i), an array argument,
or a sub query (
foo AND bar).
You can work around these restrictions by using multiple parameters
or by using functions such as
In this example we use a parameter to represent the string used as a regular expression that is matched against the field message.
Fixed List Parameter
The FixedList parameter is good when you have a small set of fixed values that will fit into a dropdown menu. If there are too many values to use this parameter type, however, the File parameter may be a better fit.
On top of the settings common to all parameter types, other specific settings needed for the Fixed List parameter are:
Values — List of comma-separated values. For example,
server3. This is a mandatory field.
Labels — List of comma-separated labels to name a value. For example,
LogScale supports uploading of CSV and JSON files for use with the
match() function in queries, but those same files
can also be used for populating parameters.
On top of the settings common to all parameter types, other specific settings needed for the File parameter are:
File — Insert the name of a file. This is a mandatory field.
Value Field — The field in the file that should be used as the value, e.g.,
userId. This is a mandatory field.
Label Field — The field in the file that should be used as the display text of items, e.g.,
Value Filters — Limit entries coming from the file by configuring some fields e.g.,
country, with a certain value e.g.,
Germany. Parameters can be used as values, and multiple values can be specified, separated by comma.
Take this configuration as an example:
Figure 112. File Based Parameter Configuration
example.csv has these
userid,name,country 1,alice,us 2,bob,uk
Then using the parameter in the dashboard looks like this:
Figure 113. File Based Parameter Output
Selecting the alice option will insert the value 1 into the parameter, and the same for bob and 2.
We can also use the Value Filters configuration to hide entries from
the output. Since
also contains a
we can specify that we only want users from, for example, the USA
Figure 114. File Based Parameter with Static Filter
This would remove
bob from the
output, but we can also specify multiple values, separated by comma,
or use a parameter as input. Using a parameter is the same as writing
out the options yourself, but you type, for example,
?country instead of
us, and you will get the
Figure 115. File Based Parameter with Dynamic Filter and Output
When parameters are assigned, they will be added to the URL and you can share a link to a dashboard configuration simply by sharing the URL of what you are looking at.
This can also be used to integrate with other systems, where you can construct dashboard URLs that contain parameters. This could for instance be an IP found in an external system that you want to look at logs for on a dashboard.
Notice that URLs use the syntax
where parameters are denoted with the
$ sign instead of the
? (like you use in queries). This
? is a reserved
character in URLs.
Example of Parameterized Dashboard
Here is an example situation where you want to create a dashboard that monitors a set of servers, and those servers are placed in racks and run in different availability zones. Let's assume that log entries are attributed with the following fields:
host— The hostname of the server.
rackId— The ID of the server rack.
thread— The thread the log entry produced on.
zone— The availability zone, represented with IDs such as
loglevel— The log level of the entry, such as
Go to Search tab from the top menu bar and enter a query like the one below:logscale
host = ?host and rackId = ?rackId and zoneId=?zoneId | timechart(loglevel)
The query contains three parameters:
Run the query to produce a time chart widget with one series per log level. This will show the activity level on servers and how many errors occur.
Figure 116. Parameters in a Query
An input field has appeared per parameter and its default value is set to
*— meaning that it matches everything.
eu-1, for example, and run the query again to show results for all hosts and all racks but only for the
You can also use the wildcard character in parameters so above we could
eu-* to match all
availability zones starting with