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:

Adding Parameters

Figure 98. Adding Parameters


  1. Click the pencil icon on the top right to take the dashboard into Edit Mode, see Editing Dashboards.

  2. On the top left of the dashboard, click Parameters and Add Parameter.

  3. A dialog pops up from the settings gear icon next to the ?new-param field, 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., user will mean you use ?user to 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, Username in place of ?user would 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, production for an ?environment parameter.

    Tip

    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, 1 or 100.

    • Other settings which are specifically required for different parameter types. For details on these settings, see Parameter Types.

  4. Click Apply.

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

Note

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.

Parameter Types

There are different types of parameters that can be used in dashboards.

All parameters are added to the query using the ?parameterName syntax.

If the dashboard does not have any parameters, parameters found in queries (e.g., ?hostname) show up automatically.

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.

Query Parameter

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 Humio 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, email.

  • Search Interval — sets how far back in time to search for values. This is always relative to the current time. For example, 5m, 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 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:

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

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.

Where to Use Parameters in a Query

A parameter 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():

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

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, server1, server2, server3. This is a mandatory field.

  • Labels — List of comma-separated labels to name a value. For example, Prod, Test, Staging.

File Parameter

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.

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., email. Allows you to configure 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.

  • 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:

File Based Parameter Configuration

Figure 99. File Based Parameter Configuration


If example.csv has these contents:

humio
userid,name,country
1,alice,us
2,bob,uk

Then using the parameter in the dashboard looks like this:

File Based Parameter Output

Figure 100. 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 example.csv also contains a country column, we can specify that we only want users from, for example, the USA

File Based Parameter with Static Filter

Figure 101. 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 appropriate options:

File Based Parameter with Dynamic Filter and Output

Figure 102. File Based Parameter with Dynamic Filter and Output


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.

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 eu-1, ca-2, us-1.

  • loglevel — The log level of the entry, such as INFO WARN and ERROR.

  1. Go to Search tab from the top menu bar and enter a query like the one below:

    humio
    host = ?host and rackId = ?rackId and zoneId=?zoneId | timechart(loglevel)

    The query contains three parameters: ?host, ?rackId and ?zoneId.

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

    Parameters in a Query

    Figure 103. Parameters in a Query


    An input field has appeared per parameter and its default value is set to * — meaning that it matches everything.

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