Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/promql-support.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"helm-charts": minor
---

feat: add PromQL support behind `hyperdx.promql.enabled` (on by default). Sets `ENABLE_PROMQL` and `NEXT_PUBLIC_ENABLE_PROMQL`, adds a PromQL default source on the `metrics_ts` TimeSeries table, and configures ClickHouse with Prometheus remote write/read handlers, the `prometheus_api_v1` HTTP handler and `allow_experimental_time_series_table` on the default profile, and grants the `app` user `CREATE TEMPORARY TABLE` so the handler can evaluate queries. The ClickHouse settings need ClickHouse 26.6 or newer and are skipped automatically on older image tags.
9 changes: 5 additions & 4 deletions charts/clickstack/README.md

Large diffs are not rendered by default.

62 changes: 62 additions & 0 deletions charts/clickstack/templates/_helpers.tpl
Original file line number Diff line number Diff line change
Expand Up @@ -312,6 +312,68 @@ ClickHouse headless service name. The operator creates a headless service named
{{- printf "%s-clickhouse-headless" (include "clickstack.clickhouse.fullname" .) -}}
{{- end }}

{{/*
Whether the ClickHouse PromQL config is injected into the ClickHouseCluster CR.
Needs hyperdx.promql.enabled and a ClickHouse server image of 26.6 or newer, the
first release with the prometheus_api_v1 handler. The tag is read from
clickhouse.cluster.spec.containerTemplate.image.tag; a four-part ClickHouse version
and an image-variant suffix such as "-alpine" are reduced to semver first. A tag
that carries no version (e.g. "latest") is assumed new enough. Renders "true" or "".
*/}}
{{- define "clickstack.clickhouse.promqlEnabled" -}}
{{- if .Values.hyperdx.promql.enabled -}}
{{- $tag := toString (dig "containerTemplate" "image" "tag" "" .Values.clickhouse.cluster.spec) -}}
{{- $version := regexFind "^[0-9]+\\.[0-9]+(\\.[0-9]+)?" $tag -}}
{{- if or (not $version) (semverCompare ">= 26.6" $version) }}true{{- end -}}
{{- end -}}
{{- end }}

{{/*
ClickHouse settings that back PromQL, merged under the user's
clickhouse.cluster.spec.settings by clickhouse/cluster.yaml. Mirrors the upstream
ClickStack config.xml/users.xml: Prometheus remote write/read into the TimeSeries
table the otel-collector creates, the Prometheus HTTP API on the main HTTP port, and
the experimental setting the TimeSeries engine needs. The metrics handler is
repeated because ClickHouse ignores its legacy prometheus.endpoint settings once a
handlers block exists.
*/}}
{{- define "clickstack.clickhouse.promqlSettings" -}}
{{- $database := .Values.hyperdx.config.HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE | default "default" }}
extraConfig:
prometheus:
handlers:
metrics_handler:
url: /metrics
handler:
type: expose_metrics
metrics: true
asynchronous_metrics: true
events: true
errors: true
remote_write_handler:
url: /write
handler:
type: remote_write
database: {{ $database | quote }}
table: metrics_ts
remote_read_handler:
url: /read
handler:
type: remote_read
database: {{ $database | quote }}
table: metrics_ts
http_handlers:
rule:
url_prefix: /prometheus/api/v1
handler:
type: prometheus_api_v1
defaults: ""
extraUsersConfig:
profiles:
default:
allow_experimental_time_series_table: 1
{{- end }}

{{/*
Render the chart-managed HyperDX ConfigMap from one canonical template so the
manifest and the Deployment rollout checksum cannot drift.
Expand Down
11 changes: 10 additions & 1 deletion charts/clickstack/templates/clickhouse/cluster.yaml
Original file line number Diff line number Diff line change
@@ -1,10 +1,19 @@
{{- if .Values.clickhouse.enabled }}
{{- $spec := deepCopy .Values.clickhouse.cluster.spec }}
{{- if include "clickstack.clickhouse.promqlEnabled" . }}
{{- /* Chart defaults go first so anything the user sets under settings wins. */}}
{{- $promql := include "clickstack.clickhouse.promqlSettings" . | fromYaml }}
{{- $settings := default (dict) $spec.settings }}
{{- $_ := set $settings "extraConfig" (mergeOverwrite (dict) $promql.extraConfig (default (dict) $settings.extraConfig)) }}
{{- $_ := set $settings "extraUsersConfig" (mergeOverwrite (dict) $promql.extraUsersConfig (default (dict) $settings.extraUsersConfig)) }}
{{- $_ := set $spec "settings" $settings }}
{{- end }}
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
name: {{ include "clickstack.clickhouse.fullname" . }}
labels:
{{- include "clickstack.labels" . | nindent 4 }}
spec:
{{- tpl (toYaml .Values.clickhouse.cluster.spec) . | nindent 2 }}
{{- tpl (toYaml $spec) . | nindent 2 }}
{{- end }}
22 changes: 22 additions & 0 deletions charts/clickstack/tests/app-configmap_test.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,28 @@ tests:
path: data.HDX_EXPORTER_ENABLED
value: "true"

- it: should enable the PromQL feature flags by default
asserts:
- equal:
path: data.ENABLE_PROMQL
value: "true"
- equal:
path: data.NEXT_PUBLIC_ENABLE_PROMQL
value: "true"

- it: should disable the PromQL feature flags when hyperdx.promql.enabled is false
set:
hyperdx:
promql:
enabled: false
asserts:
- equal:
path: data.ENABLE_PROMQL
value: "false"
- equal:
path: data.NEXT_PUBLIC_ENABLE_PROMQL
value: "false"

- it: should fail when the removed 1.x usageStatsEnabled key is set
set:
hyperdx:
Expand Down
231 changes: 231 additions & 0 deletions charts/clickstack/tests/clickhouse-promql_test.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,231 @@
suite: Test ClickHouse PromQL Settings
templates:
- clickhouse/cluster.yaml

tests:
- it: should inject Prometheus remote write and read handlers by default
asserts:
- equal:
path: spec.settings.extraConfig.prometheus.handlers.remote_write_handler.url
value: /write
- equal:
path: spec.settings.extraConfig.prometheus.handlers.remote_write_handler.handler
value:
type: remote_write
database: default
table: metrics_ts
- equal:
path: spec.settings.extraConfig.prometheus.handlers.remote_read_handler.url
value: /read
- equal:
path: spec.settings.extraConfig.prometheus.handlers.remote_read_handler.handler.type
value: remote_read

- it: should keep the metrics handler once a handlers block exists
asserts:
- equal:
path: spec.settings.extraConfig.prometheus.handlers.metrics_handler.url
value: /metrics
- equal:
path: spec.settings.extraConfig.prometheus.handlers.metrics_handler.handler.type
value: expose_metrics

- it: should expose the Prometheus HTTP API on the main HTTP port
asserts:
- equal:
path: spec.settings.extraConfig.http_handlers.rule.url_prefix
value: /prometheus/api/v1
- equal:
path: spec.settings.extraConfig.http_handlers.rule.handler.type
value: prometheus_api_v1
- equal:
path: spec.settings.extraConfig.http_handlers.defaults
value: ""

- it: should enable the TimeSeries table engine on the default profile
asserts:
- equal:
path: spec.settings.extraUsersConfig.profiles.default.allow_experimental_time_series_table
value: 1

- it: should keep the existing extraConfig and users next to the injected settings
asserts:
- equal:
path: spec.settings.extraConfig.max_connections
value: 4096
- equal:
path: spec.settings.extraConfig.query_log.ttl
value: event_date + INTERVAL 30 DAY DELETE
- isNotNull:
path: spec.settings.extraUsersConfig.users.app
- isNotNull:
path: spec.settings.extraUsersConfig.users.otelcollector

- it: should point remote write at the configured collector database
set:
hyperdx:
config:
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE: otel
asserts:
- equal:
path: spec.settings.extraConfig.prometheus.handlers.remote_write_handler.handler.database
value: otel
- equal:
path: spec.settings.extraConfig.prometheus.handlers.remote_read_handler.handler.database
value: otel

- it: should fall back to the default database when the collector database is empty
set:
hyperdx:
config:
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE: ""
asserts:
- equal:
path: spec.settings.extraConfig.prometheus.handlers.remote_write_handler.handler.database
value: default

- it: should let user settings win over the injected ones
set:
clickhouse:
cluster:
spec:
settings:
extraConfig:
prometheus:
handlers:
remote_write_handler:
handler:
table: custom_ts
extraUsersConfig:
profiles:
default:
allow_experimental_time_series_table: 0
max_memory_usage: 1000000
asserts:
- equal:
path: spec.settings.extraConfig.prometheus.handlers.remote_write_handler.handler.table
value: custom_ts
- equal:
path: spec.settings.extraConfig.prometheus.handlers.remote_write_handler.handler.type
value: remote_write
- equal:
path: spec.settings.extraUsersConfig.profiles.default.allow_experimental_time_series_table
value: 0
- equal:
path: spec.settings.extraUsersConfig.profiles.default.max_memory_usage
value: 1000000

- it: should inject settings when the spec has no settings block
set:
clickhouse:
cluster:
spec:
settings: null
asserts:
- isNull:
path: spec.settings.extraUsersConfig.users
- equal:
path: spec.settings.extraConfig.http_handlers.rule.handler.type
value: prometheus_api_v1
- equal:
path: spec.settings.extraUsersConfig.profiles.default.allow_experimental_time_series_table
value: 1

- it: should inject settings when settings has no extraConfig or extraUsersConfig
set:
clickhouse:
cluster:
spec:
settings:
extraConfig: null
extraUsersConfig: null
asserts:
- equal:
path: spec.settings.logger.level
value: information
- equal:
path: spec.settings.extraConfig.http_handlers.rule.handler.type
value: prometheus_api_v1
- equal:
path: spec.settings.extraUsersConfig.profiles.default.allow_experimental_time_series_table
value: 1

- it: should not inject settings when PromQL is disabled
set:
hyperdx:
promql:
enabled: false
asserts:
- isNull:
path: spec.settings.extraConfig.prometheus
- isNull:
path: spec.settings.extraConfig.http_handlers
- isNull:
path: spec.settings.extraUsersConfig.profiles
- equal:
path: spec.settings.extraConfig.max_connections
value: 4096

- it: should not inject settings on a ClickHouse image older than 26.6
set:
clickhouse:
cluster:
spec:
containerTemplate:
image:
tag: "25.7-alpine"
asserts:
- isNull:
path: spec.settings.extraConfig.prometheus
- isNull:
path: spec.settings.extraConfig.http_handlers
- isNull:
path: spec.settings.extraUsersConfig.profiles

- it: should not inject settings on a four-part tag just below 26.6
set:
clickhouse:
cluster:
spec:
containerTemplate:
image:
tag: "26.5.9.2"
asserts:
- isNull:
path: spec.settings.extraConfig.prometheus

- it: should inject settings on a two-part tag at 26.6
set:
clickhouse:
cluster:
spec:
containerTemplate:
image:
tag: "26.6"
asserts:
- isNotNull:
path: spec.settings.extraConfig.prometheus

- it: should inject settings on a tag without a version number
set:
clickhouse:
cluster:
spec:
containerTemplate:
image:
tag: latest
asserts:
- isNotNull:
path: spec.settings.extraConfig.prometheus

- it: should inject settings when no image tag is set
set:
clickhouse:
cluster:
spec:
containerTemplate:
image:
tag: null
asserts:
- isNotNull:
path: spec.settings.extraConfig.prometheus
8 changes: 8 additions & 0 deletions charts/clickstack/tests/clickhouse-users_test.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,14 @@ tests:
path: spec.settings.extraUsersConfig.users.app.profile
value: default

# The prometheus_api_v1 handler reads through the timeSeriesSelector() table function,
# and ClickHouse requires CREATE TEMPORARY TABLE to use any table function.
- it: should grant the app user CREATE TEMPORARY TABLE for PromQL queries
asserts:
- matchRegex:
path: spec.settings.extraUsersConfig.users.app.grants[0].query
pattern: CREATE TEMPORARY TABLE ON \*\.\*

- it: should include otelcollector user in extraUsersConfig
asserts:
- isNotNull:
Expand Down
11 changes: 11 additions & 0 deletions charts/clickstack/tests/default-env-vars_test.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,17 @@ tests:
path: spec.template.spec.containers[0].env[?(@.name == "DEFAULT_SOURCES")].value
pattern: '"exponential histogram": "otel_metrics_exponential_histogram"'

# HyperDX only creates promql-kind default sources when ENABLE_PROMQL is true,
# so the entry is safe to ship regardless of hyperdx.promql.enabled.
- it: should include a PromQL source backed by the TimeSeries table
asserts:
- matchRegex:
path: spec.template.spec.containers[0].env[?(@.name == "DEFAULT_SOURCES")].value
pattern: '"tableName": "metrics_ts"[^}]*}[^}]*"kind": "promql"'
- matchRegex:
path: spec.template.spec.containers[0].env[?(@.name == "DEFAULT_SOURCES")].value
pattern: '"kind": "promql",[^}]*"timestampValueExpression": "timestamp"'

- it: should not include DEFAULT_SOURCES when set to empty string
set:
hyperdx:
Expand Down
Loading
Loading