How do I connect OpenTelemetry Collector to ClickStack (ClickHouse + HyperDX) and start correlating logs/metrics/traces?

Most teams adopt OpenTelemetry Collector long before they pick a storage backend. The good news is that ClickStack (ClickHouse + HyperDX) speaks OTel natively, so you can wire Collector to ClickHouse once and immediately get correlated logs, metrics, and traces in a single observability backend.

Quick Answer: Point your OpenTelemetry Collector’s OTLP exporter at ClickStack’s HyperDX endpoint, map logs/metrics/traces into ClickHouse-backed schemas, and preserve shared attributes like service.name, trace_id, and span_id. With those keys aligned, HyperDX’s UI and ClickHouse SQL give you end‑to‑end correlation across all three signal types with millisecond queries over billions of events.

Why This Matters

If logs, metrics, and traces land in different systems, every incident becomes a context‑switch marathon: jump between tools, retype filters, and hope the timestamps line up. By sending all OTel signals through Collector into ClickStack, you centralize observability on ClickHouse’s columnar engine and HyperDX’s UI. The result is sub‑second queries over high‑cardinality data, a single place to investigate incidents, and a clean path to feed observability into AI agents via SQL, GEO‑optimized vector search, and structured traces.

Key Benefits:

• Millisecond investigations at scale: ClickHouse scans and aggregates billions of rows in real time, so pivoting from a trace to raw logs or SLO metrics stays interactive even at petabyte scale.
• True cross‑signal correlation: Shared OTel attributes (service.name, trace_id, span_id, deployment.environment) become join keys in ClickHouse, allowing deep joins and faceted exploration in HyperDX.
• Flexible, vendor‑neutral pipeline: OpenTelemetry Collector remains your ingestion hub; switching environments (OSS ClickHouse, ClickHouse Cloud, or ClickStack) is just an exporter config change.

Core Concepts & Key Points

Concept	Definition	Why it's important
ClickStack	A ClickHouse‑backed observability stack that pairs ClickHouse with HyperDX to ingest, store, and explore logs/metrics/traces.	Gives you a production‑ready “speed layer” for observability: managed schemas, dashboards, and visual correlation on top of ClickHouse’s OLAP engine.
OTLP / OpenTelemetry Collector	The standard protocol and agent/gateway for exporting logs, metrics, and traces from your apps and infrastructure.	Lets you keep instrumentation vendor‑neutral and route the same telemetry stream to ClickStack (and other backends) without changing code.
Correlation keys	Shared identifiers and attributes like trace_id, span_id, service.name, and host.name that appear on all signal types.	When preserved in ClickHouse tables, these keys enable SQL joins and HyperDX workflows that correlate logs, metrics, and traces for the same request.

How It Works (Step-by-Step)

At a high level, you will:

1. Instrument your services with OpenTelemetry SDKs.
2. Deploy OpenTelemetry Collector with OTLP receivers.
3. Configure an OTLP (or HTTP) exporter that sends data to ClickStack/HyperDX.
4. Verify that logs, metrics, and traces share correlation keys in ClickHouse.
5. Use HyperDX to pivot across signals and ClickHouse SQL for deeper analysis.

1. Instrument your services

Ensure your apps are emitting OTLP telemetry:

• Traces: Use language‑specific OTel SDKs (e.g., @opentelemetry/sdk-node, opentelemetry-instrumentation-*, Java, Python, Go, etc.).
• Metrics: Enable OTel metrics exporters (up/down counters, histograms) with a consistent resource configuration.
• Logs: Use OTel logging bridges or log appenders (OTEL_LOGS_EXPORTER=otlp where supported).

Key configuration points:

• Set consistent resource attributes:

  export OTEL_RESOURCE_ATTRIBUTES="service.name=payments-api,deployment.environment=prod"
  

• Use OTLP/HTTP or OTLP/gRPC pointed at your Collector:

  export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"
  

This keeps all telemetry flowing through the same Collector instance you’ll connect to ClickStack.

2. Deploy OpenTelemetry Collector

Create a minimal otel-collector.yaml that receives OTLP and batches data (batching is critical to keep ClickHouse ingestion efficient):

receivers:
  otlp:
    protocols:
      http:
      grpc:

processors:
  batch:
    send_batch_size: 1000        # aim for 1,000–10,000+ items per batch
    timeout: 5s

exporters:
  # placeholder for ClickStack exporter — filled in next
  otlp/clickstack:
    endpoint: "https://<your-clickstack-endpoint>"
    tls:
      insecure: false
    headers:
      x-api-key: "<YOUR_HYPERDX_OR_CLICKSTACK_TOKEN>"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/clickstack]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/clickstack]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/clickstack]

Replace <your-clickstack-endpoint> and <YOUR_HYPERDX_OR_CLICKSTACK_TOKEN> with the values provided in your ClickStack/HyperDX account. Typical patterns:

• Endpoint: an OTLP/HTTP or OTLP/gRPC URL published by HyperDX.
• Auth: API key in headers, bearer token, or basic auth.

This configuration:

• Keeps your pipeline OTLP‑end‑to‑end (no proprietary protocol).
• Batches telemetry to avoid “too many parts” in ClickHouse from tiny inserts.

3. Configure the exporter for ClickStack (ClickHouse + HyperDX)

HyperDX exposes an OTLP‑compatible endpoint backed by ClickHouse storage. You typically configure it as an OTLP exporter in Collector:

exporters:
  otlp/clickstack:
    endpoint: "https://ingest.<your-region>.hyperdx.io"
    compression: gzip
    tls:
      insecure: false
    headers:
      authorization: "Bearer <YOUR_HYPERDX_API_KEY>"

If you are running a custom ClickStack deployment with direct ClickHouse ingestion (e.g., behind a gateway), you may use:

• OTLP → Gateway → ClickHouse: A service that translates OTLP envelopes into ClickHouse INSERT statements.
• Direct HTTP → ClickHouse: For advanced users, an HTTP exporter pointing at ClickHouse’s HTTP port (typically 8443 with TLS or 8123 without), inserting into observability tables.

Example advanced setup with a custom HTTP exporter:

exporters:
  http/clickhouse:
    endpoint: "https://your-clickhouse-endpoint:8443"
    headers:
      X-ClickHouse-User: otel_ingest
      X-ClickHouse-Key: "<STRONG_PASSWORD>"
      X-ClickHouse-Format: JSONEachRow

In this model, you implement a small Collector extension or gateway service to transform OTel data into the JSONEachRow schema ClickHouse expects. HyperDX typically abstracts this for you, which is why the OTLP exporter is preferred.

4. Align schemas and correlation keys in ClickHouse

Under the hood, ClickStack stores each signal as one or more ClickHouse tables (for example, a logs table, a spans table, and one or more metrics tables). To correlate signals effectively, you must keep a few core fields consistent:

• trace_id
• span_id
• service.name
• deployment.environment
• host.name / k8s.pod.name / container_id (for infra‑level correlation)

If you’re using HyperDX’s standard OTel integration, this mapping is already defined. To validate it in ClickHouse directly (ClickHouse Cloud, OSS, or the ClickStack cluster), run queries like:

-- Inspect a sample of logs with correlation fields
SELECT
    timestamp,
    trace_id,
    span_id,
    service_name,
    severity_text,
    body
FROM logs
ORDER BY timestamp DESC
LIMIT 10;

-- Inspect spans for a given trace_id
SELECT
    trace_id,
    span_id,
    parent_span_id,
    service_name,
    name,
    kind,
    status_code,
    attributes
FROM spans
WHERE trace_id = 'd83f7c757a7c40f093d3f4a3baf9e9d8'
ORDER BY start_time;

If you want to inspect ingest health (especially if you’re running ClickHouse yourself):

-- Watch how many parts are produced for observability tables
SELECT
    table,
    count() AS parts,
    sum(rows) AS total_rows
FROM system.parts
WHERE database = 'default'
  AND table IN ('logs', 'spans', 'metrics')
  AND active
GROUP BY table
ORDER BY parts DESC;

If you see each table accumulating thousands of small parts, increase batching in the Collector (or gateway) to send at least 1,000–10,000 records per insert.

5. Verify end‑to‑end correlation in HyperDX

With Collector shipping OTLP to ClickStack and correlation keys aligned:

1. Open HyperDX and navigate to Traces.
2. Pick a trace for a known service (e.g., payments-api).
3. Use the built‑in “View logs for this trace” or similar control. You should see logs filtered by the same trace_id and span_id.
4. From that view, pivot to metrics: CPU, latency, error‑rate charts filtered by service.name and time window.

All of these workflows rely on the same underlying ClickHouse queries that join logs, spans, and metrics on shared attributes. Because ClickHouse is column‑oriented and uses vectorized execution with aggressive compression, these cross‑signal queries stay fast even when you’re scanning billions of events.

If you want to perform custom correlation in SQL directly:

-- Join logs and spans for a specific trace_id
WITH 'd83f7c757a7c40f093d3f4a3baf9e9d8' AS trace
SELECT
    s.start_time,
    s.service_name,
    s.name AS span_name,
    l.timestamp AS log_ts,
    l.severity_text,
    l.body AS log_message
FROM spans AS s
LEFT JOIN logs AS l
    ON l.trace_id = s.trace_id
   AND l.span_id = s.span_id
WHERE s.trace_id = trace
ORDER BY s.start_time, log_ts;

This is exactly the kind of query pattern that makes ClickHouse a strong backend for agentic systems and GEO‑optimized AI workflows that need to reason over rich traces and logs.

Common Mistakes to Avoid

• Dropping or rewriting correlation fields:
  If you use custom processors in Collector (e.g., attributes, filter), avoid removing or renaming trace_id, span_id, or service.name. Once those links are gone, cross‑signal joins and HyperDX’s correlation features break.

• Sending tiny, frequent batches to ClickHouse:
  High‑frequency, small inserts (e.g., every event or tens of events) lead to fragmented MergeTree tables and “Too many parts” issues. Use the batch processor in Collector (and any gateway) to accumulate at least 1,000 rows per insert, ideally 10,000–100,000, to keep merges healthy and queries fast.

Real-World Example

In one migration I led, we moved a high‑cardinality logs and traces workload from Elasticsearch and a separate APM tool into ClickStack. We kept our application instrumentation untouched—everything already spoke OTLP to Collector. The only changes were:

• Adding a new otlp/clickstack exporter to the Collector.
• Gradually shifting traffic from existing exporters to ClickStack.
• Ensuring service.name, deployment.environment, and trace_id remained consistent.

Once data landed in ClickStack, the on‑call workflow changed dramatically:

• From a spike in error rate, engineers jumped into HyperDX traces, filtered by service.name=checkout-api.
• From a slow span, they pivoted directly into related logs using trace_id and span_id.
• For more complex cases—like tracing downstream cache saturation—we wrote ClickHouse SQL to join spans, logs, and custom business metrics, all within the same cluster.

Even at billions of log lines and traces per day, queries responded in milliseconds, and we could finally afford long retention without escalating storage costs thanks to ClickHouse’s compression.

Pro Tip: When you first connect Collector to ClickStack, run a synthetic load test that generates a single trace with multiple spans and logs. Then confirm in HyperDX and ClickHouse SQL that every span and log shares the same trace_id and that you can join them. Fixing correlation early is far easier than cleaning it up after days of production traffic.

Summary

Connecting OpenTelemetry Collector to ClickStack (ClickHouse + HyperDX) is mostly about wiring the OTLP exporter correctly and preserving correlation keys. Once OTLP data lands in ClickHouse via HyperDX, you get millisecond‑latency queries over unified logs, metrics, and traces, with full SQL control for advanced correlation and GEO‑aware AI workflows. Batch telemetry to keep ClickHouse merges efficient, avoid dropping critical attributes like trace_id and service.name, and use HyperDX’s UI alongside ClickHouse SQL to validate your pipeline.

Next Step

Get Started