Config

Config lists every Edge configuration option.

Configuration File

Edge uses a JSON configuration file. Pass the path as the first argument:

./edge config.json

Full Example

config.json

{
  "listen_address": "0.0.0.0",
  "listen_port": 8080,
  "upstream_url": "https://agent-http-intake.logs.datadoghq.com",
  "logs_url": "https://agent-http-intake.logs.datadoghq.com",
  "metrics_url": "https://api.datadoghq.com",
  "log_level": "info",
  "max_body_size": 1048576,
  "service": {
    "name": "edge",
    "namespace": "production",
    "resource_attributes": [
      { "key": "deployment.environment", "value": "production" }
    ],
    "labels": [{ "key": "team", "value": "platform" }]
  },
  "policy_providers": [
    {
      "id": "local",
      "type": "file",
      "path": "/etc/edge/policies.json"
    },
    {
      "id": "remote",
      "type": "http",
      "url": "${TERO_CONTROL_PLANE_URL}/v1/policy/sync",
      "poll_interval": 30,
      "headers": [
        {
          "name": "Authorization",
          "value": "Bearer ${TERO_API_TOKEN}"
        }
      ]
    }
  ]
}

Any string value can reference an environment variable with ${VAR} (for example ${TERO_API_TOKEN}). See Environment Variables.

Configuration Reference

Edge supports up to 8,000 policies. Open an issue on GitHub if you need more.

Server Settings

Field	Type	Default	Description
`listen_address`	string	`"127.0.0.1"`	IP address to bind to
`listen_port`	number	`8080`	Port to listen on
`max_body_size`	number	`1048576`	Maximum request body size in bytes (1MB default)
`log_level`	string	`"info"`	Logging level: `debug`, `info`, `warn`, `err`

Upstream Settings

Field	Type	Required	Description
`upstream_url`	string	Yes	Default upstream destination (fallback when specific URLs not set)
`logs_url`	string	No	Upstream destination for log endpoints (falls back to `upstream_url`)
`metrics_url`	string	No	Upstream destination for metrics endpoints (falls back to `upstream_url`)

Service Settings

The service object identifies this Edge instance to the control plane and attaches metadata to policy sync requests. Always set name, namespace, and version — the control plane uses them to scope and match policies to this service. resource_attributes and labels are optional but recommended.

{
  "service": {
    "name": "edge",
    "namespace": "production",
    "resource_attributes": [
      { "key": "deployment.environment", "value": "production" }
    ],
    "labels": [{ "key": "team", "value": "platform" }]
  }
}

Field	Type	Required	Description
`name`	string	Recommended	Service name (default `"tero-edge"`)
`namespace`	string	Recommended	Service namespace (default `"tero"`)
`version`	string	Recommended	Service version (default `"latest"`)
`resource_attributes`	array	No	OTel resource attributes (`{key, value}`) sent on policy sync
`labels`	array	No	Free-form labels (`{key, value}`) sent on policy sync

instance_id is generated at startup and is not configurable.

Policy Providers

The policy_providers array configures where Edge loads policies from.

File Provider

Loads policies from a local file and watches for changes.

{
  "id": "local",
  "type": "file",
  "path": "/etc/edge/policies.json"
}

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for this provider
`type`	string	Yes	Must be `"file"`
`path`	string	Yes	Path to the policy file

Edge watches the file with inotify (Linux) or kqueue (macOS) and applies changes on save.

HTTP Provider

Loads policies from an HTTP endpoint with periodic polling.

{
  "id": "remote",
  "type": "http",
  "url": "https://api.example.com/policies",
  "poll_interval": 30,
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer token"
    }
  ]
}

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for this provider
`type`	string	Yes	Must be `"http"`
`url`	string	Yes	URL to fetch policies from
`poll_interval`	number	No	Seconds between policy fetches
`headers`	array	No	HTTP headers to include in requests

Prometheus Settings

The optional prometheus object bounds memory use when filtering Prometheus scrapes (relevant to distributions that handle metrics).

{
  "prometheus": {
    "max_input_bytes_per_scrape": 10485760,
    "max_output_bytes_per_scrape": 10485760
  }
}

Field	Type	Default	Description
`max_input_bytes_per_scrape`	number	`10485760`	Max bytes read from upstream per scrape (10MB)
`max_output_bytes_per_scrape`	number	`10485760`	Max bytes forwarded to the client per scrape (10MB)

Policy File Format

Define policies in a JSON file:

policies.json

{
  "policies": [
    {
      "id": "policy-1",
      "name": "Human-readable name",
      "description": "What this policy does",
      "enabled": true,
      "log": {
        "match": [...],
        "keep": "...",
        "transform": {...}
      }
    },
    {
      "id": "policy-2",
      "name": "Another policy",
      "metric": {
        "match": [...],
        "keep": true
      }
    }
  ]
}

See the Policies section for detailed policy configuration.

Environment Variables

Edge reads environment variables two ways.

Value Substitution

Any string value in the config file can reference an environment variable with ${VAR}. The variable is resolved when the config loads:

{
  "upstream_url": "https://agent-http-intake.logs.${TERO_DD_REGION}.datadoghq.com",
  "policy_providers": [
    {
      "id": "remote",
      "type": "http",
      "url": "${TERO_CONTROL_PLANE_URL}/v1/policy/sync",
      "headers": [
        { "name": "Authorization", "value": "Bearer ${TERO_API_TOKEN}" }
      ]
    }
  ]
}

Unset variables resolve to an empty string.
Use $${VAR} to emit a literal ${VAR} without substitution.

Field Overrides

A TERO_-prefixed environment variable overrides the matching config field. The name is the field path in SCREAMING_SNAKE_CASE, with nested fields joined by _, so service.namespace becomes TERO_SERVICE_NAMESPACE. Overrides are applied after the file is parsed, so they always win over it.

TERO_LOG_LEVEL=debug TERO_LISTEN_PORT=9090 ./edge config.json

Every scalar field is overridable. The full set:

Variable	Overrides	Type	Default
`TERO_LISTEN_ADDRESS`	`listen_address`	IPv4 address	`127.0.0.1`
`TERO_LISTEN_PORT`	`listen_port`	port	`8080`
`TERO_UPSTREAM_URL`	`upstream_url`	string	`http://127.0.0.1:80`
`TERO_LOGS_URL`	`logs_url`	string, optional	unset
`TERO_METRICS_URL`	`metrics_url`	string, optional	unset
`TERO_SERVICE_NAME`	`service.name`	string	`tero-edge`
`TERO_SERVICE_NAMESPACE`	`service.namespace`	string	`tero`
`TERO_SERVICE_VERSION`	`service.version`	string	`latest`
`TERO_LOG_LEVEL`	`log_level`	`debug`/`info`/`warn`/`err`	`info`
`TERO_MAX_BODY_SIZE`	`max_body_size`	bytes	`1048576`
`TERO_MAX_DECODED_BYTES`	`max_decoded_bytes`	bytes, optional	unset
`TERO_MAX_CONNECTIONS`	`max_connections`	count	`256`
`TERO_WORKER_COUNT`	`worker_count`	count, optional	unset
`TERO_THREAD_POOL_COUNT`	`thread_pool_count`	count, optional	unset
`TERO_TAP_ENABLED`	`tap_enabled`	`true`/`false`/`1`/`0`	`false`
`TERO_PROMETHEUS_MAX_INPUT_BYTES_PER_SCRAPE`	`prometheus.max_input_bytes_per_scrape`	bytes	`10485760`
`TERO_PROMETHEUS_MAX_OUTPUT_BYTES_PER_SCRAPE`	`prometheus.max_output_bytes_per_scrape`	bytes	`10485760`

Defaults above are the built-in ones. Each distribution image bakes a config.json that already changes some of them — edge-datadog, for example, ships listen_address: 0.0.0.0, service.namespace: production, and a Datadog US1 upstream_url. Env vars override whichever value the file set.

Rules worth knowing:

Optional fields accept an empty string to mean “unset”. TERO_METRICS_URL= sets metrics_url back to null rather than to an empty URL.
An unparseable value fails startup. TERO_LOG_LEVEL=bogus or a non-numeric TERO_LISTEN_PORT exits with config.load.error err="InvalidValue" instead of silently falling back to the default.
Lists are not overridable. policy_providers, service.resource_attributes, and service.labels are arrays, so they have no env var — supply a config file, or use value substitution for the strings inside it. Setting a TERO_ variable that matches no field is silently ignored, so a typo fails quietly.
service.instance_id and service.supported_stages are ignored. Both are set by the runtime at startup — the instance ID is generated per process, and the supported stages come from the distribution.

Other Environment Variables

These are read directly rather than as config-field overrides:

Variable	Purpose
`TERO_IO_BACKEND`	I/O backend: `inherited` (default) or `single_threaded`. Unknown values warn and fall back to `inherited`.
`TERO_API_KEY`	Referenced as `${TERO_API_KEY}` by the bundled configs for policy sync.

Introduction

Architecture

Distributions

How-to guides

Edge Reference

Policy Reference

Source

Configuration File

Full Example

Configuration Reference

Server Settings

Upstream Settings

Service Settings

Policy Providers

File Provider

HTTP Provider

Prometheus Settings

Policy File Format

Environment Variables

Value Substitution

Field Overrides

Other Environment Variables

Next Steps

Operations

Log Filtering

​Configuration File

​Full Example

​Configuration Reference

​Server Settings

​Upstream Settings

​Service Settings

​Policy Providers

​File Provider

​HTTP Provider

​Prometheus Settings

​Policy File Format

​Environment Variables

​Value Substitution

​Field Overrides

​Other Environment Variables

​Next Steps

Operations

Log Filtering

Configuration File

Full Example

Configuration Reference

Server Settings

Upstream Settings

Service Settings

Policy Providers

File Provider

HTTP Provider

Prometheus Settings

Policy File Format

Environment Variables

Value Substitution

Field Overrides

Other Environment Variables

Next Steps