Source

A data source is a set of settings that hold the Clickhouse table to query from as well as the mapping of the various columns to observability concepts in HyperDX.

Create a Source

You'll be first prompted to create a source at startup. Afterwards, you can manage sources either from a source selection dropdown or on the team settings page.

Within a source, all "Expression" fields can either be a column ex. ColumnA or a full SQL expression such as parseDateTime64BestEffort(TsColumn).

A source requires the following fields to be specified:

• Name: A name for the source to identify it later.
• Connection: The Clickhouse connection to use for querying.
• Database: The Clickhouse database to query from.
• Table: The Clickhouse table to query from.
• Timestamp Column: The DateTime column in the table that represents the timestamp of the event.
• Default Select: This is a SQL SELECT expression for the columns to select in the search page. We typically recommend showing the timestamp, event level, service name, and the message of the event (log body or span name). We do not recommend filling * for performance reasons.

Creating a Log Source

If you're querying a log table in Clickhouse, you can optionally configure the following fields:

• Service Name Expression: String column for the name of the service associated with the log.
• Log Level Expression: String column for the log level (ex. info, warn) for the log.
• Resource Attributes Expression: Map column that contains the OpenTelemetry-based Resource Attributes map.
• Log Attributes Expression:
• Correlated Trace Source: HyperDX Source for traces correlated with this log source.
• Trace Id Expression: String column for the trace id associated with the log.
• Span Id Expression: String column for the span id associated with the log.
• Implicit Column Expression: A string column that will be searched upon when the user enters a bare string in the search bar in Lucene mode (ex. "errors")

Creating a Trace Source

If you're querying a trace table in Clickhouse, you'll need to configure the following fields:

• Duration Expression: Duration column in the table that represents the duration of the span.

• Duration Precision: The precision of the duration column in the table (seconds, milliseconds, nanoseconds, etc.).

• Trace Id Expression: String column for the trace id associated with the span.

• Span Id Expression: String column for the span id of the span.

• Parent Span Id Expression: String column for the parent span id of the span.

• Span Name Expression: String column for the name of the span.

• Correlated Log Source: HyperDX Source for logs correlated with this trace source.

• Status Code Expression: String column for the status code (opens in a new tab) of the span (ex. error, ok, unset).

• Status Message Expression: String column for the status message of the span (typically an error message).

• Service Name Expression: String column for the name of the service associated with the span.

• Span Kind Expression: String column for the kind of span (opens in a new tab) (ex. server, client).

• Service Name Expression: String column for the name of the service associated with the log.

• Log Level Expression: String column for the log level (ex. info, warn) for the log.

• Resource Attributes Expression: Map column that contains the OpenTelemetry-based Resource Attributes map.

• Log Attributes Expression:

• Correlated Trace Source: HyperDX Source for traces correlated with this log source.

• Implicit Column Expression: A string column that will be searched upon when the user enters a bare string in the search bar in Lucene mode (ex. "errors")