Configuration options

The following configuration options are available for each component of ClickStack:

Settings for open source distributions

Docker

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

docker run  -e HYPERDX_LOG_LEVEL='debug' -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest

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.yaml file e.g.

Example:

services:
  app:
    environment:
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      # ... other settings

Helm

Customizing values (optional)

You can customize settings by using --set flags e.g.

helm install my-hyperdx hyperdx/hdx-oss-v2 \
  --set replicaCount=2 \
  --set resources.limits.cpu=500m \
  --set resources.limits.memory=512Mi \
  --set resources.requests.cpu=250m \
  --set resources.requests.memory=256Mi \
  --set ingress.enabled=true \
  --set ingress.annotations."kubernetes\.io/ingress\.class"=nginx \
  --set ingress.hosts[0].host=hyperdx.example.com \
  --set ingress.hosts[0].paths[0].path=/ \
  --set ingress.hosts[0].paths[0].pathType=ImplementationSpecific \
  --set env[0].name=CLICKHOUSE_USER \
  --set env[0].value=abc

Alternatively edit the values.yaml. To retrieve the default values:

helm show values hyperdx/hdx-oss-v2 > values.yaml

Example config:

replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  env:
    - name: CLICKHOUSE_USER
      value: abc

ClickStack UI (HyperDX) application

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:

Each of these sources require at least one table specified on creation and a set of columns which allow HyperDX to query the data.

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 following settings are available for each source:

Logs

Traces

Metrics

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:

These attributes are displayed in the side panel after clicking on a log or span:

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.

Correlated sources

To enable full cross-source correlation in ClickStack, you must configure correlated sources for logs, traces, metrics, and sessions. This allows HyperDX 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, HyperDX 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:

Application configuration settings

• HYPERDX_API_KEY

  • Default: None (required)
  • Description: Authentication key for the HyperDX API.
  • Guidance:
  • Required for telemetry and logging
  • In local development, can be any non-empty value
  • For production, use a secure, unique key
  • Can be obtained from the team settings page after account creation

• HYPERDX_LOG_LEVEL

  • Default: info
  • Description: Sets the logging verbosity level.
  • Options: debug, info, warn, error
  • Guidance:
  • Use debug for detailed troubleshooting
  • Use info for normal operation
  • Use warn or error in production to reduce log volume

• HYPERDX_API_PORT

  • Default: 8000
  • Description: Port for the HyperDX API server.
  • Guidance:
  • Ensure this port is available on your host
  • Change if you have port conflicts
  • Must match the port in your API client configurations

• HYPERDX_APP_PORT

  • Default: 8000
  • Description: Port for the HyperDX frontend app.
  • Guidance:
  • Ensure this port is available on your host
  • Change if you have port conflicts
  • Must be accessible from your browser

• HYPERDX_APP_URL

  • Default: http://localhost
  • Description: Base URL for the frontend app.
  • Guidance:
  • Set to your domain in production
  • Include protocol (http/https)
  • Don’t include trailing slash

• MONGO_URI

  • Default: mongodb://db:27017/hyperdx
  • Description: MongoDB connection string.
  • Guidance:
  • Use default for local development with Docker
  • For production, use a secure connection string
  • Include authentication if required
  • Example: mongodb://user:pass@host:port/db

• MINER_API_URL

  • Default: http://miner:5123
  • Description: URL for the log pattern mining service.
  • Guidance:
  • Use default for local development with Docker
  • Set to your miner service URL in production
  • Must be accessible from the API service

• FRONTEND_URL

  • Default: http://localhost:3000
  • Description: URL for the frontend app.
  • Guidance:
  • Use default for local development
  • Set to your domain in production
  • Must be accessible from the API service

• OTEL_SERVICE_NAME

  • Default: hdx-oss-api
  • Description: Service name for OpenTelemetry instrumentation.
  • Guidance:
  • Use descriptive name for your HyperDX service. Applicable if HyperDX self-instruments.
  • Helps identify the HyperDX service in telemetry data

• NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT

  • Default: http://localhost:4318
  • Description: OpenTelemetry collector endpoint.
  • Guidance:
  • Relevant of self-instrumenting HyperDX.
  • Use default for local development
  • Set to your collector URL in production
  • Must be accessible from your HyperDX service

• USAGE_STATS_ENABLED

  • Default: true
  • Description: Toggles usage statistics collection.
  • Guidance:
  • Set to false to disable usage tracking
  • Useful for privacy-sensitive deployments
  • Default is true for better product improvement

• IS_OSS

  • Default: true
  • Description: Indicates if running in OSS mode.
  • Guidance:
  • Keep as true for open-source deployments
  • Set to false for enterprise deployments
  • Affects feature availability

• IS_LOCAL_MODE

  • Default: false
  • Description: Indicates if running in local mode.
  • Guidance:
  • Set to true for local development
  • Disables certain production features
  • Useful for testing and development

• EXPRESS_SESSION_SECRET

  • Default: hyperdx is cool 👋
  • Description: Secret for Express session management.
  • Guidance:
  • Change in production
  • Use a strong, random string
  • Keep secret and secure

• ENABLE_SWAGGER

  • Default: false
  • Description: Toggles Swagger API documentation.
  • Guidance:
  • Set to true to enable API documentation
  • Useful for development and testing
  • Disable in production

• BETA_CH_OTEL_JSON_SCHEMA_ENABLED

  • Default: false
  • Description: Enables Beta support for the JSON type in HyperDX. See also OTEL_AGENT_FEATURE_GATE_ARG to enable JSON support in the OTel collector.
  • Guidance:
    • Enables a beta feature. JSON-typed schemas are not recommended for typical observability workloads. See Map vs JSON type for the comparison and when each is appropriate.
    • Set to true to enable JSON support in the ClickStack UI.

OpenTelemetry collector

See “ClickStack OpenTelemetry Collector” for more details.

• CLICKHOUSE_ENDPOINT

  • Default: None (required) if standalone image. If All-in-one or Docker Compose distribution this is set to the integrated ClickHouse instance.
  • Description: The HTTPS URL of the ClickHouse instance to export telemetry data to.
  • Guidance:
    • Must be a full HTTPS endpoint including port (e.g., https://clickhouse.example.com:8443)
    • Required for the collector to send data to ClickHouse

• CLICKHOUSE_USER

  • Default: default
  • Description: Username used to authenticate with the ClickHouse instance.
  • Guidance:
    • Ensure the user has INSERT and CREATE TABLE permissions
    • Recommended to create a dedicated user for ingestion

• CLICKHOUSE_PASSWORD

  • Default: None (required if authentication is enabled)
  • Description: Password for the specified ClickHouse user.
  • Guidance:
    • Required if the user account has a password set
    • Store securely via secrets in production deployments

• HYPERDX_LOG_LEVEL

  • Default: info
  • Description: Log verbosity level for the collector.
  • Guidance:
    • Accepts values like debug, info, warn, error
    • Use debug during troubleshooting

• OPAMP_SERVER_URL

  • Default: None (required) if standalone image. If All-in-one or Docker Compose distribution this points to the deployed HyperDX instance.
  • Description: URL of the OpAMP server used to manage the collector (e.g., HyperDX instance). This is port 4320 by default.
  • Guidance:
    • Must point to your HyperDX instance
    • Enables dynamic configuration and secure ingestion
    • If omitted, secure ingestion is disabled unless an OTLP_AUTH_TOKEN value is specified.

• OTLP_AUTH_TOKEN

  • Default: None. Used only for standalone image.
  • Description: Allows an OTLP authentication token to be specified. If set, all communication requires this bearer token.
  • Guidance:
    • Recommended if using the standalone collector image in production.

• HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE

  • Default: default
  • Description: ClickHouse database the collector writes telemetry data to.
  • Guidance:
    • Set if using a custom database name
    • Ensure the specified user has access to this database

• OTEL_AGENT_FEATURE_GATE_ARG

  • Default: <empty string>
  • Description: Enables feature flags in the collector. If set to --feature-gates=clickhouse.json, enables Beta support for the JSON type in the collector, ensuring schemas are created with that type. See also BETA_CH_OTEL_JSON_SCHEMA_ENABLED to enable JSON support in HyperDX.
  • Guidance:
    • Enables a beta feature. JSON-typed schemas are not recommended for typical observability workloads. See Map vs JSON type for the comparison and when each is appropriate.
    • Set to --feature-gates=clickhouse.json to create new tables using the JSON type.

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.