> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usetero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How Edge is built and why it's fast

Edge is a lightweight Zig proxy that applies policies to telemetry at high
throughput and low latency.

## Component Overview

### Internal Architecture

```mermaid theme={null}
graph TB
    subgraph Clients
        C[HTTP Clients]
    end

    subgraph Server[HTTP Server]
        TP[Thread Pool]
        SC[ServerContext]
    end

    subgraph Routing[Request Routing]
        R[Router]
    end

    subgraph Modules[Module Pipeline]
        direction LR
        H[HealthModule]
        DD[DatadogModule]
        OT[OtlpModule]
        PT[PassthroughModule]
    end

    subgraph Filtering[Policy Engine]
        REG[PolicyRegistry]
        PE[PolicyEngine]
    end

    subgraph Providers[Policy Providers]
        PL[PolicyLoader]
        FP[FileProvider]
        HP[HttpProvider]
    end

    subgraph Upstream
        UCM[UpstreamClientManager]
        TLS[TLS Client]
    end

    C -->|Request| TP
    TP --> SC
    SC --> R
    R --> H
    R --> DD
    R --> OT
    R --> PT

    DD --> PE
    OT --> PE
    PE -->|Filtered| UCM

    PT --> UCM
    UCM --> TLS

    PL -.->|async| FP
    PL -.->|async| HP
    FP -.->|update| REG
    HP -.->|update| REG
    REG -.->|snapshot| PE

    style C fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style TP fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style SC fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style R fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style H fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style DD fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style OT fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style PT fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style REG fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style PE fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style PL fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style FP fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style HP fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style UCM fill:#0e2b22,stroke:#0e2b22,color:#fafafa
    style TLS fill:#0e2b22,stroke:#0e2b22,color:#fafafa
```

### Protocol Modules

Each distribution includes modules for specific protocols:

| Module          | Endpoints        | Description                  |
| --------------- | ---------------- | ---------------------------- |
| Datadog Logs    | `/api/v2/logs`   | Datadog log ingestion API    |
| Datadog Metrics | `/api/v1/series` | Datadog metrics API          |
| OTLP Logs       | `/v1/logs`       | OpenTelemetry log export     |
| OTLP Metrics    | `/v1/metrics`    | OpenTelemetry metrics export |

Modules are stateless. They parse incoming requests, evaluate policies, and
forward results. All state lives in the policy registry.

### Policy Registry

The registry holds all loaded policies and provides lock-free read access during
request processing.

Key properties:

* **Atomic snapshots**: Writers create new snapshots; readers use existing ones
* **Lock-free reads**: No contention during policy evaluation
* **Hot reload**: New policies take effect without restart

Policy updates do not block request processing.

### Policy Engine

The engine evaluates policies against telemetry using Vectorscan (a Hyperscan
fork) for regex matching.

Evaluation flow:

1. **Index lookup**: Find policies that might match based on field keys
2. **Regex scan**: Evaluate regex patterns against field values
3. **Action merge**: Combine keep/transform actions from matching policies
4. **Apply**: Execute the merged actions

Vectorscan compiles regex patterns into finite automata, enabling simultaneous
evaluation of thousands of patterns in a single pass.

### Policy Providers

Providers load policies from external sources:

| Provider | Source           | Reload Mechanism                   |
| -------- | ---------------- | ---------------------------------- |
| File     | Local filesystem | inotify/kqueue file watching       |
| HTTP     | Remote endpoint  | Polling with configurable interval |

Multiple sources can be configured. Policies from all sources merge together.
The policy ID acts as a unique key. If two providers emit a policy with the same
ID, the one from the higher-priority source (HTTP > file) wins. Same-priority
sources will have the later update win. This structure allows you to create a
set of default policies that can be overridden remotely.

## Design Principles

### Data-Oriented Design

Edge optimizes for memory access patterns and cache coherency. It lays out data
structures for sequential access to minimize cache misses during
high-throughput processing.

### Lock-Free Reads

Policy evaluation reads policies on each request, while updates stay rare. Edge uses atomic pointers to policy snapshots,
eliminating read-side synchronization.

```mermaid theme={null}
sequenceDiagram
    participant R1 as Request Thread 1
    participant R2 as Request Thread 2
    participant Reg as Policy Registry
    participant U as Update Thread

    Note over Reg: Snapshot v1 active

    R1->>Reg: read snapshot
    Reg-->>R1: Snapshot v1
    R2->>Reg: read snapshot
    Reg-->>R2: Snapshot v1

    Note over U,Reg: Policy update arrives
    U->>Reg: create Snapshot v2
    U->>Reg: atomic swap pointer
    Note over Reg: Snapshot v2 now active

    R1->>Reg: read snapshot
    Reg-->>R1: Snapshot v2
    R2->>Reg: read snapshot
    Reg-->>R2: Snapshot v2
```

### Fail-Open

Edge prioritizes availability. If policy evaluation fails, Edge forwards the
telemetry unchanged. A filter may not apply, and no data is dropped.

### Stateless Modules

Protocol modules are stateless. Each module:

1. Parses the request
2. Reads policies from the registry
3. Applies policies to the data
4. Forwards to upstream

Engineers can inspect each module in isolation, and Edge can run modules in parallel.

## Performance Characteristics

| Metric              | Typical Value     |
| ------------------- | ----------------- |
| Latency overhead    | \< 5ms p99        |
| Requests per second | 90k+              |
| Policy evaluation   | O(1) average case |
| Memory per policy   | \~1KB             |
| Max policies tested | 8,000+            |

Performance depends on:

* Number of regex patterns (more patterns = more evaluation time)
* Request body size (larger bodies take longer to parse)

## Deployment Patterns

### Gateway

Deploy Edge as a shared gateway for multiple services:

```mermaid theme={null}
flowchart LR
    subgraph Applications
        App1[App 1]
        App2[App 2]
        App3[App 3]
    end

    subgraph Pipeline[Telemetry Pipeline]
        Collector[OTel Collector]
    end

    subgraph Gateway[Egress Gateway]
        Edge[Tero Edge]
    end

    subgraph Vendors[External Vendors]
        DD[Datadog]
        NR[New Relic]
        Grafana[Grafana Cloud]
    end

    App1 --> Collector
    App2 --> Collector
    App3 --> Collector
    Collector -->|All Data| Edge
    Edge -->|Filtered| DD
    Edge -->|Filtered| NR
    Edge -->|Filtered| Grafana

    style Edge fill:#10b981,stroke:#262626,color:#fff
    style Collector fill:#f59e0b,stroke:#262626,color:#000
    style App1 fill:#262626,stroke:#262626,color:#fafafa
    style App2 fill:#262626,stroke:#262626,color:#fafafa
    style App3 fill:#262626,stroke:#262626,color:#fafafa
    style DD fill:#632ca6,stroke:#262626,color:#fff
    style NR fill:#0ea5e9,stroke:#262626,color:#fff
    style Grafana fill:#f97316,stroke:#262626,color:#fff
```

**Use Case**: Tero Edge sits at the egress point after your telemetry pipeline.
It acts as a final gateway before data leaves your network and applies
cost-focused policies that reduce egress to SaaS vendors. Drop redundant health
checks and sample high-cardinality metrics before your provider bills for them.

Best for:

* Centralized policy management
* Environments with many services
* When you want a single point of control

### Sidecar

Deploy Edge alongside each service:

```mermaid theme={null}
flowchart LR
    subgraph Host[Pod or Host]
        App[Application]
        Edge[Tero Edge]
    end

    subgraph Pipeline[Telemetry Pipeline]
        Collector[OTel Collector]
    end

    subgraph Backend
        DD[Datadog]
        Splunk[Splunk]
        S3[S3]
    end

    App -->|Logs/Metrics| Edge
    Edge -->|Filtered| Collector
    Collector --> DD
    Collector --> Splunk
    Collector --> S3

    style Edge fill:#10b981,stroke:#262626,color:#fff
    style App fill:#262626,stroke:#262626,color:#fafafa
    style Collector fill:#f59e0b,stroke:#262626,color:#000
    style DD fill:#632ca6,stroke:#262626,color:#fff
    style Splunk fill:#059669,stroke:#262626,color:#fff
    style S3 fill:#0ea5e9,stroke:#262626,color:#fff
```

**Use Case**: Tero Edge runs as a lightweight sidecar next to each application.
It applies policies at the source by dropping noisy debug logs, redacting PII, or
sampling high-volume metrics before data reaches the telemetry pipeline.
This reduces load on collectors and network bandwidth within your
infrastructure.

Best for:

* Service-specific policies
* Isolation between services
* Kubernetes environments with sidecar injection

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/edge/quickstart">
    Get Edge running in 5 minutes
  </Card>

  <Card title="Reference" icon="gear" href="/edge/edge-reference/config">
    Full configuration reference
  </Card>
</CardGroup>