Rotation

log_ctrl recognizes the following two log filename formats:

<log_name>.log
<log_name>.log.YYYY-MM-DD

Examples:

cobotta4_server.log
cobotta4_server.log.2026-03-31
cobotta4_server.log.2026-04-06

Current log

A file without a date suffix,

<log_name>.log

is the current log.

The current log has no special date such as current and no virtual filename.

data = client.read("cobotta4_server")

reads:

cobotta4_server.log

This is the current log file.

Rotated logs

data = client.read(
    "cobotta4_server",
    date="2026-04-06",
)

reads:

cobotta4_server.log.2026-04-06

This is the dated log file.

Dates are strictly validated in YYYY-MM-DD format.

Listing dates

dates = client.dates(
    "cobotta4_server"
)

dates() examines existing files matching:

<log_name>.log.YYYY-MM-DD

and returns only files with valid date suffixes.

The results are sorted newest first.

[
    "2026-04-06",
    "2026-03-31",
    "2026-03-30",
]

Dates need not be consecutive; missing dates are not filled in.

The current <log_name>.log is not included in dates().

`log_names()`

log_names() extracts log_name values from both current and rotated logs.

Therefore, if only:

old_device.log.2026-02-19

exists, and:

old_device.log

does not exist,

client.log_names()

still includes "old_device".

Check separately whether the current log exists using:

client.exists("old_device")

This call tests the current file.

Responsibility for rotation

log_ctrl itself does not perform:

Writing logs
Rotating logs
Managing the number of retained generations
Deleting old logs

These operations are outside its scope.

They are the responsibility of the log-writing process. log_ctrl only accesses files that actually exist in the directory.

Files outside the naming convention

log_names() and dates() parse only files matching the log naming convention above.

For troubleshooting, however:

client.raw_files()

returns every file under log_dir, without filtering by filename.

Consequently, even a file outside the naming convention can be read with:

client.read_raw(relative_path)

This retrieves its contents.

Path restrictions

For ordinary read(), tail(), exists(), and dates() calls, log_name cannot contain a path. The log_name itself also cannot include .log.

read_raw() accepts a relative path, but rejects paths that resolve outside log_dir. Absolute paths are also prohibited.