File source

The file source watches a directory for log files and tails them line by line. It tracks read positions across restarts using a high-watermark file so no logs are missed.

Configuration

{
  "sources": {
    "app-logs": {
      "type": "file",
      "path": "/var/log/app/",
      "extension": ".log"
    }
  }
}

Options

Option	Type	Default	Description
`path`	string	required	Directory to watch
`extension`	string	`""`	File extension filter (e.g. `".log"`)
`recursive`	bool	`false`	Watch subdirectories
`include`	string[]	`null`	Glob patterns to include (matched on filename)
`exclude`	string[]	`null`	Glob patterns to exclude (matched on filename)

Either extension or include patterns must be set. Reveald rejects a config with neither. Use include when files have no extension or when you need finer control than a single suffix.

Examples

Tail all `.log` files in a directory

{
  "sources": {
    "app": {
      "type": "file",
      "path": "/var/log/app/",
      "extension": ".log"
    }
  }
}

Recursive directory watch with glob patterns

{
  "sources": {
    "pods": {
      "type": "file",
      "path": "/var/log/pods/",
      "extension": ".log",
      "recursive": true,
      "exclude": ["*.tmp", "*.gz"]
    }
  }
}

Extensionless files and glob patterns

Use include when log files have no extension — for example /var/log/messages, CURRENT, or rotation files named 0, 1, 2. Set include to one or more glob patterns and omit extension, or combine both when you need a suffix plus a name filter.

Patterns are matched against the filename only (not the full path). Reveald uses Go filepath.Match glob syntax:

Pattern	Matches
`*`	Any sequence of characters
`?`	Any single character
`[abc]`	Any character in the set

When both extension and include are set, a file must satisfy both filters. exclude patterns are applied last and override a match.

Tail a single extensionless file

{
  "sources": {
    "syslog": {
      "type": "file",
      "path": "/var/log/",
      "include": ["messages"]
    }
  }
}

Tail extensionless files by name prefix

{
  "sources": {
    "app": {
      "type": "file",
      "path": "/var/log/app/",
      "include": ["access*", "error*"],
      "recursive": true
    }
  }
}

Tail all files in a directory (extensionless or not)

Use include: ["*"] to match every filename, then narrow with exclude:

{
  "sources": {
    "all-logs": {
      "type": "file",
      "path": "/var/log/app/",
      "include": ["*"],
      "exclude": ["*.gz", "*.tmp", "*.bak", "*.old"],
      "recursive": true
    }
  }
}

include: ["*"] watches every file in the directory. Prefer specific patterns or exclude rules on busy hosts so reveald does not tail sockets, lock files, or other non-log files.

Combine extension and include

When files share an extension but you only want a subset, set both:

{
  "sources": {
    "access": {
      "type": "file",
      "path": "/var/log/nginx/",
      "extension": ".log",
      "include": ["access*"]
    }
  }
}

This tails access.log and access.log.1 but not error.log.

Event fields

Field	Value
`sourceType`	`"file"`
`rawLog`	The log line content
`eventTime`	Current time when the line is read
`tags.file`	Full path of the file being read

High-watermark

The file source saves its read position to ~/.config/reveald/watcher-hwm.json. This allows reveald to resume from where it left off after a restart. Delete this file to reprocess from the beginning.

Log rotation

Reveald detects file rotation automatically. When a file is rotated (renamed or truncated), reveald picks up the new file matching the configured patterns and continues reading.

On this page