Collector configuration reference

Everything you can put in collector.yaml. Sane defaults across the board — minimum-viable config is a single trefur.api_key line.

Minimum-viable config

trefur:
  api_key: "${TREFUR_API_KEY}"
  endpoint: "https://api.trefur.com"  # default

inputs:
  otel:
    enabled: true                      # accept OTLP traces / metrics / logs

Secrets interpolation

Every YAML string field accepts ${ENV_VAR} interpolation. Use it for anything sensitive — the literal value comes from the environment at startup, never from disk.

trefur:
  api_key: "${TREFUR_API_KEY}"

inputs:
  otel:
    enabled: true

If you commit the YAML to git you only commit placeholders. If a config file leaks, the attacker sees ${TREFUR_API_KEY}, not the actual key.

Shutdown drain window

shutdown:
  grace_seconds: 15           # max drain window on SIGTERM (5..300)

On SIGTERM the collector stops accepting new events and flushes in-flight batches, up to grace_seconds. Values outside 5..300 are clamped and logged at load time.

Path-typed fields (TLS cert / key, CA bundles, file inputs) accept a leading ~ and expand to the current user's home at load time.

Batching & on-disk buffer

The collector batches events before each HTTPS export and spills to an encrypted on-disk buffer when the upstream is unreachable. Today these run on fixed, sensible defaults:

Behavior	Current value
Events per export batch	`100`
Max wait before flushing a partial batch	`5s`
On-disk buffer cap	`50 MB`

The processing.batch_size, processing.flush_every, buffer.max_disk_mb, and buffer.disk_path keys are accepted by the config parser (a config that sets them still validates) but are not yet honored at runtime — the values above are fixed in the current release. Don't rely on overriding them yet.

Resource-constrained tuning (Raspberry Pi / edge VM)

On tightly-resourced hosts the knobs that do take effect are the shutdown drain window and the log level:

shutdown:
  grace_seconds: 30           # slower flushes, more drain time

logging:
  level: "warn"               # trim journal volume

Cloud-authored pipeline DSL

Rules authored in the Trefur dashboard (drop / mask / extract / route / enrich) are pulled to the collector every 60s and applied before data leaves your network.

pipeline_puller:
  enabled: true                                       # default true
  interval_seconds: 60                                # default 60; floor 10
  endpoint: ""                                        # default composes trefur.endpoint + /api/v1/collector/pipelines
  cache_path: "~/.trefur-collector/pipelines.json"    # default; "" disables persistence

Dropped events are counted via the Prometheus metric trefur_collector_pipeline_dropped_total{source,pipeline_name} on /metrics/prometheus on the health server.

Environment overrides

Canonical list: env-vars reference. The most common are TREFUR_API_KEY, TREFUR_ENDPOINT, TREFUR_COLLECTOR_CONFIG, and TREFUR_LOG_LEVEL.