Configuration Options

#### Metrics[​](#metrics "Direct link to Metrics")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Setting Description Required Inferred in Default Schema Inferred Value|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `Name` Source name. Yes No –|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `Server Connection` Server connection name. Yes No `Default`| `Database` ClickHouse database name. Yes Yes `default`| `Gauge Table` Table storing gauge-type metrics. Yes No `otel_metrics_gauge`| `Histogram Table` Table storing histogram-type metrics. Yes No `otel_metrics_histogram`| `Sum Table` Table storing sum-type (counter) metrics. Yes No `otel_metrics_sum`| `Correlated Log Source` Optional. Linked log source (e.g. HyperDX logs). No No – | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

#### Sessions[​](#settings "Direct link to Sessions")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Setting Description Required Inferred in Default Schema Inferred Value|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `Name` Source name. Yes No –|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `Server Connection` Server connection name. Yes No `Default`| `Database` ClickHouse database name. Yes Yes `default`| `Table` Target table for session data. Target table name. Set to `hyperdx_sessions` if using the default schema. Yes Yes -|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `Timestamp Column` Datetime column or expression that's part of your primary key. Yes Yes `TimestampTime`| `Log Attributes Expression` Expression for extracting log-level attributes from session data. Yes Yes `LogAttributes`| `LogAttributes` Alias or field reference used to store log attributes. Yes Yes `LogAttributes`| `Resource Attributes Expression` Expression for extracting resource-level metadata. Yes Yes `ResourceAttributes`| `Correlated Trace Source` Optional. Linked trace source for session correlation. No No –|  |  |  |  |  | | --- | --- | --- | --- | --- | | `Implicit Column Expression` Column used for full-text search when no field is specified (e.g. Lucene-style query parsing). Yes Yes `Body` | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

#### Highlighted Attributes[​](#highlighted-attributes "Direct link to 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.

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[​](#correlated-sources "Direct link to 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[​](#application-configuration-settings "Direct link to Application configuration settings")

HyperDX in ClickHouse Cloud

These settings can't be modified when HyperDX is managed in ClickHouse Cloud.

- `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`