Dashboard parameters allow you to interact with dashboards doing filtering, and do drill-down for widgets.
Parameters are added to the query using the ?parameterName
syntax.
Suppose you want to create a dashboard that monitors a set of servers and that those servers are placed in racks and run in different availability zones.
Assuming 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 ‘eu-1’, ‘ca-2’, ‘us-1’.
loglevel
— The log level of the entry, such as INFO
WARN
and ERROR
.
On the search page we enter a query like the one below:
host = ?host and rackId = ?rackId and zoneId=?zoneId | timechart(loglevel)
The query contains three parameters: ?host
, ?rackId
and ?zoneId
.
Running the query produces a time chart widget with one series per log level. This allows us to see the activity level on servers and how many errors occur.
As you can see, the screenshot shows an input field has appeared per parameter and its default value is set to *
— meaning that it matches everything. We can now set the ?zone
parameter to eu-1
, for example, and run the query again to show results for all hosts and all racks but only for the eu-1
availability zone.
You can also use the wildcard character in parameters so above we could write eu-*
to match all availability zones starting with “eu-".
Once you are happy with your query with parameters you can add them to a dashboard. Parameters are automatically discovered on the dashboard and will appear at the top of the screen.
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.
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.
There are four types of parameter:
To configure a parameter, take the dashboard into Edit Mode by clicking Edit Dashboard in the top menu.
You will see that parameters now look different and that there is a settings icon next to each parameter input field. Clicking the settings icon will bring up a popup that allows you to choose options for the parameter.
One of the most important parameter settings is the Default Value field. It allows you to set the default value the parameter should have if nothing else is specified.
In many cases this will be *
indicating “no filtering” but in other cases you might want to set, for example, production
for an ?environment
parameter.
Quite often you will want to filter or aggregate based on values that appear in your logs. You can use the Values from Search Results parameter type for this.
This will make the parameter input into a dropdown box where the option in the dropdown is taken from search results. Fill in the Query String field with a Humio 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 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.
Pro Tip: 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.
The Fixed List of Values 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 Values from Files parameter may be a better fit.
Humio 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. Selecting the File parameter type lets you give the name of a file and specify which field to insert data into the parameter from, with the File and Value Field settings, respectively. If you configure Label Field, those are the values that will appear in the Web UI when you select the value for the parameter, but it is still the value field that determines what data goes in the query. If no labelling field is configured, the Web UI will display the actual values.
Take this configuration as an example:
If example.csv
has these contents:
userid,name,country
1,alice,us
2,bob,uk
Then using the parameter in the dashboard looks like this:
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 example.csv
also contains a country
column, we can specify that we only want users from, for example, the USA
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 appropriate options:
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 dashboards/<dashboard-id>?$param1=value1&$param2=value2
where parameters are denoted with the $
sign instead of the ?
(like you use in queries). This is because ?
is a reserved character in URLs.
A parameter must be can only be assigned simple values, you cannot for instance assign a regex literal (/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 regex
:
regex(?regex, field="message")
In this example we use a parameter to represent the string used as a regular expression that is matched against the field message.