The Log File Reader is an agent feature that creates HPA metrics from fixed-width log files. It is useful for monitoring external systems (batch schedulers, middleware, application logs) whose activity is written as structured text lines with fixed column positions.

This feature requires the LOG_FILE_READER licence module.

Principle

The agent periodically scans configured directories for matching log files, reads new lines since the last collection cycle, and turns each qualifying line into an HPA metric.

One or more readers are defined in a YAML configuration file. Each reader watches a directory and applies its own parsing rules.

Concepts

Reader

A reader is a named configuration block that targets one directory and one family of log files. Its name appears in the metric path, so it should be short and descriptive (e.g. CTM_DAILY, APP_ERRORS).

Key field

Each reader defines a key field: a fixed-width column extracted from every line. Field positions are 0-based and counted in characters. The key field acts as a filter — only lines whose key value appears in the allowed-values list produce a metric. An optional alias can replace the raw value in the metric path for readability.

For example, if the key field column contains status codes 2 and 3, an alias can map 2 to OK while keeping 3 as-is.

Extract fields

Optional additional fixed-width columns can be extracted. Each extracted value becomes an extra node in the metric path, allowing finer-grained breakdowns.

File rotation

Log files that are renamed during rotation (e.g. app.log becomes app.log.1) are handled transparently — reading resumes where it stopped regardless of the file name change. The file-name-regex must match both the active file and the rotated names.

Configuration

See the Log File Reader configuration reference for the full YAML schema and examples.

Produced metrics

See the Log File Reader metrics reference for the list of metrics produced by this feature.