akkudoktoreos.core.logging.read_file_log

akkudoktoreos.core.logging.read_file_log(log_path: Path, limit: int = 100, level: str | None = None, contains: str | None = None, regex: str | None = None, from_time: str | None = None, to_time: str | None = None, tail: bool = False) → List[dict]

Read and filter structured log entries from a JSON-formatted log file.

Parameters:

  • log_path (Path) – Path to the JSON-formatted log file.

  • limit (int, optional) – Maximum number of log entries to return. Defaults to 100.

  • level (Optional[str], optional) – Filter logs by log level (e.g., “INFO”, “ERROR”). Defaults to None.

  • contains (Optional[str], optional) – Filter logs that contain this substring in their message. Case-insensitive. Defaults to None.

  • regex (Optional[str], optional) – Filter logs whose message matches this regular expression. Defaults to None.

  • from_time (Optional[str], optional) – ISO 8601 datetime string to filter logs not earlier than this time. Defaults to None.

  • to_time (Optional[str], optional) – ISO 8601 datetime string to filter logs not later than this time. Defaults to None.

  • tail (bool, optional) – If True, read the last lines of the file (like tail -n). Defaults to False.

Returns:

A list of filtered log entries as dictionaries.

Return type:

List[dict]

Raises:

  • FileNotFoundError – If the log file does not exist.

  • ValueError – If the datetime strings are invalid or improperly formatted.

  • Exception – For other unforeseen I/O or parsing errors.