Self-Hosted ClickStack Observability

A fully self-hosted observability stack in a single container.

This guide walks you through setting up Qtap with ClickStack — a self-contained observability stack that bundles ClickHouse, an OTel collector, and the HyperDX UI into a single Docker image. Events and artifacts flow through OpenTelemetry, with no S3 setup required.

Quick version: Run ClickStack, point Qtap at it, see traffic in your browser. Total setup time: ~5 minutes.

---

What You'll Get

Component	What It Does	Port
ClickStack	ClickHouse + OTel collector + HyperDX UI	8080, 4317, 4318
Qtap	eBPF agent capturing traffic and sending via OTel	—

Both events (connection metadata, HTTP transactions) and objects (request/response headers and bodies) are sent through the same OTel endpoint. No separate object storage to configure.

---

Prerequisites

• Docker installed

• Linux host with kernel 5.8+ (for eBPF)

• Root or CAP_BPF + CAP_SYS_ADMIN capabilities

---

Step 1: Start ClickStack

docker run -d --name clickstack \
   -p 8080:8080 \
   -p 4317:4317 \
   -p 4318:4318 \
   -e BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true \
   clickhouse/clickstack-local:latest

Wait for it to be ready:

docker logs -f clickstack

Once you see the startup complete, visit http://localhost:8080 to access the HyperDX UI.

---

Step 2: Create the Qtap Configuration

Create a file called qtap-clickstack.yaml:

version: 2
services:
    event_stores:
        - type: otel
          endpoint: "localhost:4317"
          protocol: grpc
          service_name: "qtap"
          environment: "production"
          tls:
              enabled: false
    object_stores:
        - type: otel
          otel_endpoint: "localhost:4317"
          protocol: grpc
          service_name: "qtap"
          environment: "production"
          tls:
              enabled: false
stacks:
    basic_reporting:
        plugins:
            - type: http_capture
              config:
                  level: full
                  format: json
            - type: report_usage
tap:
    direction: egress
    ignore_loopback: true
    audit_include_dns: false
    http:
        stack: basic_reporting

This configuration:

• Sends events (connection metadata, HTTP transaction summaries) to ClickStack via OTel

• Sends objects (full request/response headers and bodies) to ClickStack via OTel

• Captures all egress HTTP traffic at full detail level

• Both stores share the same OTel endpoint — no S3 credentials needed

This replaces many small S3 files with batched OTLP log records, which ClickHouse ingests efficiently.

---

Step 3: Start Qtap

docker run -d --name qtap \
  --user 0:0 --privileged \
  --pid=host --network=host \
  -v /sys:/sys \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd)/qtap-clickstack.yaml:/app/config/qtap.yaml" \
  -e TINI_SUBREAPER=1 \
  --ulimit=memlock=-1 \
  us-docker.pkg.dev/qpoint-edge/public/qtap:v0 \
  --log-level=info \
  --log-encoding=console \
  --config="/app/config/qtap.yaml"

Verify Qtap is running and connected:

docker logs qtap 2>&1 | tail -20

You should see the eventstore and objectstore initialize successfully:

INFO    eventstore.otel initialized
INFO    objectstore.otel initialized

---

Step 4: Generate Traffic and View

Generate some traffic:

curl https://httpbin.org/get
curl https://api.github.com
curl -X POST https://httpbin.org/post -d '{"test": "data"}'

Open http://localhost:8080 in your browser. In the HyperDX UI, create a source with table name otel_logs to view captured events and artifacts.

You'll see:

• Connection events — TCP connections with protocol detection, TLS info, process attribution

• HTTP transaction summaries — method, URL, status, duration, content type

• Full request/response data — headers and bodies captured by the http_capture plugin

---

How It Works

Your Applications
       │
       │  (HTTP/HTTPS traffic)
       ▼
    Qtap (eBPF)
       │
       ├── Events ──→ OTel (gRPC :4317) ──→ ClickStack ──→ ClickHouse
       │
       └── Objects ──→ OTel (gRPC :4317) ──→ ClickStack ──→ ClickHouse

Qtap captures traffic using eBPF and exports both event metadata and full artifacts as OpenTelemetry Logs. ClickStack receives them through its built-in OTel collector and stores everything in ClickHouse.

---

Configuration Options

Capture Level

Control how much detail is captured per request:

Level	What's Captured
none	Connection metadata only
summary	HTTP method, URL, status, duration
details	Summary + headers
full	Summary + headers + bodies

Change the level in the http_capture plugin:

plugins:
    - type: http_capture
      config:
          level: summary    # Less data, lower storage
          format: json

Traffic Direction

Control which traffic is captured:

Direction	What's Captured
egress	All outbound traffic
egress-external	Only external destinations
egress-internal	Only internal destinations

---

Cleanup

docker rm -f qtap clickstack

---

Next Steps

• Storage Configuration — Compare OTel vs S3 object storage options

• Traffic Processing with Plugins — Filter and transform captured traffic

• OTel Object Store Release Notes — Feature details

• Sample Configuration — Reference config on GitHub