{"id":34657617,"url":"https://github.com/usetero/edge","last_synced_at":"2026-02-24T05:52:00.958Z","repository":{"id":328062286,"uuid":"1099401526","full_name":"usetero/edge","owner":"usetero","description":"Edge proxy that enforces Tero policies","archived":false,"fork":false,"pushed_at":"2026-01-29T16:09:02.000Z","size":27258,"stargazers_count":9,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-30T04:59:21.918Z","etag":null,"topics":["edge","observability","proxy","telemetry"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usetero.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-19T00:19:43.000Z","updated_at":"2026-01-29T16:08:41.000Z","dependencies_parsed_at":"2025-12-11T14:02:41.140Z","dependency_job_id":null,"html_url":"https://github.com/usetero/edge","commit_stats":null,"previous_names":["usetero/edge"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/usetero/edge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetero%2Fedge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetero%2Fedge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetero%2Fedge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetero%2Fedge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usetero","download_url":"https://codeload.github.com/usetero/edge/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetero%2Fedge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29179574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T22:12:24.066Z","status":"ssl_error","status_checked_at":"2026-02-06T22:12:09.859Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["edge","observability","proxy","telemetry"],"created_at":"2025-12-24T18:34:39.124Z","updated_at":"2026-02-24T05:52:00.950Z","avatar_url":"https://github.com/usetero.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tero Edge\n\nTero Edge is a lightweight, high-performance telemetry proxy that enables\nefficient telemetry processing via a set of policies. The repository is\nstructured as modular packages that can be composed to enable multiple use cases\nand scenarios. The proxy demonstrates how to implement the policy spec described\nin\n[this OTEP](https://github.com/open-telemetry/opentelemetry-specification/pull/4738).\nThis project is not meant to replace the opentelemetry collector but rather work\nin tandem with it, providing a lightweight alternative for solely applying\npolicies. It's expected that a follow up to this project will be a collector\nprocessor Policy implementation.\n\n## Current Configurations\n\n1. **Edge data proxy** - Receives data in a gateway or sidecar configuration,\n   processes the data through its policy engine, and forwards it to the next\n   destination.\n\n2. **OTLP (OpenTelemetry) proxy** - Receives OpenTelemetry logs via the\n   `/v1/logs` endpoint, applies policy-based filtering (DROP/KEEP), and forwards\n   to OTLP-compatible backends.\n\n3. **Datadog proxy** - Receives OpenTelemetry logs via the `/api/v2/logs`\n   endpoint, applies policy-based filtering (DROP/KEEP), and forwards to\n   Datadog.\n\n4. **Prometheus proxy** - Sits as a sidecar next to your application, proxies\n   `/metrics` scrapes with streaming policy-based metric filtering, and forwards\n   filtered metrics to Prometheus.\n\n## Repository Structure\n\n```\nsrc/\n├── main.zig              # Default distribution entry point\n├── datadog_main.zig      # Datadog-focused distribution entry point\n├── otlp_main.zig         # OTLP-focused distribution entry point\n├── prometheus_main.zig   # Prometheus-focused distribution entry point\n├── lambda_main.zig       # AWS Lambda extension entry point\n├── root.zig              # Library root (public API exports)\n│\n├── modules/              # Protocol-specific processing modules\n├── proxy/                # HTTP proxy infrastructure\n├── prometheus/           # Prometheus metric parsing and filtering\n├── config/               # Configuration parsing (non-policy)\n├── lambda/               # AWS Lambda extension support\n└── zonfig/               # Comptime configuration with env overrides\n```\n\n## External Dependencies\n\nEdge consumes the following shared modules from\n[policy-zig](https://github.com/usetero/policy-zig):\n\n- **`policy_zig`** - Policy engine, registry, matchers, transforms, and\n  Hyperscan/Vectorscan bindings\n- **`proto`** - Protobuf types (policy, common, OTLP\n  logs/metrics/trace/resource)\n- **`o11y`** - Observability (EventBus, structured logging, spans)\n\n## Package Overview\n\nEach package is designed to be as independent as possible, with clear interfaces\nfor integration.\n\n### `modules/` - Protocol Modules\n\nProtocol-specific request processing modules that plug into the proxy\ninfrastructure.\n\n**Key exports:**\n\n- `ProxyModule` - Vtable interface for request processing\n- `ModuleRegistration` - Module configuration (routes, upstream, etc.)\n- `DatadogModule` - Datadog log ingestion with policy-based filtering\n- `OtlpModule` - OpenTelemetry log ingestion with policy-based filtering\n- `PrometheusModule` - Prometheus metrics scraping with streaming policy-based\n  filtering\n- `PassthroughModule` - No-op passthrough for unhandled routes\n\n**Dependencies:** `policy_zig`, `proto`, `o11y`\n\n#### OtlpModule\n\nThe OTLP module handles OpenTelemetry log ingestion with policy-based filtering.\nIt processes the standard OTLP JSON format (`ExportLogsServiceRequest`).\n\n**Supported filter match cases:**\n\n- `log_body` - Match against log message body\n- `log_severity_text` - Match against severity text (INFO, DEBUG, ERROR, etc.)\n- `log_severity_number` - Match against severity number (1-24)\n- `log_attribute` - Match against log record attributes\n- `resource_attribute` - Match against resource attributes (e.g.,\n  `service.name`)\n- `scope_name` - Match against instrumentation scope name\n- `scope_version` - Match against instrumentation scope version\n- `scope_attribute` - Match against scope attributes\n\n**Routes:**\n\n- `POST /v1/logs` - OTLP log ingestion endpoint\n\n---\n\n### `proxy/` - HTTP Proxy Infrastructure\n\nCore HTTP proxy server and routing infrastructure.\n\n**Key exports:**\n\n- `ProxyServer` - HTTP server with module-based request routing\n- `Router` - Route matching (path patterns, method bitmasks)\n- `UpstreamClient` - HTTP client for forwarding requests\n- `compress` - gzip compression/decompression utilities\n\n**Dependencies:** `o11y`, links to httpz\n\n---\n\n### `prometheus/` - Prometheus Metrics\n\nStreaming Prometheus exposition format parsing and policy-based filtering.\n\n**Key exports:**\n\n- `PolicyStreamingFilter` - Streaming filter that applies policies to metrics\n- `FilteringWriter` - Writer that filters metrics line-by-line\n- `FieldAccessor` - Maps policy field references to Prometheus metric fields\n- `LineParser` - Prometheus exposition format parser\n\n**Dependencies:** `policy_zig`, `proto`, `o11y`\n\n---\n\n### `config/` - Configuration Parsing\n\nApplication configuration loading and parsing (non-policy configuration).\n\n**Key exports:**\n\n- `ProxyConfig` - Main proxy configuration struct\n- `ProviderConfig` - Policy provider configuration (re-exported from policy-zig)\n- `ServiceMetadata` - Service metadata (re-exported from policy-zig)\n\n**Dependencies:** `policy_zig`\n\n---\n\n## Distributions\n\nDistributions are pre-configured entry points that compose packages for specific\nuse cases.\n\n### Full (`main.zig`)\n\nFull distribution supporting both Datadog and OTLP ingestion with:\n\n- Handles Datadog `/api/v2/logs` and `/api/v2/series` endpoints\n- Handles OTLP `/v1/logs` and `/v1/metrics` endpoints\n- Policy-based filtering (DROP/KEEP) for logs and metrics\n- Separate upstream URLs for logs and metrics (optional)\n- Async policy loading (server starts immediately while policies load in\n  background)\n- Fail-open behavior (errors pass data through unchanged)\n- Lock-free policy updates via atomic snapshots\n- Graceful shutdown with signal handling\n- SIGSEGV handler for crash diagnostics with stack traces\n\nBuild: `zig build` (default) Run: `zig build run` or\n`./zig-out/bin/edge [config-file]`\n\n### Datadog (`datadog_main.zig`)\n\nFocused distribution for Datadog log and metrics ingestion with:\n\n- Handles `/api/v2/logs` and `/api/v2/series` endpoints\n- Policy-based filtering (DROP/KEEP)\n- Separate upstream URLs for logs and metrics (optional)\n- Async policy loading (non-blocking startup)\n- Fail-open behavior (errors pass data through)\n- Lock-free policy updates via atomic snapshots\n- Graceful shutdown with signal handling\n- SIGSEGV handler for crash diagnostics\n\nBuild: `zig build datadog` Run: `zig build run-datadog` or\n`./zig-out/bin/edge-datadog [config-file]`\n\n### OTLP (`otlp_main.zig`)\n\nFocused distribution for OpenTelemetry Protocol (OTLP) log ingestion with:\n\n- Handles `/v1/logs` endpoint (OTLP JSON format)\n- Policy-based log filtering (DROP/KEEP) on log body, severity, attributes\n- Support for resource attributes, scope attributes, and log attributes\n- Async policy loading (non-blocking startup)\n- Fail-open behavior (errors pass logs through unchanged)\n- Lock-free policy updates via atomic snapshots\n- Graceful shutdown with signal handling\n- SIGSEGV handler for crash diagnostics\n- Compatible with any OTLP-receiving backend (Datadog, Jaeger, etc.)\n\nBuild: `zig build otlp` Run: `zig build run-otlp` or\n`./zig-out/bin/edge-otlp [config-file]`\n\n### Prometheus (`prometheus_main.zig`)\n\nFocused distribution for Prometheus metrics scraping with streaming filtering:\n\n- Proxies `/metrics` endpoint with policy-based metric filtering\n- Streaming response processing (bounded memory regardless of response size)\n- Configurable per-scrape limits (`max_input_bytes_per_scrape`,\n  `max_output_bytes_per_scrape`)\n- Filters metrics by name, labels, type, and other fields\n- Zero-copy forwarding for metrics that pass policy checks\n- Fail-open behavior (errors pass metrics through unchanged)\n- Designed for sidecar deployment next to your application\n- Lock-free policy updates via atomic snapshots\n- Graceful shutdown with signal handling\n\nBuild: `zig build prometheus` Run: `zig build run-prometheus` or\n`./zig-out/bin/edge-prometheus [config-file]`\n\n### Lambda (`lambda_main.zig`)\n\nAWS Lambda extension distribution for Datadog telemetry processing.\n\nBuild: `zig build lambda` Run: Deployed as a Lambda layer\n\n## Building\n\n```bash\n# Build all targets\nzig build\n\n# Run tests\nzig build test\n\n# Build specific distribution\nzig build edge        # Full distribution (Datadog + OTLP + Prometheus)\nzig build datadog     # Datadog-only distribution\nzig build otlp        # OTLP-only distribution\nzig build prometheus  # Prometheus-only distribution\nzig build lambda      # Lambda extension distribution\n\n# Run specific distribution\nzig build run-edge\nzig build run-datadog\nzig build run-otlp\nzig build run-prometheus\n```\n\n## Installation\n\n### Pre-built Binaries\n\nDownload the latest release for your platform from the\n[Releases](../../releases) page:\n\n| Platform                    | Binary              |\n| --------------------------- | ------------------- |\n| Linux x86_64                | `edge-linux-amd64`  |\n| Linux ARM64                 | `edge-linux-arm64`  |\n| macOS ARM64 (Apple Silicon) | `edge-darwin-arm64` |\n\nFor Datadog-only or OTLP-only distributions, use `edge-datadog-*` or\n`edge-otlp-*` binaries.\n\n```bash\n# Download and run (example for Linux x86_64)\ncurl -LO https://github.com/\u003corg\u003e/edge/releases/latest/download/edge-linux-amd64\nchmod +x edge-linux-amd64\n./edge-linux-amd64 config.json\n```\n\n### Docker\n\nMulti-stage Dockerfile for building minimal container images.\n\n```bash\n# Build the full distribution\ndocker build --build-arg DISTRIBUTION=edge -t edge .\n\n# Build Datadog-only distribution\ndocker build --build-arg DISTRIBUTION=datadog -t edge-datadog .\n\n# Build OTLP-only distribution\ndocker build --build-arg DISTRIBUTION=otlp -t edge-otlp .\n\n# Run with a config file\ndocker run -v $(pwd)/config.json:/app/config.json -p 8080:8080 edge\n```\n\nPre-built images are available from GitHub Container Registry:\n\n```bash\n# Pull the full distribution\ndocker pull ghcr.io/\u003corg\u003e/edge:latest\n\n# Pull Datadog-only distribution\ndocker pull ghcr.io/\u003corg\u003e/edge-datadog:latest\n\n# Pull OTLP-only distribution\ndocker pull ghcr.io/\u003corg\u003e/edge-otlp:latest\n```\n\nAvailable distributions: `edge`, `datadog`, `otlp`\n\n## Configuration\n\nSee `config.json` for the Datadog distribution or `config-otlp.json` for the\nOTLP distribution.\n\n### Key settings:\n\n- `listen_address` / `listen_port` - Server bind address\n- `upstream_url` - Default upstream destination (used when specific URLs not\n  set)\n- `logs_url` - (Optional) Upstream URL for log endpoints (falls back to\n  `upstream_url`)\n- `metrics_url` - (Optional) Upstream URL for metrics endpoints (falls back to\n  `upstream_url`)\n- `workspace_id` - Workspace identifier for policy sync\n- `log_level` - Logging level (trace, debug, info, warn, err)\n- `policy_providers` - List of policy sources (file/http)\n- `max_body_size` - Request/response body limits\n\n### Example OTLP Configuration (`config-otlp.json`):\n\n```json\n{\n  \"listen_address\": \"127.0.0.1\",\n  \"listen_port\": 8080,\n  \"upstream_url\": \"https://otlp.us5.datadoghq.com\",\n  \"workspace_id\": \"your-workspace-id\",\n  \"log_level\": \"info\",\n  \"max_body_size\": 1048576,\n  \"policy_providers\": [\n    {\n      \"id\": \"file\",\n      \"type\": \"file\",\n      \"path\": \"policies.json\"\n    },\n    {\n      \"id\": \"http\",\n      \"type\": \"http\",\n      \"url\": \"http://localhost:9090/v1/policy/sync\"\n    }\n  ]\n}\n```\n\n### Environment Variables:\n\n- `TERO_LOG_LEVEL` - Override log level (trace, debug, info, warn, err)\n\n## Design Principles\n\n1. **Data-Oriented Design** - Optimize for cache coherency and memory access\n   patterns\n2. **Lock-Free Reads** - Policy evaluation uses atomic snapshot pointers for\n   zero-contention reads\n3. **Fail-Open** - Errors in policy evaluation result in data passthrough, not\n   drops\n4. **Modular Composition** - Packages can be used independently or composed\n   together\n5. **Explicit Dependencies** - Each package declares its dependencies via\n   imports\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusetero%2Fedge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusetero%2Fedge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusetero%2Fedge/lists"}