Skip to main content
The following configuration options are available for each component of ClickStack:

Settings for open source distributions

Docker

If using the All in One, ClickStack UI only or Local Mode simply pass the desired setting via an environment variable e.g.

Docker Compose

If using the Docker Compose deployment guide, the .env file can be used to modify settings. Alternatively, explicitly overwrite settings in the docker-compose.yml file e.g. Example:

Helm

Use the Helm deployment guide to install the operators and ClickStack chart. Retrieve the current chart’s values before customizing a deployment:
Set the application and collector environment separately using the chart’s values, then apply your configuration:
See Helm configuration for the supported values, ingress, resources, and secret configuration. The older hyperdx/hdx-oss-v2 chart has a different values structure.

ClickStack UI application

Connections

Configure the database connection used by your sources in Team Settings.

Data source settings

The ClickStack UI relies on the user defining a source for each of the Observability data types/pillars:
  • Logs
  • Traces
  • Metrics
  • Sessions
This configuration can be performed inside the application from Team Settings -> Sources, as shown below for logs:
ClickStack UI Source configuration
Each source needs table and column mappings so the ClickStack UI can query its data. Metrics sources can use separate tables for different metric types. The Enabled toggle appears when editing an existing source; source-level Query Settings accept up to ten name/value pairs. If using the default OpenTelemetry (OTel) schema distributed with ClickStack, these columns can be automatically inferred for each of the sources. If modifying the schema or using a custom schema, users are required to specify and update these mappings.
The collector creates tables through schema migrations or legacy exporter-managed schema creation, depending on its schema configuration. Column mappings follow the OpenTelemetry conventions, including the log data model.
The following settings are available for each source:

Logs

Traces

Metrics

A metric source also stores its timestamp and resource-attribute mappings (normally TimeUnix and ResourceAttributes). A unified series Table field is shown only for teams with metrics-series-table support enabled.

PromQL

When PromQL is enabled, you can create a PromQL source. In addition to the common name, connection, database, table, query settings, and enabled fields, it has Minimum auto granularity. For a ClickHouse connection, select the TimeSeries engine table. The timestamp expression is set automatically. Minimum auto granularity also determines the scrape interval used to calculate $__rate_interval; when unset, this assumes a 15-second scrape interval.

Sessions

Materialized views

Materialized views can be registered against Log and Trace data sources so that eligible aggregation queries are answered from the pre-aggregated view instead of the source table. For guidance on creating and registering views, see “Materialized views”. Each registered view is configured with the following settings: Most of these settings are inferred from the view’s schema when the target table is selected.

Metadata materialized views

Metadata materialized views are materialized views which accelerate field discovery for filters and autocomplete. They can be configured on Log and Trace data sources.

Highlighted Attributes

Highlighted Attributes and Highlighted Trace Attributes can be configured on Log and Trace data sources.
  • Highlighted Attributes are columns or expressions which are displayed for each log or span, when viewing log or span details.
  • Highlighted Trace Attributes are columns or expressions which are queried from each log or span in a trace, and displayed above the trace waterfall.
These attributes are defined in the source configuration and can be arbitrary SQL expressions. If the SQL expression returns a value that is in the format of a URL, then the attribute will be displayed as a link. Empty values aren’t displayed. Each attribute is configured with the following settings: For example, this trace source has been configured with a Highlighted Attribute and a Highlighted Trace Attribute:
Highlighted Attributes configuration
These attributes are displayed in the side panel after clicking on a log or span:
Highlighted Attributes
Clicking on an attribute provides options for using the attribute as a search value. If the optional Lucene expression is provided in the attribute configuration, then the Lucene expression will be used for the search instead of the SQL expression.
Highlighted Attributes Search

Correlated sources

To enable full cross-source correlation in ClickStack, you must configure correlated sources for logs, traces, metrics, and sessions. This allows ClickStack UI to associate related data and provide rich context when rendering events.
  • Logs: Can be correlated with traces and metrics.
  • Traces: Can be correlated with logs, sessions, and metrics.
  • Metrics: Can be correlated with logs.
  • Sessions: Can be correlated with traces.
Setting these correlations enables several features. For example, ClickStack UI can render relevant logs alongside a trace or surface metric anomalies linked to a session. For example, below is the Logs source configured with correlated sources:
ClickStack UI Source correlated

ClickHouse client settings

The ClickHouse Client Settings section in Team Settings controls query behavior for the team. For permissions and security policies, see Role-based access control. For notification destinations, see Alerts.

Application configuration settings

These environment variables configure self-hosted ClickStack. They aren’t configurable for the hosted ClickStack UI in ClickHouse Cloud. Defaults below refer to the official container entrypoints unless otherwise noted; Docker Compose can override them. Restart the affected service after changing its environment.

Network and storage

If running the API directly rather than using the container entrypoint, set PORT and OPAMP_PORT for the API and OpAMP listeners. The HYPERDX_*_PORT variables are container/deployment conveniences.

Authentication and security

Bootstrap and provisioning

For local-mode deployments, NEXT_PUBLIC_HDX_LOCAL_DEFAULT_CONNECTIONS and NEXT_PUBLIC_HDX_LOCAL_DEFAULT_SOURCES supply JSON defaults in the browser instead. These values are public: don’t place production credentials in them.

AI assistant

Logging and self-instrumentation

These settings control telemetry emitted by ClickStack itself, not authentication for users or incoming application telemetry.

Optional features and deployment modes

NEXT_PUBLIC_IS_LOCAL_MODE is the frontend build flag for the Local Mode distribution. It isn’t a general-purpose development switch. Use the appropriate distribution rather than disabling authentication on an existing deployment. IS_LOCAL_MODE and IS_OSS are application constant names, not the environment variables to set. NEXT_PUBLIC_IS_OSS is a build setting; it isn’t an enterprise-edition switch. MINER_API_URL is no longer used by the current application. When using the supplied reverse-proxy configuration for a subpath, set HYPERDX_BASE_PATH and NEXT_PUBLIC_HYPERDX_BASE_PATH to the same prefix (for example /clickstack), and include the prefix in FRONTEND_URL. Some frontend settings are read at build time. In particular, changing NEXT_PUBLIC_HYPERDX_BASE_PATH (the deployment path prefix), NEXT_PUBLIC_NOINDEX (search-engine indexing), or the distribution’s mode flags requires building the frontend with those values. Runtime settings read through next-runtime-env, such as NEXT_PUBLIC_INSTANCE_LABEL, can be supplied to the container at startup.

OpenTelemetry collector

See ClickStack OpenTelemetry Collector for deployment instructions. Set collector variables on the collector container, not just the UI container. In Compose, declaring a value in .env only passes it to a container when docker-compose.yml references it.

Connection and authentication

Without OpAMP, OIDC, or OTLP_AUTH_TOKEN, the standalone OTLP receiver has no authentication. The ClickHouse account needs permission to insert telemetry and, when schema creation or migrations are enabled, to create or alter the required database objects.

Export, batching, and custom configuration

Schema and retention

The per-signal TTLs and reconciliation setting apply to the migration tool, which is skipped when legacy schema creation is enabled.

Migration TLS

These variables configure the migration tool’s ClickHouse connection. They don’t automatically configure exporter TLS; configure the collector exporters separately when using custom certificates.

Prometheus-compatible metrics

ClickHouse

ClickStack Open Source ships with a default ClickHouse configuration designed for multi-terabyte scale, but users are free to modify and optimize it to suit their workload. To tune ClickHouse effectively, you should understand key storage concepts such as parts, partitions, shards and replicas, and how merges occur at insert time. We recommend reviewing the fundamentals of primary indices, sparse secondary indices, and data skipping indices, along with techniques for managing data lifecycle e.g. using a TTL lifecycle. ClickStack supports schema customization - you may modify column types, extract new fields (e.g. from logs), apply codecs and dictionaries, and accelerate queries using projections. Additionally, materialized views can be used to transform or filter data during ingestion, provided that data is written to the source table of the view and the application reads from the target table. Materialized views can also be used to accelerate queries natively in ClickStack. For more details, refer to ClickHouse documentation on schema design, indexing strategies, and data management best practices - most of which apply directly to ClickStack deployments.