Skip to main content

The local-directory connector

The local-directory connector ingests logs from a folder on the same machine that runs Log Lens. When your Laravel, Horizon, nginx, or console logs live on the local filesystem, this is the simplest way to point Log Lens at them - no SSH, no credentials, just a path.

Configuration​

A local connector needs a name and a directory. The directory is validated on save: it must be an existing, readable folder, otherwise the connector is rejected with "A readable local directory is required." The path is resolved to its canonical (realpath) form and stored.

KeyTypeDefaultNotes
directorystring-Required. Must be an existing, readable directory.
recursivebooltrueDescend into subdirectories.

You can also attach a connector to a module and toggle it enabled or disabled. Connector names must be unique and contain 1-100 characters.

Discovery and recursion​

When Log Lens scans the connector, it walks the directory looking for log files:

  • With recursive on (the default), every subdirectory is traversed.
  • With recursive off, only files directly inside the directory are considered.

A file counts as a log only if its name matches the log-file pattern - by default *.log and rotated variants like app.log.1. See which files count as logs for the exact rule. Discovered files are sorted by path so scans are stable and predictable.

Each file is tracked by its device and inode, not just its name. That means Log Lens keeps following a file across renames and rotations, which powers incremental ingestion and log rotation handling.

Testing the connection​

Use the connector's Test action before relying on it. A local connector runs discovery and reports how many log files it found:

{ "ok": true, "message": "Connection succeeded; discovered 4 log file(s)." }

If the count is zero, check that recursive is set correctly and that the files actually match the log-file pattern.

Edge cases​

  • The directory is re-validated whenever the connector runs; if it is later deleted or moved, discovery fails with "The configured local log directory does not exist."
  • Reads happen in byte ranges (see byte-range storage), so only new bytes are pulled on each sync.