Skip to main content

ClickStack Documentation

Welcome to the ClickStack documentation - a local observability stack for testing and development.

What is ClickStack?​

ClickStack is a complete observability solution combining:

  • nginx with ngx_otel_module - Generates traces from HTTP requests
  • OTEL Collector - Receives, processes, and exports telemetry data
  • ClickHouse - High-performance columnar database for trace storage
  • Grafana - Visualization and dashboards

Quick Start​

cd /opt/work/pne/infra/clickstack-local

# Start the stack
podman-compose up -d

# Generate test traces
./scripts/test-traces.sh 100

# Check trace count
curl -s "http://localhost:18123/?query=SELECT+COUNT(*)+FROM+otel.otel_traces"

Architecture Overview​

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   nginx     │────▶│  OTEL Col   │────▶│ ClickHouse  │────▶│   Grafana   │
│ (traces)    │     │ (process)   │     │ (storage)   │     │ (visualize) │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
     :18080              :4317              :18123              :13000

Key Features​

  • Persistent Queues - Zero trace loss during backend outages
  • WAL Buffering - Write-Ahead Log for durability
  • Multi-Backend Export - ClickHouse, Uptrace, VictoriaLogs
  • Podman Rootless - Secure container runtime