Plugins 〉Hydrolix
Hydrolix
Hydrolix data source for Grafana
The Hydrolix data source plugin integrates Hydrolix with Grafana, enabling seamless querying, analysis, and visualization of Hydrolix data.
Install the plugin
To install the Hydrolix data source plugin:
- Open the Grafana Plugin Catalog.
- Search for Hydrolix Data Source.
- Select the plugin and click Install Plugin.
After installation:
- In Grafana, go to Connections > Data Sources > Add new data source.
- Select Hydrolix from the list.
For more details about installation, see Grafana’s Plugin management documentation.
Configure the data source
You can configure the Hydrolix data source directly within Grafana or via configuration files.
Following is the list of Hydrolix configuration options.
- Name - The name used to reference this data source in panels and queries.
- Default - Toggle to set this Hydrolix data source as the default in panels and visualizations.
Server section:
- Server address - The IP address or hostname of your Hydrolix instance.
- Server port - The port on which your Hydrolix instance is running.
- Use default - Toggle to use the default port instead of specifying a custom one.
- Protocol - The communication protocol used: Native or HTTP.
- Secure connection - Toggle to enable a secure connection.
- HTTP URL path (optional) - Additional URL path for HTTP requests.
TLS / SSL Settings section:
- Skip TLS verify - Toggle to bypass TLS certificate verification. Not recommended, unless absolutely necessary for testing.
Credentials section:
- Credentials Type - Credentials type for connecting to your Hydrolix instance: User Account or Service Account.
- Token - Service account token.
- Username, Password - Service account credentials.
Additional Settings section:
- Default database (optional) - Used when no database is explicitly included in the query.
- Default round (optional) - Used when a query does not specify a round value. Aligns
$from
and$to
to the nearest multiple of this value. For more details, see Round timestamps. - Ad hoc filter table variable name (optional) - Variable defines which table to use for retrieving ad hoc filter columns and values.
- Ad hoc filter default time range (optional) - Default time range for time filtering when dashboard time range is not available
- Ad hoc filter values query condition variable name (optional) - Name of a dashboard variable that defines query condition to filter ad hoc filter values
- Dial timeout (optional) - Connection timeout in seconds.
- Query timeout (optional) - Read timeout in seconds.
Query Settings subsection:
You can configure Hydrolix query settings that will be sent
with each query from this data source, wrapped as CustomSetting
values. Note that only a subset of settings is
supported in this way.
To add a setting, select it from the dropdown list and provide a corresponding value in the field that appears.
You can include any built-in Grafana variables or dashboard template variables in the setting values. Keep in mind that some variables may not be available during interpolation - their availability depends on the query source. If a variable is not defined in the current context, it will not be interpolated and will remain as-is.
The plugin also supports several synthetic variables specific to query settings:
${__hydrolix.raw_query}
- Represents the raw query text before any interpolation is applied.${__hydrolix.query_source}
- Represents the query source, derived from theDataQueryRequest.app
field. This is useful to distinguish whether a query originated from Explore or elsewhere.
Provision the data source
To provision the Hydrolix data source using Grafana’s provisioning system, define it in a YAML configuration file.
Below are some provisioning examples.
Using HTTPS protocol
apiVersion: 1
datasources:
- name: "Hydrolix"
type: "hydrolix-hydrolix-datasource"
jsonData:
host: localhost
port: 443
protocol: http
secure: true
username: username
path: /query
secureJsonData:
password: password
Using native protocol
apiVersion: 1
datasources:
- name: "Hydrolix"
type: "hydrolix-hydrolix-datasource"
jsonData:
host: localhost
port: 9440
protocol: native
secure: true
username: username
secureJsonData:
password: password
Using HTTPS protocol with defaults and ad hoc filters
apiVersion: 1
datasources:
- name: "Hydrolix"
type: "hydrolix-hydrolix-datasource"
jsonData:
host: localhost
port: 443
protocol: http
secure: true
username: username
path: /query
defaultDatabase: database
defaultRound: 60s
adHocTableVariable: table
secureJsonData:
password: password
For more details about provisioning, see Grafana’s Provisioning documentation.
Querying the data source
The query editor in Grafana enables powerful SQL querying with convenient syntax enhancements through macros and templates.
SQL query editor
The editor provides extensive SQL capabilities, featuring:
- Intelligent autocompletion for databases, tables, columns, and SQL syntax.
- Template variable and macro support.
- Code formatting.
Keyboard shortcuts
Cmd/Ctrl + Return
- Run the query.
Macros
To simplify syntax and to allow for dynamic parts, like date range filters, the query can contain macros.
Macro | Description | Output example |
---|---|---|
$__dateFilter(column) | Generates a condition to filter data (using the provided column) based on the panel's date range | date >= toDate('2022-10-21') AND date <= toDate('2022-10-23') |
$__timeFilter([column]) | Generates a condition to filter data based on the panel's time range in seconds. Accepts an optional column name. If no column is provided, the primary key is used automatically. | time >= toDateTime(1415792726) AND time <= toDateTime(1447328726) |
$__timeFilter_ms([column]) | Generates a condition to filter data based on the panel's time range in milliseconds. Accepts an optional column name. If no column is provided, the primary key is used automatically. | time >= fromUnixTimestamp64Milli(1415792726123) AND time <= fromUnixTimestamp64Milli(1447328726456) |
$__dateTimeFilter(dateColumn, timeColumn) | Combines $__dateFilter() and $__timeFilter() for filtering with separate date and time columns | $__dateFilter(dateColumn) AND $__timeFilter(timeColumn) |
$__adHocFilter | Replaced with a condition to filter data based on the applied ad hoc filters | statusCode = '200' |
$__fromTime | Replaced with the panel's start time, cast as DateTime | toDateTime(1415792726) |
$__toTime | Replaced with the panel's end time, cast as DateTime | toDateTime(1447328726) |
$__fromTime_ms | Replaced with the panel's start time, cast as DateTime64(3) (millisecond precision) | fromUnixTimestamp64Milli(1415792726123) |
$__toTime_ms | Replaced with the panel's end time, cast as DateTime64(3) (millisecond precision) | fromUnixTimestamp64Milli(1447328726456) |
$__interval_s | Replaced with the interval in seconds | 20 |
$__timeInterval([column]) | Calculates intervals based on panel width, useful for grouping data in seconds. Accepts an optional column name. If no column is provided, the primary key is used automatically. | toStartOfInterval(toDateTime(column), INTERVAL 20 second) |
$__timeInterval_ms([column]) | Calculates intervals based on panel width, useful for grouping data in milliseconds. Accepts an optional column name. If no column is provided, the primary key is used automatically. | toStartOfInterval(toDateTime64(column, 3), INTERVAL 20 millisecond) |
$__conditionalAll(condition, $templateVar) | Includes the provided condition only if the template variable does not select all values, defaults to 1=1 otherwise | condition or 1=1 |
Below is an example of a query with the $__timeFilter
macro:
SELECT $__timeInterval(log_time) AS time, avg(cpu_usage) AS value
FROM logs
WHERE $__timeFilter()
GROUP BY time
ORDER BY time
Ad hoc filters
Ad hoc filters allow flexible, column-value filtering dynamically applied across queries. These filters are injected into
queries via the $__adHocFilter
macro, which must be explicitly included in the WHERE
clause:
SELECT $__timeInterval(log_time) AS time, avg(cpu_usage) AS value
FROM logs
WHERE $__timeFilter() AND $__adHocFilter()
GROUP BY time
ORDER BY time
The plugin ensures filters are applied only when valid for the selected table.
Configure ad hoc filters
To enable ad hoc filters, both the data source and the dashboard must be configured properly:
In the data source settings (under Advanced Settings):
- Ad hoc filter table variable name: the name of a dashboard variable that defines the table used to retrieve column names and their values for ad hoc filters.
- Ad hoc filter default time range: a default time range to use when the dashboard time range is unavailable.
In the target dashboard, create a variables using the exact name defined in the data source settings A variable for the table name
Note: Ad hoc filters will not work unless both the data source and the dashboard are configured correctly. Be sure to match variable names precisely.
Limit ad hoc filter values
This plugin allows limiting ad hoc filter values based on a specified condition. For example, if a dashboard only shows data from hosts with commercial domains, you can restrict the filter values using a condition like: host like '%.com'
To apply the limit ad hoc filters, both the data source and the dashboard must be configured properly:
In the data source settings (under Advanced Settings):
- Ad hoc filter values query condition variable name: the name of a dashboard variable that defines query condition to filter ad hoc filter values.
In the target dashboard, create a const variables using the exact name defined in the data source settings Ad hoc filter values query condition variable name and add condition as a value (e.g.
host like '%.com'
)
Empty and null values
Ad hoc filters support two synthetic values to help identify and query rows with missing or blank data:
__null__
: matches rows where the column value isNULL
.__empty__
: matches rows where the column value is an empty string.
These synthetic values appear in the ad hoc filter suggestions only if the underlying data contains NULL
or empty
strings for the selected column during the current dashboard time range.
If the data contains literal values such as __null__
or __empty__
, those will also be matched by the corresponding
filters.
Wildcards
Ad hoc filters support wildcard filtering using the =~
and !~
operators. These operators allow matching or excluding
values based on simple patterns that include the *
wildcard character. Full regular expressions are not supported.
The *
symbol matches any sequence of characters, including an empty one. For example, *user*
will match any value
that contains the substring user, regardless of what comes before or after.
To match a literal asterisk (*
), escape it with a backslash (\*
). For example, to search for the exact string
*debug*
, enter: \*debug\*
.
To apply a wildcard filter:
- On the dashboard, click inside the filter field.
- Select the column you want to filter, such as
message
. - Choose the operator
=~
or!~
. - Type your full wildcard pattern, for example
*user*
. - Do not select any of the suggested values while typing.
- As you type, an option appears at the bottom of the suggestion list:
Use custom value: *user*
. - Click this option to apply the filter.
Round timestamps
To control how time ranges are aligned, $from
and $to
timestamps can be rounded to the nearest multiple of the round
value, set in the query editor or in the data source settings.
When a round value is set in the query editor, it takes precedence and is always used. If no round is set in the query editor,
the data source falls back to the default round, if it is configured and non-zero. If neither is set, or if the round value
in the query editor is explicitly set to 0
, no rounding is applied and the original timestamps are used as-is.
The supported time units for rounding are: ms
(milliseconds), s
(seconds), m
(minutes), and h
(hours).
Examples
Default round | Query round | Effective round | Input timestamp | Rounded timestamp |
---|---|---|---|---|
5m | not set | 5m | 10:07:20 | 10:05:00 |
5m | 1m | 1m | 09:02:30 | 09:03:00 |
not set | not set | not applied | 08:01:23 | 08:01:23 |
5m | 0 | not applied | 07:45:50 | 07:45:50 |
Template variables
Hydrolix queries fully support Grafana's template variables, allowing the creation of dynamic and reusable dashboards.
For more details about template variables, see Grafana’s Template variables documentation.
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Installing Hydrolix on Grafana Cloud:
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
For more information, visit the docs on plugin installation.
Installing on a local Grafana:
For local instances, plugins are installed and updated via a simple CLI command. Plugins are not updated automatically, however you will be notified when updates are available right within your Grafana.
1. Install the Data Source
Use the grafana-cli tool to install Hydrolix from the commandline:
grafana-cli plugins install
The plugin will be installed into your grafana plugins directory; the default is /var/lib/grafana/plugins. More information on the cli tool.
Alternatively, you can manually download the .zip file for your architecture below and unpack it into your grafana plugins directory.
Alternatively, you can manually download the .zip file and unpack it into your grafana plugins directory.
2. Configure the Data Source
Accessed from the Grafana main menu, newly installed data sources can be added immediately within the Data Sources section.
Next, click the Add data source button in the upper right. The data source will be available for selection in the Type select box.
To see a list of installed data sources, click the Plugins item in the main menu. Both core data sources and installed data sources will appear.
Changelog
0.6.0
- Feature: Service Account support (GRAP-41)
- Feature: Support of limit values for ad-hoc filter (GRAP-78)
- Feature: Add “Run Query” button to the query editor (GRAP-35)
- Fix: Query parsing error when user tries to format query (GRAP-75)
- Fix: Incorrect handling of single quotes inside ad-hoc filter values (GRAP-80)
0.5.0
- Feature: Support $__timeFilter and $__timeInterval macros without timestamp (GRAP-71)
- Feature: Support automatic timestamp column detection in ad hoc filters (GRAP-68)
0.4.0
- Feature: Support configurable Hydrolix query settings per data source (GRAP-46)
0.3.1
- Fix: Some queries in template variables fail in Grafana 10.x (GRAP-64)
0.3.0
- Feature: Support
*
wildcard in ad hoc filters and convert to SQL%
(HDX-8167) - Feature: Support synthetic ad hoc filter values
__empty__
and__null__
(HDX-8468) - Fix: Do not crash when ad hoc tag values are missing in dashboard time range (HDX-8605)
- Fix: Tooltip for invalid round value causes layout shift in query editor (HDX-8391)
- Fix: No loading spinner when changing round value in query editor (HDX-8491)
0.2.0
- Feature: Add support for
one-of
(=|
) andnot-one-of
(!=|
) ad hoc filter operators (HDX-8336) - Fix: Do not crash on complex queries with ad hoc filters (HDX-8193)
- Data source config: Drop support for ad hoc query definitions in data source settings (HDX-8173)
- Chore: Update plugin screenshots and exclude test Go code from release build (HDX-8422)
0.1.6
- Fix: Apply default round setting to queries defined in template variables
0.1.5
- Feature: Add option to show interpolated SQL in the query editor
- Feature: Add new column type support for ad hoc filter keys
0.1.4
- Fix: Resolve issues reported by the Grafana plugin validator to comply with publishing requirements
0.1.3
- Fix: Rename plugin ID to follow the naming convention
0.1.2
- Feature: Add support for alerting
0.1.1
- Compatibility: Improve compatibility with Grafana 10.4.x
0.1.0
- Initial beta release.