Working with Dashboard Parameters

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.

Creating a Parameterized Dashboard

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.

Creating a Widget with Parameters

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-".

Adding Parameters to Dashboards

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.

Configuring a Parameter

There are four types of parameter:

• Free text parameters
• Search result-based parameters
• Parameters with a fixed set of options
• File-based parameters

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.

Default Value

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.

Query Based Parameters

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.

Fixed list parameters

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.

File Based Parameters

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:

URL

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.

Where can parameters be used in a query?

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.