The following table lists the types of variables shipped with FojiSoft.
You must enter general options for any type of variable that you create.
1. Navigate to the dashboard you want to make a variable for and click the Dashboard settings (gear) icon at the top of the page.
2. On the Variables tab, click New.
3. Enter a Name for the variable.
4. In the Type list, select Query.
5. (Optional) In Label, enter the display name of the variable dropdown.
If you don’t enter a display name, then the dropdown label is the variable name.
6. Choose a Hide option:
Query variables enable you to write a data source query that can return a list of metric names, tag values, or keys. For example, a query variable might return a list of server names, sensor IDs, or data centers. The variable values change as they dynamically fetch options with a data source query.
Query variables are generally only supported for strings. If your query returns numbers or any other data type, you might need to convert them to strings in order to use the mas variables. For the Azure data source, for example, you can use the tostring function for this purpose.
Query expressions can contain references to other variables and in effect create linked variables. FojiSoft detects this and automatically refreshes a variable when one of its linked variables change.
Note: Query expressions are different for each data source.
Use a custom variable for a value that does not change, such as a number or a string.
For example, if you have server names or region names that never change, then you might want to create them as custom variables rather than query variables. Because they do not change, you might use them in chained variables rather than other query variables. That would reduce the number of queries FojiSoft must send when chained variables are updated.
Text box variables display a free text input field with an optional default value. This is the most flexible variable because you can enter any value. Use this type of variable if you have metrics with high cardinality or if you want to update multiple panels in a dashboard at the same time.
Constant variables enable you to define a hidden constant. This is useful for metric path prefixes for dashboards you want to share. When you export a dashboard, constant variables are converted to import options.
Constant variables are not flexible. Each constant variable only holds one value, and it cannot be updated unless you update the variable settings.
Constant variables are useful when you have complex values that you need to include in queries but don’t want to retype in every query. For example, if you had a server path called i-0b6a61efe2ab843gg, then you could replace it with a variable called $path_gg.
Data source variables enable you to quickly change the data source for an entire dashboard. They are useful if you have multiple instances of a data source, perhaps in different environments.
Use an interval variable to represent time spans such as 1m,1h, 1d. You can think of them as a dashboard-wide “group by time” command. Interval variables change how the data is grouped in the visualization. You can also use the Auto Option tore turn a set number of data points per time span.
Step count - Select the number of times the current time range will be divided to calculate the value, similar to the Max data points query option. For example, if the current visible time range is 30 minutes, then the auto interval groups the data into 30 one-minute increments. The default value is 30 steps.
Min Interval - The minimum threshold below which the step count intervals will not divide the time. To continue the 30 minute example, if the minimum interval is set to 2m, then FojiSoft would group the data into 15 two-minute increments
Ad hoc filters enable you to add key/value filters that are automatically added to all metric queries that use the specified data source. Unlike other variables, you do not use ad hoc filters in queries. Instead, you use ad hoc filters to write filters for existing queries.
Ad hoc filters are one of the most complex and flexible variable options available. Instead of a regular list of variable options, this variable allows you to build a dashboard-wide ad hoc query. Filters you apply in this manner are applied to all panels on the dashboard.
Selection Options are a feature you can use to manage variable option selections. All selection options are optional, and they are off by default.
Interpolating a variable with multiple values selected is tricky as it is not straight forward how to format the multiple values into a string that is valid in the given context where the variable is used. FojiSoft tries to solve this by allowing each data source plugin to inform the templating interpolation engine what format to use for multiple values.
Note: The Custom all value option on the variable must be blank for FojiSoft to format all values into a single string. If leave it blank, then the FojiSoft concatenates (adds together) all the values in the query. Something like value1,value2,value3. If a custom all value is used, then instead the value will be something like * or all.
FojiSoft uses regex expressions, so the same variable would be interpolated as (host1|host2|host3). Every value would also be regex escaped. If not, a value with a regex control character would break the regex expression.
Automatic escaping and formatting can cause problems and it can be tricky to grasp the logic behind it. Especially when using the regex syntax requiring that the variable is used in regex operator context.
If you do not want FojiSoft to do this automatic regex escaping and formatting, then you must do one of the following:
FojiSoft adds an All option to the variable dropdown list. If a user selects this option, then all variable options are selected.
This option is only visible if the Include All option is selected.
Enter regex syntax in the Custom all value field to define the value of the All option.
By default the All value includes all options in combined expression. This can become very long and can have performance problems. Sometimes it can be better to specify a custom all value, like a wildcard regex.
In order to have custom regex syntax in the Custom all value option, it is never escaped so you will have to think about what is a valid value for your data source.
FojiSoft has global built-in variables that can be used in expressions in the query editor. This topic lists them in alphabetical order and defines them. These variables are useful in queries, dashboard links, panel links, and data links.
$__dashboard
This variable is the name of the current dashboard.
$__from and $__to
FojiSoft has two built-in time range variables: $__from and $__to. They are currently always interpolated as epoch milliseconds by default, but you can control date formatting.
The syntax above also works with ${__to}.
You can use this variable in URLs, as well.
$__interval
You can use the $__interval variable as a parameter to group by time (for InfluxDB, MySQL, Postgres, MSSQL), Date histogram interval (for Elasticsearch), or as a summarize function parameter (for Graphite).
FojiSoft automatically calculates an interval that can be used to group by time in queries. When there are more data points than can be shown on a graph, then queries can be made more efficient by grouping by a larger interval. It is more efficient to group by 1 day than by 10s when looking at 3 months of data and the graph will look the same and the query will be faster. The $__interval is calculated using the time range and the width of the graph (the number of pixels).
Approximate Calculation: (to - from) / resolution
For example, when the time range is 1 hour and the graph is full screen, then the interval might be calculated to 2m - points are grouped in 2 minute intervals. If the time range is 6 months and the graph is full screen, then the interval might be 1d (1 day) - points are grouped by day.
$__interval_ms
This variable is the $__interval variable in milliseconds, not a time interval formatted string. For example, if the $__interval is 20m then the $__interval_ms is 1200000.
$__name
This variable is only available in the Single stat panel and can be used in the prefix or suffix fields on the Options tab. The variable will be replaced with the series name or alias.
$__org
This variable is the ID of the current organization. ${__org.name} is the name of the current organization.
$__user
${__user.id} is the ID of the current user. ${__user.login} is the login handle of the current user. ${__user.email} is the email for then current user.
$__range
This variable represents the range for the current dashboard. It is calculated by to - from. It has a millisecond and a second representation called $__range_ms and $__range_s.
$__rate_interval
The $__rate_interval variable is meant to be used in the rate function.
$timeFilter or $__timeFilter
The $timeFilter variable returns the currently selected time range as an expression. For example, the time range interval Last 7 days expression is time > now() - 7d.
This is used in several places, including:
Chained variables, also called linked variables or nested variables, are query variables with one or more other variables in their variable query. This section explains how chained variables work and provides links to example dashboards that use chained variables.
Chained variable queries are different for every data source, but the premise is the same for all. You can use chained variable queries in any data source that allows them.
Extremely complex linked templated dashboards are possible, 5 or 10 levels deep. Technically, there is no limit to how deep or complex you can go, but the more links you have, the greater the query load.
The following practices will make your dashboards and variables easier to use.
You can change the orders of variables in the dashboard variable list by clicking the up and down arrows on the right side of each entry. FojiSoft lists variable drop downs left to right according to this list, with the variable at the top on the far left.
The more layers of dependency you have in variables, the longer it will take to update dashboards after you change variables.
For example, if you have a series of four linked variables (country, region, server, metric)and you change a root variable value (country), then FojiSoft must run queries for all the dependent variables before it updates the visualizations in the dashboard.
The variables page lets you add variables and manage existing variables. It also allows you to inspect variables and identify whether a variable is being referenced (or used) in other variables or dashboard.
Move: You can move a variable up or down the list using drag and drop.
Clone: To clone a variable, click the clone icon from the set of icons on the right. This creates a copy of the variable with the name of the original variable prefixed with copy_of_.
Delete: To delete a variable, click the trash icon from the set of icons on the right.
Using the Regex Query option, you filter the list of options returned by the variable query or modify the options returned.
This page show show to use regex to filter/modify values in the variable dropdown.
Using the Regex Query Option, you filter the list of options returned by the Variable query or modify the options returned.
Examples off filtering on the following list of options:
Regex:
Result:
Regex:
Result:
List of options:
Regex:
Result:
Using named capture groups, you can capture separate ’text’ and ‘value’ parts from the options returned by the variable query. This allows the variable drop-down list to contain a friendly name for each value that can be selected.
For example, when querying the node_hwmon_chip_names Prometheus metric, the chip_name is a lot friendlier that the chip value. So the following variable query result:
Passed through the following Regex:
Would produce the following drop-down list:
Note: Only text and value capture group names are supported.