Skip to main content

Configuration Reference

infrasagent is configured with a single YAML file. Environment variables in the form ${VAR} or ${VAR:-default} are interpolated at startup.

./infrasagent -config /etc/infrasagent/agent.yaml

Top-Level Structure​

agent:
  name: string          # identifies this agent in telemetry (default: hostname)
  mode: agent | gateway # agent = local collector, gateway = aggregator

api:
  listen: string        # admin API listen address (default: 0.0.0.0:8080)
  api_keys: []string    # if set, requests must include X-API-Key or Authorization: Bearer
  read_only: bool       # disallow /reload via API (default: false)
  tls:
    cert_file: string
    key_file: string

sources:
  <name>:
    type: string        # source plugin name
    # ... source-specific options

processors:
  <name>:
    type: string        # processor plugin name
    sources: []string   # upstream source or processor names
    # ... processor-specific options

sinks:
  <name>:
    type: string        # sink plugin name
    sources: []string   # upstream source or processor names
    # ... sink-specific options

Environment Variable Interpolation​

sinks:
  infrasage:
    type: otlp
    endpoint: "https://api.infrasage.dev"
    auth_header: "Bearer ${INFRASAGE_API_KEY}"

sources:
  kafka_in:
    type: kafka
    brokers: ["${KAFKA_BROKER:-localhost:9092}"]

Syntax:

  • ${VAR} — required; agent exits at startup if missing
  • ${VAR:-default} — uses default if VAR is unset

Routing​

Each sink and processor declares which upstream components feed it via sources:. The pipeline engine builds a DAG from these declarations, validates signal compatibility (e.g. a metrics-only sink refuses to wire to a logs source), and wires channels at startup.

sources:
  app_logs:
    type: file
    include: ["/var/log/app/**/*.log"]

  host_metrics:
    type: hostmetrics
    collection_interval: 15s

processors:
  enrich:
    type: k8s_attributes
    sources: [app_logs]          # only logs

  batch:
    type: batch
    timeout: 5s
    sources: [enrich, host_metrics]   # logs + metrics

sinks:
  infrasage:
    type: otlp
    endpoint: "https://api.infrasage.dev"
    protocol: http
    auth_header: "Bearer ${INFRASAGE_API_KEY}"
    sources: [batch]

Hot Reload​

Send SIGHUP to reload the config without restarting:

kill -HUP $(pgrep infrasagent)

Or call the API:

curl -X POST http://localhost:8080/reload \
  -H "X-API-Key: ${ADMIN_API_KEY}"

The agent validates the new config, starts the new pipeline, drains the old one with a 5-second grace window, and swaps atomically. No data is lost.

Full Example​

agent:
  name: "${HOSTNAME}-agent"
  mode: agent

api:
  listen: "0.0.0.0:8080"
  api_keys: ["${ADMIN_API_KEY}"]

sources:
  otlp_in:
    type: otlp
    grpc:
      listen: "0.0.0.0:4317"
    http:
      listen: "0.0.0.0:4318"

  host_metrics:
    type: hostmetrics
    collection_interval: 15s
    scrapers: [cpu, memory, disk, network, load, processes]

  app_logs:
    type: file
    include: ["/var/log/app/**/*.log"]
    multiline:
      mode: halt_before
      condition_pattern: '^\d{4}-\d{2}-\d{2}'

  syslog_in:
    type: syslog
    listen: "0.0.0.0:514"
    protocol: udp

processors:
  k8s_enrich:
    type: k8s_attributes
    sources: [otlp_in, app_logs]

  add_env:
    type: attributes
    sources: [k8s_enrich, syslog_in, host_metrics]
    actions:
      - action: insert
        key: deployment.environment
        value: "${ENV:-production}"

  drop_debug:
    type: filter
    sources: [add_env]
    logs:
      severity_number:
        min: 9   # drop DEBUG (1-8), keep INFO and above

  batch_main:
    type: batch
    timeout: 5s
    max_size: 10000
    sources: [drop_debug]

  trace_sample:
    type: sampling
    sources: [otlp_in]
    policies:
      - name: errors
        type: error
      - name: slow
        type: latency
        threshold_ms: 500
      - name: baseline
        type: probabilistic
        sampling_percentage: 10

sinks:
  infrasage:
    type: otlp
    endpoint: "https://api.infrasage.dev"
    protocol: http
    auth_header: "Bearer ${INFRASAGE_API_KEY}"
    sources: [batch_main, trace_sample]

  local_clickhouse:
    type: clickhouse
    endpoint: "tcp://clickhouse:9000"
    database: infrasage
    username: default
    password: "${CH_PASSWORD}"
    compression: lz4
    async_insert: true
    sources: [batch_main]