K-O11y Server

K-O11y Server — the backend. Self-hosted observability platform with ServiceMap, S3 Tiering, and SSO.

English | 한국어 | 日本語 | 中文

Built on ClickHouse and the OpenTelemetry ecosystem.

• 🗺️ ServiceMap — Microservice dependency topology visualization with batch processing
• 💾 S3 3-Tier Storage — Hot (EBS) → Warm (S3 Standard) → Cold (S3 Glacier IR) tiering
• 🔐 SSO Tenant Auto-Lock — JWT-based multi-tenant SSO with automatic workspace binding
• 🔍 Distributed Tracing — ClickHouse-based trace storage and query
• 📊 Metrics Monitoring — Prometheus-compatible metric collection and dashboards
• 📜 Log Management — Structured log collection and search
• 🔔 Alerting — AlertManager-based alert rules and channel management
• 🔒 AES-256-GCM Encryption — Encrypted storage of S3 credentials and sensitive config

K-O11y Server is a monorepo backend composed of two packages: a Go-based core API (ServiceMap batch processor, S3 Tiering API) and the packages/signoz directory providing the React frontend and Query Service. Both talk to a shared ClickHouse cluster.

flowchart TB
    subgraph Clients["Client Layer"]
        User[👤 User / Operator]
        OTel[OTel Collectors<br/>from Agent clusters]
    end

    subgraph Server["K-O11y Server (this repo)"]
        subgraph CorePkg["packages/core (Go 1.24)"]
            CoreAPI[Core HTTP API<br/>Gin Router]
            BatchProc[ServiceMap<br/>Batch Processor]
            CoreRepo[ClickHouse<br/>Repository]
        end

        subgraph SigNozPkg["packages/signoz"]
            Frontend[Frontend UI<br/>React 18 + Ant Design]
            QueryService[Query Service<br/>+ S3 Tiering + SSO]
            Crypto[AES-256-GCM<br/>Crypto Module]
            K8sJob[K8s Job Manager]
        end

        Frontend --> QueryService
        Frontend --> CoreAPI
        CoreAPI --> BatchProc
        CoreAPI --> CoreRepo
        QueryService --> Crypto
        QueryService --> K8sJob
    end

    subgraph Storage["Storage Layer (external)"]
        CH[(ClickHouse<br/>dedicated VM)]
        S3[(S3 Tiered<br/>Hot / Warm / Cold)]
    end

    User --> Frontend
    OTel -->|OTLP ingest<br/>via Gateway| CH
    CoreRepo --> CH
    QueryService --> CH
    CH -.TTL MOVE / Lifecycle.-> S3

    classDef core fill:#fff3e0,stroke:#f57c00,color:#000
    classDef signoz fill:#e8f5e9,stroke:#2e7d32,color:#000
    classDef storage fill:#f3e5f5,stroke:#7b1fa2,color:#000
    class CoreAPI,BatchProc,CoreRepo core
    class Frontend,QueryService,Crypto,K8sJob signoz
    class CH,S3 storage

Data flow:

1. Ingest — OTel Collectors (from Agent clusters) ship telemetry through the OTel Gateway into ClickHouse
2. Batch — packages/core runs a periodic ServiceMap batch processor that builds topology data from trace spans
3. Query — packages/signoz Query Service serves the UI (metrics/logs/traces) and manages SSO + S3 tiering config
4. Visualize — Frontend consumes both Core API (ServiceMap) and the standard Query Service (metrics/logs/traces views)

Handler (HTTP endpoints, Gin Router)
    ↓
Service (business logic, topology build)
    ↓
Repository (ClickHouse queries, data access)
    ↓
Infrastructure (DB connection management)

Part of a larger system. Full production deployment (Host + Agent clusters, ClickHouse VM, OTel Gateway) is documented in the umbrella repo: Wondermove-Inc/k-o11y.

This README covers local development and building of the server components only.

Also required: a running ClickHouse instance (see k-o11y-install for VM setup).

cd packages/core

# Required env vars
export CLICKHOUSE_HOST=<YOUR_IP>
export CLICKHOUSE_PORT=9000
export CLICKHOUSE_DATABASE=signoz_traces
export CLICKHOUSE_USER=default
export CLICKHOUSE_PASSWORD=<password>

# Optional (defaults shown)
# export APP_PORT=3001                    # default: 3001
# export APP_ENV=local                    # default: local
# export BATCH_SERVICEMAP_ENABLED=true    # default: true
# export BATCH_SERVICEMAP_INTERVAL=20s    # default: 20s

go run cmd/main.go

All batch settings ship with sensible defaults — no tuning needed to start. To disable the ServiceMap batch, set BATCH_SERVICEMAP_ENABLED=false.

cd packages/signoz

# 1. Create local env file (first time only)
cp .env.example .env.local
# Edit .env.local — set ClickHouse DSN and other real values

# 2. Start dev infrastructure (local ClickHouse + OTel Collector)
make devenv-up

# 3. Run Go backend
make go-run-community

Env precedence (highest first): make CLI args → shell export → .env.local → defaults.

# Example: pass DSN directly via make
make go-run-community SIGNOZ_CLICKHOUSE_DSN=tcp://default:'pass'@host:9000

cd packages/signoz/frontend
CI=1 yarn install
yarn dev

Once the Core server is running, open:

http://localhost:3001/swagger-ui/

K-O11y Server is a monorepo with two packages.

k-o11y-server/
├── packages/
│   ├── core/                        # Go backend (ServiceMap, S3 Tiering API)
│   │   ├── cmd/main.go              # Entrypoint
│   │   ├── internal/
│   │   │   ├── batch/               # ServiceMap batch processor
│   │   │   ├── config/              # Environment-based configuration
│   │   │   ├── domain/servicemap/   # Domain models
│   │   │   ├── handler/             # HTTP handlers (Gin router)
│   │   │   ├── service/             # Business logic
│   │   │   ├── repository/          # ClickHouse data access
│   │   │   ├── infrastructure/      # DB connection management
│   │   │   └── utils/               # Utilities
│   │   ├── pkg/                     # Shared packages (logger, response, errors)
│   │   ├── deployments/Dockerfile   # Multi-stage build
│   │   └── Makefile
│   │
│   └── signoz/                      # Backend UI + Query Service
│       ├── frontend/                # React frontend
│       ├── pkg/                     # Go backend packages
│       │   ├── crypto/              # AES-256-GCM encryption (S3 creds)
│       │   ├── http/middleware/     # SSO + Tenant Auto-Lock
│       │   ├── k8s/                 # K8s Job management
│       │   └── query-service/       # ClickHouse query + S3 tiering
│       ├── cmd/community/           # Community build entrypoint
│       └── Makefile
│
├── Makefile                         # Root build (interactive build-and-push)
├── NOTICE                           # Attribution
└── README.md

Core package

Hub package

Pre-built Docker images and Helm charts are not published yet. You must build images from source and push to your own registry (GHCR, Harbor, Docker Hub, etc.).

# Core API
cd packages/core
docker build -t <your-registry>/observability/core:v1.0.0 -f deployments/Dockerfile .
docker push <your-registry>/observability/core:v1.0.0

# Hub (community build)
cd packages/signoz
make go-build-community
docker build -t <your-registry>/observability/hub:v1.0.0 -f cmd/community/Dockerfile .
docker push <your-registry>/observability/hub:v1.0.0

make build-and-push
# Choose:
#   1. core   → build & push packages/core
#   2. hub    → build & push packages/signoz
# Enter TAG (e.g. 0.1.3)

# Core
cd packages/core
make core-build-and-push TAG=0.1.3
# → <YOUR_REGISTRY>/observability/core:0.1.3

# Trigger GitHub Actions workflow
make trigger-workflow CUSTOM_TAG=v0.1.3

# Hub package
cd packages/signoz
make o11y-build-and-push TAG=0.1.20

Helm charts live in the separate k-o11y-install repo. To package and push:

cd k-o11y-install/charts
helm package k-o11y-host
helm package k-o11y-agent
helm push k-o11y-host-*.tgz oci://<your-registry>/charts
helm push k-o11y-agent-*.tgz oci://<your-registry>/charts

Update values.yaml image registries to match your registry before installing.

Base URL: http://<host>:3001/api/v1

All endpoints use POST to handle large filter payloads and avoid URL-encoding issues.

Server

ClickHouse connection

Batch processing

All batch settings have defaults — the server runs fine with none set.

Logging

Env vars are injected via .env.local, make CLI args, or shell export. See .env.example for the full template.

Configurable variables (Makefile ?=)

Makefile-managed (do not override)

K-O11y Server is one component of a larger observability platform. See the umbrella repo for the full picture.

Contributions are welcome — especially on good first issues.

1. Find an issue labeled good first issue or help wanted
2. Comment on the issue to claim it (avoid duplicate work)
3. Fork, branch, and send a PR — scope narrowly, describe clearly
4. Address review feedback — maintainers will reply within a few days

See CONTRIBUTING.md for more.

This project follows passive maintenance — PRs and issues are reviewed as time allows. We aim to respond within 7 days but cannot guarantee faster turnaround.

MIT License — see LICENSE.

This project is derived from SigNoz (MIT License, Copyright SigNoz Inc.). See NOTICE for full attribution.

• 🐛 Bug reports & feature requests: GitHub Issues
• 💭 Questions & discussions: Open an issue (GitHub Discussions coming soon)
• 🌐 Website: www.skuberplus.com