OTel profiles

Composable OpenTelemetry collector configuration, one fragment per class of machine. ClickStack ingests everything through OTel, so what a GPU node, a bare-metal server with a BMC, a KVM hypervisor and a vSphere cluster each need is a different set of receivers — not a different stack. These are those sets, written so they merge rather than replace each other.

Read CONVENTIONS.md before adding or editing one. The first three rules there are not style: breaking one disables ClickStack's own ingestion with no error at startup.

Profiles

Profile	Tier	Collects	deploy.platform
linux-host	A	OS metrics and syslog from any Linux machine	host
gpu-nvidia	A	NVIDIA GPU telemetry via dcgm-exporter	gpu
baremetal-node	A	in-band hwmon plus out-of-band BMC sensors	baremetal
virt-kvm	A	KVM/libvirt per-domain counters and hypervisor OS	vm
virt-vsphere	B	vSphere clusters, hosts, VMs, datastores	vm
mysql	A+B	self-managed MySQL: engine metrics, error and slow query logs	host
aws-rds-mysql	B	MySQL on RDS: engine metrics plus CloudWatch instance metrics, Enhanced Monitoring and logs	managed

None carry a Verified on … line yet: each needs its own class of hardware (or, for aws-rds-mysql, a real RDS instance) to run against, and per AGENTS.md the claim waits for an end-to-end run confirmed by SQL.

Tier A and Tier B

ClickStack does not ship otelcol-contrib. It is an OCB build (otelcol-hyperdx) whose receivers are only nop, otlp, datadog, dockerstats, filelog, fluentforward, hostmetrics, k8scluster, kubeletstats, prometheus and statsd.

Tier	Ships	Runs where
A	custom.config.yaml	inside ClickStack, merged into its config
B	sidecar.config.yaml	a separate contrib collector, OTLP to ClickStack

The prometheus receiver is why most hardware profiles stay in Tier A: scraping an exporter that already exists needs no new receiver, and dcgm-exporter, node_exporter, ipmi_exporter and the libvirt exporters all speak Prometheus.

Use

Merge the profiles you want into one file — ClickStack takes exactly one custom config:

./bin/build-config.sh linux-host gpu-nvidia > custom.config.yaml

Mount it and point ClickStack at it:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/custom.config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /:/hostfs:ro \
  clickhouse/clickstack-all-in-one:latest

Tier B instead builds a sidecar config and runs it next to ClickStack:

./bin/build-config.sh --tier b virt-vsphere > sidecar/sidecar.config.yaml
cd sidecar && docker compose --env-file .env up -d

Profiles compose because each names its components and pipelines after itself, so a deep merge has nothing to reconcile. build-config.sh refuses the merge if two profiles ever do collide on a pipeline name.

Checks

./bin/lint.sh                                  # conventions, all profiles
./bin/build-config.sh linux-host > /dev/null   # merge cleanly
CH_URL=http://localhost:8123 ./bin/verify.sh linux-host

verify.sh runs the profile's verify.sql against ClickHouse and prints each result. An empty result means nothing was ingested — a failed verification, not a pass.

Layout

Path	What it is
CONVENTIONS.md	the rules every profile follows, and why
bin/build-config.sh	merge selected profiles into one config
bin/lint.sh	enforce the conventions
bin/verify.sh	run a profile's verify.sql
common/resource.yaml	shared resourcedetection, merged into every Tier A build
sidecar/	Tier B base config and compose file
profiles/<name>/	README.md, config fragment, .env.example, metrics.md, verify.sql

Reference versions

Written against HyperDX 2.39.1, collector components 0.155.0, core 1.61.0, semantic conventions 1.44.0. The hw.* hardware conventions are at Development stability, and the vcenter receiver is alpha — pin your sidecar image.

---

./bin/build-config.sh linux-host gpu-nvidia > custom.config.yaml

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/custom.config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /:/hostfs:ro \
  clickhouse/clickstack-all-in-one:latest

./bin/build-config.sh --tier b virt-vsphere > sidecar/sidecar.config.yaml
cd sidecar && docker compose --env-file .env up -d

./bin/lint.sh                                  # 전체 프로파일 규약 검사
./bin/build-config.sh linux-host > /dev/null   # 병합 확인
CH_URL=http://localhost:8123 ./bin/verify.sh linux-host