K-O11y OTel Gateway

OpenTelemetry Collector distribution with JWT-based license validation for enterprise.

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

Based on OpenTelemetry Collector v0.109.0.

• 🛂 License Guard Extension — RS256 JWT-based license validation (public key only — no private key required)
• 🚪 License Gate Processor — Drops telemetry (traces, logs, metrics) when the license has expired beyond the grace period
• ⏳ Grace Period — Configurable window (default 7 days) to warn operators without disrupting data flow immediately after expiration
• 🔁 Periodic Re-validation — License status re-checked on a configurable interval (default 1 hour)
• 📊 Prometheus Metrics — 4 built-in metrics for license health and drop accounting
• 🔧 Pass-through Mode — Works transparently without a license for dev/test environments
• 🏢 Multi-tenant Aware — License claims (tenant_id, contract_id) surfaced as metric attributes
• 📦 Upstream compatible — Full OTel Collector features (ClickHouse exporter, span metrics processor, etc.) retained

The gateway sits at the edge of the Host cluster, in front of ClickHouse. Every OTLP payload from Agent clusters passes through a two-stage license check: the License Guard Extension holds and refreshes the current license state, and the License Gate Processor consults that state on each batch, either forwarding to ClickHouse or dropping with a counter increment.

flowchart LR
    subgraph Agents["Agent Clusters"]
        A1[OTel Collector<br/>DaemonSet]
        A2[OTel Collector<br/>Deployment]
    end

    subgraph Gateway["K-O11y OTel Gateway"]
        direction TB
        R[OTLP Receiver<br/>:4317]
        LG["🛂 License Guard Extension<br/>(RS256 JWT verify,<br/>check_interval: 1h)"]
        GP["🚪 License Gate Processor<br/>(consult guard state)"]
        B[Batch Processor]
        E[ClickHouse Exporter]

        R --> GP
        GP --> B
        B --> E
        LG -.state.-> GP
    end

    subgraph Decision["Gate Decision"]
        direction TB
        V{License<br/>valid?}
        G{Within<br/>grace period?}
        PASS[✅ Forward to ClickHouse]
        WARN[⚠️ Forward + log warning]
        DROP["❌ Drop<br/>otel_data_dropped_total++"]

        V -->|yes| PASS
        V -->|no| G
        G -->|yes| WARN
        G -->|no| DROP
    end

    A1 -->|OTLP gRPC| R
    A2 -->|OTLP gRPC| R
    GP -.each batch.-> V

    E --> CH[(ClickHouse)]

    classDef agent fill:#e1f5ff,stroke:#0288d1,color:#000
    classDef gw fill:#fff3e0,stroke:#f57c00,color:#000
    classDef decide fill:#f3e5f5,stroke:#7b1fa2,color:#000
    class A1,A2 agent
    class R,LG,GP,B,E gw
    class V,G,PASS,WARN,DROP decide

Validation flow:

1. On startup, License Guard loads the JWT from env (LICENSE_KEY) and verifies the RS256 signature with the configured public key
2. Guard extracts claims (tenant_id, contract_id, exp) and records them on Prometheus metrics
3. Every check_interval (default 1h), Guard re-validates and updates its in-memory status
4. For every telemetry batch, License Gate Processor consults Guard's status:
   • Valid → forward to the next processor
   • Expired but within grace period → forward + log a warning
   • Expired beyond grace period → drop and increment otel_data_dropped_total

A JWT-based license validation extension that exposes license status via Prometheus metrics and OpenTelemetry internal metrics.

• RS256 public-key verification — only the public key is deployed to the gateway; private keys stay with the license issuer
• Expiration tracking with configurable grace period
• Periodic re-validation (default: 1h)
• Pass-through mode when no license is configured (dev/test)
• fail_mode — closed to block on verification failure, open to allow

A processor that drops telemetry data when the License Guard reports an expired license beyond the grace period.

• Works with traces, logs, and metrics pipelines
• Integrates with License Guard Extension by name (extension_name)
• In grace period: warns but lets data through
• After grace period: drops data and increments otel_data_dropped_total

extensions:
  license_guard:
    # JWT license key (environment variable reference)
    license_key_env: "LICENSE_KEY"

    # RSA public key for JWT verification (PEM format)
    public_key_pem: |
      -----BEGIN PUBLIC KEY-----
      ...
      -----END PUBLIC KEY-----

    # Re-validation interval (default: 1h)
    check_interval: 1h

    # Grace period after expiration (default: 7 days)
    grace_period_days: 7

    # Behavior on validation failure: "closed" (block) or "open" (allow)
    fail_mode: closed

processors:
  license_gate:
    # Name of the License Guard extension to check (default: "license_guard")
    extension_name: license_guard

extensions:
  license_guard:
    license_key_env: "LICENSE_KEY"
    public_key_pem: |
      -----BEGIN PUBLIC KEY-----
      ...
      -----END PUBLIC KEY-----

service:
  extensions: [license_guard]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [license_gate, batch]
      exporters: [clickhouse]
    logs:
      receivers: [otlp]
      processors: [license_gate, batch]
      exporters: [clickhouse]
    metrics:
      receivers: [otlp]
      processors: [license_gate, batch]
      exporters: [clickhouse]

• Go 1.22+
• Docker

go build -o signoz-otel-collector ./cmd/signozotelcollector

docker build -t ghcr.io/wondermove-inc/signoz-otel-collector:latest \
  -f cmd/signozotelcollector/Dockerfile .

go test ./extension/licenseguardextension/...
go test ./processor/licensegateprocessor/...

Example alert rules:

# License expiring within 14 days
- alert: LicenseExpiringSoon
  expr: otel_license_expires_in_days < 14
  for: 10m

# Data being dropped due to expired license
- alert: DataDroppedLicenseExpired
  expr: rate(otel_data_dropped_total[5m]) > 0
  for: 1m

K-O11y OTel Gateway is part of the broader K-O11y project.

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 details.

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.

Apache License 2.0 — see LICENSE.

Forked from SigNoz OTel Collector (Apache 2.0), based on the OpenTelemetry Collector (Apache 2.0). See NOTICE for attribution details.

• Umbrella: k-o11y — meta-repo with the full stack overview
• Server: k-o11y-server — Observability backend + Core API
• Install: k-o11y-install — Helm charts + Go CLI installers
• OTel Collector: k-o11y-otel-collector — Agent-side collector with CRD Processor

• 🐛 Bug reports & feature requests: GitHub Issues
• 💭 Questions & discussions: Open an issue on the umbrella repo
• 🌐 Website: www.skuberplus.com