Skip to content

Personal Knowledge Base

SigNoz — Architecture

SigNoz — Architecture¶

Component breakdown, deployment topologies, and data flow for SigNoz.

System Architecture¶

flowchart TB
    subgraph Sources["Data Sources"]
        APP["Application\n+ OTel SDK"]
        PROM["Prometheus\nTargets"]
        LEGACY["Jaeger /\nZipkin Clients"]
        FB["FluentBit /\nFluentD"]
        RUM["Browser\n(RUM SDK)"]
    end

    subgraph CollectorFleet["OTel Collector Fleet"]
        direction TB
        GW["Gateway Collectors\n(load-balanced)"]
        AGT["Agent Collectors\n(DaemonSet, optional)"]
    end

    subgraph Backend["SigNoz Backend"]
        direction TB
        QS["Query Service\n(Go API)"]
        Rule["Ruler +\nAlertmanager"]
        OpAMP["OpAMP Server\n(dynamic config)"]
        EE["Enterprise Extensions\n(SSO, RBAC, SAML)"]
        FE["React Frontend\n(SPA)"]
    end

    subgraph CHCluster["ClickHouse Cluster"]
        direction TB
        Shard1["Shard 1\n(Replica A + B)"]
        Shard2["Shard 2\n(Replica A + B)"]
        ZK["ZooKeeper /\nClickHouse Keeper"]

        subgraph Tables["Core Tables"]
            T_Traces["signoz_traces\n.signoz_index_v2"]
            T_Logs["signoz_logs\n.logs"]
            T_Metrics["signoz_metrics\n.samples_v4"]
        end
    end

    subgraph Meta["Metadata"]
        PG["PostgreSQL\n(metadata, auth)"]
    end

    Sources --> CollectorFleet
    GW -->|"ClickHouse\nexporter"| CHCluster
    AGT -->|"forward"| GW
    QS -->|"query"| CHCluster
    Rule -->|"eval"| CHCluster
    QS --> FE
    QS --> PG
    OpAMP -.->|"reconfigure"| CollectorFleet

    style Backend fill:#7b1fa2,color:#fff
    style CHCluster fill:#1565c0,color:#fff

Component Responsibility Matrix¶

Component	Language	Role	Scales Via
OTel Collector (Gateway)	Go	Ingestion, processing, routing	Horizontal (replicas behind LB)
OTel Collector (Agent)	Go	Per-node collection, forwarding	DaemonSet (1 per node)
Query Service	Go	API layer, ClickHouse queries	Horizontal (stateless)
Ruler / Alertmanager	Go	Alert evaluation, notifications	Single leader
OpAMP Server	Go	Dynamic collector reconfiguration	Single instance
React Frontend	TypeScript	UI, dashboards, query builder	Static assets (CDN/replicas)
ClickHouse	C++	Columnar storage for all signals	Sharding + replication
ZooKeeper / Keeper	Java/C++	ClickHouse coordination	3-node ensemble
PostgreSQL	C	Metadata, user auth, settings	Standard HA (RDS etc.)

Deployment Topologies¶

Small (< 50 GB/day)¶

flowchart LR
    OTel["OTel Collector\n(single)"]
    QS["Query Service"]
    FE["Frontend"]
    CH["ClickHouse\n(single node)"]
    PG["PostgreSQL"]

    OTel --> CH
    QS --> CH
    QS --> PG
    QS --> FE

Production (50–200 GB/day)¶

flowchart LR
    subgraph Collectors["Collector Fleet"]
        C1["Collector 1"]
        C2["Collector 2"]
        C3["Collector 3"]
    end

    LB["Load Balancer"]
    subgraph QSPool["Query Service Pool"]
        QS1["QS 1"]
        QS2["QS 2"]
    end

    subgraph CHCluster["ClickHouse (2×2)"]
        S1R1["Shard1 Rep1"]
        S1R2["Shard1 Rep2"]
        S2R1["Shard2 Rep1"]
        S2R2["Shard2 Rep2"]
    end

    Collectors --> LB --> CHCluster
    QSPool --> CHCluster

ClickHouse Storage Schema Detail¶

Trace Index Table¶

Column	Type	Purpose
`timestamp`	DateTime64(9)	Nanosecond precision timestamp
`traceID`	FixedString(32)	128-bit trace identifier
`spanID`	String	Span identifier
`parentSpanID`	String	Parent span link
`serviceName`	LowCardinality(String)	Service name
`name`	LowCardinality(String)	Operation name
`kind`	Int8	Span kind (server/client/etc.)
`durationNano`	UInt64	Span duration
`statusCode`	Int16	Status code
`httpMethod`	LowCardinality(String)	HTTP method
`httpRoute`	LowCardinality(String)	HTTP route
`resourceAttributes`	Map(String, String)	Resource attributes

Log Table¶

Column	Type	Purpose
`timestamp`	UInt64	Unix nanoseconds
`body`	String	Log message body
`severityText`	LowCardinality(String)	ERROR, WARN, INFO, etc.
`severityNumber`	UInt8	Numeric severity
`traceID`	String	Correlation to traces
`spanID`	String	Correlation to spans
`resourceAttributes`	Map(String, String)	Resource context
`logAttributes`	Map(String, String)	Log-specific attributes

Sources¶