Configuring ClickHouse data source in Grafana

The easiest way to modify a configuration is in the Grafana UI on the plugin configuration page, but data sources can also be provisioned with a YAML file.

This page shows a list of options available for configuration in the ClickHouse plugin, as well as config snippets for those provisioning a data source with YAML.

For a quick overview of all the options, a full list of config options can be found here.

Common Settings

Example configuration screen:

Example configuration YAML for common settings:

Note that a version property is added when the configuration is saved from the UI. This shows the version of the plugin that the config was saved with.

HTTP Protocol

More settings will be displayed if you choose to connect via the HTTP protocol.

HTTP Path

If your HTTP server is exposed under a different URL path, you can add that here.

Custom HTTP Headers

You can add custom headers to the requests sent to your server.

Headers can be either plain text or secure. All header keys are stored in plain text, while secure header values are saved in the secure config (similar to the password field).

Secure Values over HTTP

While secure header values are stored securely in the config, the value will still be sent over HTTP if secure connection is disabled.

Example YAML for plain/secure headers:

Additional Settings

These additional settings are optional.

Example YAML:

OpenTelemetry

OpenTelemetry (OTel) is deeply integrated within the plugin. OpenTelemetry data can be exported to ClickHouse with our exporter plugin. For the best usage, it is recommended to configure OTel for both logs and traces.

It is also required to configure these defaults for enabling data links, a feature that enables powerful observability workflows.

Logs

To speed up query building for logs, you can set a default database/table as well as columns for the logs query. This will pre-load the query builder with a runnable logs query, which makes browsing on the explore page faster for observability.

If you are using OpenTelemetry, you should enable the "Use OTel" switch, and set the default log table to otel_logs. This will automatically override the default columns to use the selected OTel schema version.

While OpenTelemetry isn't required for logs, using a single logs/trace dataset helps to enable a smoother observability workflow with data linking.

Example logs configuration screen:

Example logs config YAML:

Traces

To speed up query building for traces, you can set a default database/table as well as columns for the trace query. This will pre-load the query builder with a runnable trace search query, which makes browsing on the explore page faster for observability.

If you are using OpenTelemetry, you should enable the "Use OTel" switch, and set the default trace table to otel_traces. This will automatically override the default columns to use the selected OTel schema version. While OpenTelemetry isn't required, this feature works best when using its schema for traces.

Example trace configuration screen:

Example trace config YAML:

Column Aliases

Column aliasing is a convenient way to query your data under different names and types. With aliasing, you can take a nested schema and flatten it so it can be easily selected in Grafana.

Aliasing may be relevant to you if:

• You know your schema and most of its nested properties/types
• You store your data in Map types
• You store JSON as strings
• You often apply functions to transform the columns you select

Table-defined ALIAS Columns

ClickHouse has column aliasing built-in and works with Grafana out of the box. Alias columns can be defined directly on the table.

In the above example, we create an alias called TimestampDate that converts the nanoseconds timestamp to a Date type. This data isn't stored on disk like the first column, it's calculated at query time. Table-defined aliases will not be returned with SELECT *, but this can be configured in the server settings.

For more info, read the documentation for the ALIAS column type.

Column Alias Tables

By default, Grafana will provide column suggestions based on the response from DESC table. In some cases, you may want to completely override the columns that Grafana sees. This helps obscure your schema in Grafana when selecting columns, which can improve the user experience depending on your table's complexity.

The benefit of this over the table-defined aliases is that you can easily update them without having to alter your table. In some schemas, this can be thousands of entries long, which may clutter the underlying table definition. It also allows hiding columns that you want the user to ignore.

Grafana requires the alias table to have the following column structure:

Here's how we could replicate the behavior of the ALIAS column using the alias table:

We can then configure this table to be used in Grafana. Note that the name can be anything, or even defined in a separate database:

Now Grafana will see the results of the alias table instead of the results from DESC example_table:

Both types of aliasing can be used to perform complex type conversions or JSON field extraction.

All YAML Options

These are all of the YAML configuration options made available by the plugin. Some fields have example values while others simply show the field's type.

See Grafana documentation for more information on provisioning data sources with YAML.