Before diving into configuration, it helps to understand how Edge thinks about
telemetry processing.
Policies
A policy is an atomic rule that matches specific telemetry and applies an
action. Each policy does one thing: identify telemetry that meets certain
conditions, then decide what happens to it. You can think of a policy as a way
to select a group of telemetry and apply an action to it. The policy syntax is
based on the
OpenTelemetry Semantic Convention
and is being
evaluated for donation
to the OpenTelemetry project. For now, you can read
Tero’s Policy Specification to learn more.
The policy specification is still in development and subject to change.
id: drop-debug-logs
name: Drop debug and trace logs
log:
match:
- log_field: severity_text
regex: "^(DEBUG|TRACE)$"
keep: none
Policy Properties
Every policy has these characteristics:
- Atomic: One intent per policy. Match one pattern, apply a set of actions.
- Self-contained: No dependencies between policies. Each stands alone.
- Fail-open: If evaluation fails, telemetry passes through.
- Idempotent: Safe to apply multiple times with identical results.
Why Atomic Policies?
Traditional pipelines are sequential. Telemetry flows through a chain of
processors, each modifying the data. This creates problems:
- Order matters: Changing one processor affects downstream processors
- Hidden dependencies: Processors rely on fields set by earlier processors
- Debugging nightmare: Tracing why telemetry changed requires understanding
the entire chain
Edge policies execute in parallel. Each policy evaluates independently against
the original telemetry. No policy depends on another policy’s output. This makes
policies:
- Easy to add, remove, or modify without side effects
- Simple to understand in isolation
- Safe to generate programmatically
Matchers
Matchers identify which telemetry a policy applies to. A policy can have
multiple matchers—all must match for the policy to apply (AND logic). When
creating a policy, it’s best to ensure the matchers are mutually exclusive to
avoid unintended matches.
match:
- resource_attribute: service.name
exact: checkout-api
- log_field: severity_text
exact: DEBUG
Match Types
| Type | Description | Example |
|---|
exact | Exact string equality | exact: "error" |
regex | RE2 regular expression | regex: "^payment-" |
exists | Field presence check | exists: true |
Negation
Add negate: true to invert any match:
match:
- log_field: severity_text
exact: DEBUG
negate: true # Matches everything EXCEPT DEBUG
Actions
When a policy matches, it contributes to two stages: keep and transform.
Keep Stage
The keep action determines whether telemetry survives processing:
| Value | Effect |
|---|
keep: all | Keep all matching telemetry (default) |
keep: none | Drop all matching telemetry |
keep: 50% | Keep 50% (percentage sampling) |
keep: 100/s | Keep max 100 per second (rate limiting) |
none (drop) beats everything- Lower percentages beat higher percentages
- Rate limits are evaluated independently
Transforms modify telemetry that survives the keep stage:
| Operation | Effect |
|---|
remove | Delete fields |
redact | Mask field values |
rename | Change field names |
add | Insert new fields |
Execution Model
Edge processes telemetry in two fixed stages:
Telemetry → Match (parallel) → Keep → Transform → Output
├─ Policy 1
├─ Policy 2
└─ Policy N
- Match: All policies evaluate in parallel against the incoming telemetry
- Keep: Matching policies contribute their keep values; most restrictive
wins
- Transform: Surviving telemetry has all matching transforms applied
This parallel model scales to thousands of policies without performance
degradation. There’s no sequential bottleneck.
Telemetry Types
Edge currently supports two telemetry types:
| Type | Description | Policy Actions |
|---|
| Logs | Log records with body, severity, attributes | Filter, sample, transform |
| Metrics | Numeric measurements with dimensions | Filter only |
| Traces | Distributed traces with spans | Filter only (coming soon) |
Policy Sources
Edge loads policies from its policy providers. Currently two policy providers
are supported:
- File: Local JSON files with file watching for hot reload
- HTTP/gRPC: Remote endpoints with polling for updates
(view the gRPC API)
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.
Next Steps
