Architecture Overview¶

SemConv Proxy intercepts OTLP signals on their way from instrumented applications (via OpenTelemetry Collectors) to your observability backend. It forwards every signal unmodified while asynchronously building a live dictionary of discovered semantic conventions.

Pipeline Position¶

graph LR
    App["Application"] --> Coll["OTel Collector"]
    Coll --> Proxy["SemConv Proxy"]
    Proxy --> Backend["Observability Backend"]
    Proxy --> API["REST API"]
    API --> User["Engineer"]

The proxy is a drop-in component. You point your existing OTel Collector exporters at the proxy instead of directly at the backend. No application or Collector configuration changes are needed beyond the endpoint URL.

Core Architecture¶

graph TB
    subgraph "Hot Path (Zero-Loss)"
        Recv["OTLP Receiver<br/>HTTP :4318 / gRPC :4317"]
        Fwd["OTLP Forwarder"]
    end

    subgraph "Analysis Pipeline (Async)"
        RB["Ring Buffer"]
        WP["Worker Pool"]
        Ext["Attribute Extractor"]
    end

    subgraph "Dictionary Layer"
        Dict["Sharded Dictionary<br/>64 Shards"]
        CT["Cardinality Tracker<br/>HLL + CMS + Top-K"]
    end

    subgraph "Persistence"
        Pebble["Pebble<br/>Write-Behind"]
    end

    subgraph "API Layer"
        REST["REST API :8080"]
        Weav["Weaver Exporter"]
        Prom["Prometheus /metrics"]
    end

    Recv --> Fwd
    Recv --> RB
    RB --> WP
    WP --> Ext
    Ext --> Dict
    Ext --> CT
    Dict --> Pebble
    Dict --> REST
    CT --> REST
    Dict --> Weav
    REST --> Weav
    REST --> Prom

Key Design Decisions¶

Performance Targets¶

Technology Stack¶