Configuration

Reveald is configured with a single JSON file. The file uses HUJSON format, which extends JSON with support for comments and trailing commas.

Config file structure

A reveald config has two top-level keys: sources and destinations. Both are maps where each entry has a unique name and a type field that determines which source or destination is used.

{
  // Sources collect logs from the host
  "sources": {
    "my-source-name": {
      "type": "file",
      "path": "/var/log/app/",
      "extension": ".log"
    }
  },
  // Destinations forward collected events
  "destinations": {
    "my-destination-name": {
      "type": "runreveal",
      "webhookURL": "https://api.runreveal.com/sources/reveald/webhook/..."
    }
  }
}

The source and destination names (e.g. "my-source-name") are identifiers used in logging and metrics. Choose descriptive names.

By default every source feeds every destination --- all events from all sources are delivered to all configured destinations. Add an optional routes section to control which destinations receive events from each source.

Environment variables

Sensitive values like webhook URLs and API keys can be referenced as environment variables. Prefix the value with $ and use a valid environment variable name:

{
  "destinations": {
    "runreveal": {
      "type": "runreveal",
      "webhookURL": "$WEBHOOK_URL"
    }
  }
}

Then set the variable before running reveald:

export WEBHOOK_URL="https://api.runreveal.com/sources/reveald/webhook/..."
reveald run --config config.json

Default config path

The default config path is /etc/reveald/config.json. Override it with the --config or -c flag:

reveald run --config /opt/reveald/config.json
reveald run -c ./config.json

Debug logging

Set the RUNREVEAL_DEBUG environment variable to enable debug-level logging:

RUNREVEAL_DEBUG=1 reveald run --config config.json

Multiple sources and destinations

You can define as many sources and destinations as needed. Each runs concurrently:

{
  "sources": {
    "kubernetes-pods": {
      "type": "file",
      "path": "/var/log/pods/",
      "extension": ".log",
      "recursive": true
    },
    "system-journal": {
      "type": "journald"
    },
    "nginx": {
      "type": "nginx_syslog",
      "addr": "0.0.0.0:5514"
    }
  },
  "destinations": {
    "runreveal": {
      "type": "runreveal",
      "webhookURL": "$WEBHOOK_URL",
      "batchSize": 200,
      "flushFreq": "10s"
    },
    "archive": {
      "type": "s3",
      "bucketName": "my-log-archive",
      "bucketRegion": "us-west-2"
    }
  }
}

Routing

By default reveald delivers every source's events to every destination. The optional routes section overrides this so a given source only reaches the destinations you choose. This lets a single reveald instance, for example, send audit logs to one RunReveal workspace and application logs to another, or archive some sources to S3 while forwarding others to RunReveal.

routes is a map keyed by source name, whose value is the list of destination names that should receive that source's events:

{
  "sources": {
    "app": { "type": "file", "path": "/var/log/app/", "extension": ".log" },
    "audit": { "type": "journald" }
  },
  "destinations": {
    "saas": { "type": "runreveal", "webhookURL": "$SAAS_URL" },
    "ce": { "type": "runreveal", "webhookURL": "$CE_URL" },
    "archive": { "type": "s3", "bucketName": "my-logs", "bucketRegion": "us-west-2" }
  },
  "routes": {
    "app": ["saas", "archive"], // app events -> saas + archive
    "audit": ["ce"], // audit events -> ce only
    "*": ["archive"] // any other source -> archive
  }
}

Wildcards

• A source key of "*" is a catchall route applied to any source that doesn't have its own explicit entry.
• A destination value of "*" expands to every configured destination (for example "app": ["*"] sends the app source to all destinations).

Defaults and backwards compatibility

• If routes is omitted or empty, every source is delivered to every destination (the historical behavior).
• If routes is present but a source has no explicit entry and there is no "*" catchall, that source falls back to all destinations.
• A source routed to an empty list ("app": []) is dropped --- its events are not delivered anywhere.

High-watermark files

Reveald persists read positions so it can resume after restarts without reprocessing logs:

These files are created automatically. If you need a clean start, stop reveald and delete the relevant watermark file.

Full example

Here is a production-ready configuration collecting from multiple sources:

{
  // Collect application logs, journald, and nginx access logs
  "sources": {
    "app": {
      "type": "file",
      "path": "/var/log/app/",
      "extension": ".log",
    },
    "journal": {
      "type": "journald",
    },
    "nginx": {
      "type": "nginx_syslog",
      "addr": "0.0.0.0:5514",
    },
  },
  "destinations": {
    "runreveal": {
      "type": "runreveal",
      "webhookURL": "$WEBHOOK_URL",
      "batchSize": 100,
      "flushFreq": "15s",
    },
  },
}

Related

• Sources --- All source type options
• Destinations --- All destination type options
• Processors --- Transform events before forwarding