diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c38778..da4b134 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,15 @@ All notable changes to this project are documented here. The format follows ## [Unreleased] +### Added + +- DEBUG logging of every action, one line each, never the output: `flipperone.linux` (a command or a file read, its + exit code, time and sizes; streams, file copies), `flipperone.cli` (an MCU or probe command, its time and reply size; + streams and watches). `flipperone.wire` (the bytes) stays as it was. +- DEBUG logging of each command's output, as a record after its line, indented, stderr under `err:`: + `flipperone.linux.output`, `flipperone.cli.output`; `log_output_limit` of `Linux` and of the CLI devices (64 KiB by + default) caps each stream, the rest is counted. + ## [0.1.0] - 2026-11-15 ### Added diff --git a/README.md b/README.md index b516076..d193fc5 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,12 @@ with connect.linux_over_ssh("10.0.0.1", password="...") as linux: The subsystem classes take any transport: `Mcu(stream)` runs over a serial port, an SSH channel or your own stream; `Linux(shell)` over SSH or your own shell. `flipperone.connect` only pairs them the usual way. +Nothing is printed. At DEBUG the library logs every action in one line, never its output: `flipperone.linux` +(commands, file reads, streams, copies: exit code, time, sizes) and `flipperone.cli` (MCU and probe commands: time, +reply size); `flipperone.linux.output` and `flipperone.cli.output` add each command's output after its line (up to +`log_output_limit` bytes per stream, 64 KiB by default). `flipperone.wire` logs the bytes themselves at DEBUG: silence +it, or the output loggers, on its own (`logging.getLogger("flipperone.wire").setLevel(logging.WARNING)`). + ## Documentation - [docs/transport.md](docs/transport.md) — streams, shells, finding ports diff --git a/src/flipperone/_cli.py b/src/flipperone/_cli.py index f9cf69e..9f4b23b 100644 --- a/src/flipperone/_cli.py +++ b/src/flipperone/_cli.py @@ -17,6 +17,8 @@ from contextlib import contextmanager from dataclasses import dataclass +from ._output import DEFAULT_LIMIT +from ._output import record as output_record from .errors import CliError, CommandNotFound, FlipperOneError, PortNotFound, SyncTimeout, UsageError from .transport.base import Stream @@ -30,6 +32,8 @@ _NOT_FOUND = re.compile(r"could not find command `([^`]*)`") wire = logging.getLogger("flipperone.wire") +log = logging.getLogger("flipperone.cli") # DEBUG: one line per command (the device, the command, time, size) +output_log = logging.getLogger("flipperone.cli.output") # DEBUG: each command's reply, after its line Connect = Callable[[], Stream] @@ -93,8 +97,10 @@ class CliDevice: def __init__(self, connect: Stream | Connect, *, timeout_s: float = 2.0, sync_timeout_s: float = 3.0, settle_s: float = 0.3, reconnect_timeout_s: float = 20.0, - sleep: Callable[[float], None] = time.sleep, clock: Callable[[], float] = time.monotonic): + sleep: Callable[[float], None] = time.sleep, clock: Callable[[], float] = time.monotonic, + log_output_limit: int = DEFAULT_LIMIT): self.timeout_s = timeout_s + self.log_output_limit = log_output_limit # bytes of a reply the flipperone.cli.output logger keeps self.sync_timeout_s = sync_timeout_s self.settle_s = settle_s self.reconnect_timeout_s = reconnect_timeout_s @@ -163,9 +169,16 @@ def reconnect(self, timeout: float | None = None) -> None: def run(self, line: str, timeout: float | None = None) -> Result: """Run one command line and return its reply once the prompt is back.""" + started = self._clock() self._send(line) - raw = self._read_until(PROMPT, timeout or self.timeout_s, f"the prompt after '{line}'") + try: + raw = self._read_until(PROMPT, timeout or self.timeout_s, f"the prompt after '{line}'") + except Exception as e: + log.debug("%s: %s -> %s: %s", type(self).__name__, line, type(e).__name__, e) + raise text = clean(raw, line) + log.debug("%s: %s -> %.2f s, %d B", type(self).__name__, line, self._clock() - started, len(text)) + self._log_reply(line, text) m = _NOT_FOUND.search(text) if m: raise CommandNotFound(f"{self.name}: could not find command `{m.group(1)}`") @@ -177,7 +190,16 @@ def stream(self, line: str, seconds: float) -> Result: raw = self._read_for(seconds) self._write(ETX) raw += self._read_until(PROMPT, self.timeout_s, f"the prompt after stopping '{line}'") - return Result(line, raw, clean(raw, line)) + text = clean(raw, line) + log.debug("%s: %s (for %g s) -> %d B", type(self).__name__, line, seconds, len(text)) + self._log_reply(line, text) + return Result(line, raw, text) + + def _log_reply(self, line: str, text: str) -> None: + if output_log.isEnabledFor(logging.DEBUG): + entry = output_record(f"{type(self).__name__}: {line}", text, limit=self.log_output_limit) + if entry: + output_log.debug("%s", entry) def watch(self, line: str, handler: Callable[[str], bool], timeout: float) -> bool: """Run a command that keeps printing and give each line to ``handler`` as it arrives, until the handler @@ -198,6 +220,8 @@ def watch(self, line: str, handler: Callable[[str], bool], timeout: float) -> bo break self._write(ETX) self._read_until(PROMPT, self.timeout_s, f"the prompt after stopping '{line}'") + log.debug("%s: %s (watched, %g s at most) -> %s", type(self).__name__, line, timeout, + "the handler stopped it" if done else "timed out") return done @contextmanager diff --git a/src/flipperone/_output.py b/src/flipperone/_output.py new file mode 100644 index 0000000..e0b3f9c --- /dev/null +++ b/src/flipperone/_output.py @@ -0,0 +1,23 @@ +# SPDX-License-Identifier: GPL-3.0-or-later +"""A command's output as a log record: what the ``*.output`` loggers write at DEBUG.""" + +from __future__ import annotations + +DEFAULT_LIMIT = 64 * 1024 # bytes of one stream (stdout or stderr) kept in a record; the rest is only counted +INDENT = " " + + +def clip(text: str, limit: int) -> str: + """``text`` cut to ``limit`` bytes (UTF-8), with how many were left out.""" + data = text.encode() + if len(data) <= limit: + return text + return data[:limit].decode(errors="ignore") + f"\n... {len(data) - limit} B more" + + +def record(label: str, out: str, err: str = "", limit: int = DEFAULT_LIMIT) -> str | None: + """``label:`` then the output indented, ``err:`` and stderr after it when there is any; None when both are empty.""" + def indented(text: str) -> str: + return "\n".join(INDENT + line for line in clip(text, limit).rstrip("\n").split("\n")) + parts = ([indented(out)] if out else []) + ([INDENT + "err:", indented(err)] if err else []) + return f"{label}:\n" + "\n".join(parts) if parts else None diff --git a/src/flipperone/linux/linux.py b/src/flipperone/linux/linux.py index ed7a00f..2e8393f 100644 --- a/src/flipperone/linux/linux.py +++ b/src/flipperone/linux/linux.py @@ -3,12 +3,18 @@ from __future__ import annotations +import logging import shlex from collections.abc import Callable, Iterable from pathlib import Path +from .._output import DEFAULT_LIMIT +from .._output import record as output_record from ..transport.base import CommandResult, Shell, Stream +log = logging.getLogger("flipperone.linux") # DEBUG: one line per action (what, exit code, time, sizes), no output +output_log = logging.getLogger("flipperone.linux.output") # DEBUG: each command's stdout and stderr, after its line + MARK = "===FLIPPERONE:" # separates files in a read_many reply; not something sysfs content holds @@ -17,26 +23,44 @@ class Linux: ``shell``: an :class:`~flipperone.transport.ssh.SshShell` (see :func:`flipperone.connect.linux_over_ssh`) or any other :class:`~flipperone.transport.base.Shell`. ``command_timeout_s``: the default for :meth:`run`. + ``log_output_limit``: bytes of a command's stdout (and of its stderr) the ``flipperone.linux.output`` logger keeps. """ - def __init__(self, shell: Shell, *, command_timeout_s: float = 20.0): + def __init__(self, shell: Shell, *, command_timeout_s: float = 20.0, log_output_limit: int = DEFAULT_LIMIT): self.shell = shell self.command_timeout_s = command_timeout_s + self.log_output_limit = log_output_limit def run(self, command: str, *, timeout: float | None = None, check: bool = False, on_line: Callable[[str], None] | None = None) -> CommandResult: """Run a shell command line. ``check``: raise :class:`~flipperone.errors.CommandFailed` on a non-zero exit. ``on_line`` gets each line of stdout as it arrives; the result still holds all of it.""" - result = self.shell.run(command, self.command_timeout_s if timeout is None else timeout, on_line) - return result.check() if check else result + return self._run(command, command, timeout, check, on_line) def sudo(self, command: str, *, timeout: float | None = None, check: bool = False, on_line: Callable[[str], None] | None = None) -> CommandResult: """:meth:`run` as root through ``sudo -n`` (the user needs passwordless sudo).""" - return self.run(f"sudo -n sh -c {shlex.quote(command)}", timeout=timeout, check=check, on_line=on_line) + return self._run(f"sudo -n sh -c {shlex.quote(command)}", f"sudo {command}", timeout, check, on_line) + + def _run(self, command: str, label: str, timeout: float | None, check: bool, + on_line: Callable[[str], None] | None) -> CommandResult: + """``command`` run, logged as ``label`` (what the caller asked for, not the wrapping).""" + try: + result = self.shell.run(command, self.command_timeout_s if timeout is None else timeout, on_line) + except Exception as e: + log.debug("%s -> %s: %s", label, type(e).__name__, e) + raise + log.debug("%s -> exit %d, %.2f s, out %d B%s", label, result.code, result.duration_s, len(result.out), + f", err {len(result.err)} B" if result.err else "") + if output_log.isEnabledFor(logging.DEBUG): + text = output_record(label, result.out, result.err, self.log_output_limit) + if text: + output_log.debug("%s", text) + return result.check() if check else result def open_stream(self, command: str, *, sudo: bool = False) -> Stream: """A command as a duplex byte stream (its stdin and stdout); closing the stream ends it.""" + log.debug("stream %s%s", "sudo " if sudo else "", command) if sudo: command = f"sudo -n sh -c {shlex.quote(command)}" return self.shell.open_stream(command) @@ -53,7 +77,9 @@ def read_many(self, paths: Iterable[str], *, sudo: bool = False) -> dict[str, st script = ("for p in " + " ".join(shlex.quote(p) for p in paths) + f"; do if [ -r \"$p\" ]; then printf '%s\\n' '{MARK}'\"$p\"; cat -- \"$p\" 2>/dev/null; " f"printf '\\n'; else printf '%s\\n' '{MARK}'\"$p\"':missing'; fi; done") - result = self.sudo(script) if sudo else self.run(script) + label = f"{'sudo ' if sudo else ''}read {' '.join(paths)}" + command = f"sudo -n sh -c {shlex.quote(script)}" if sudo else script + result = self._run(command, label, None, False, None) return parse_read_many(result.out, paths) def glob(self, pattern: str) -> list[str]: @@ -65,10 +91,12 @@ def exists(self, path: str) -> bool: return self.run(f"test -e {shlex.quote(path)}").ok def put(self, local: Path, remote: str) -> None: + log.debug("put %s -> %s (%d B)", local, remote, local.stat().st_size) self.shell.put(local, remote) def get(self, remote: str, local: Path) -> None: self.shell.get(remote, local) + log.debug("get %s -> %s (%d B)", remote, local, local.stat().st_size) def close(self) -> None: self.shell.close() diff --git a/tests/test_output_log.py b/tests/test_output_log.py new file mode 100644 index 0000000..d66a170 --- /dev/null +++ b/tests/test_output_log.py @@ -0,0 +1,22 @@ +# SPDX-License-Identifier: GPL-3.0-or-later +import logging + +from flipperone._output import clip, record +from flipperone.linux import Linux +from flipperone.testing import FakeShell + + +def test_record_indents_stdout_then_stderr_and_clips(): + assert record("uname -r", "7.4.0\n") == "uname -r:\n 7.4.0" + assert record("x", "a\nb", "oops") == "x:\n a\n b\n err:\n oops" + assert record("x", "", "") is None + assert clip("abcdef", 4) == "abcd\n... 2 B more" + + +def test_linux_logs_the_action_and_its_output(caplog): + shell = FakeShell({"uname -r": "7.4.0\n"}) + with caplog.at_level(logging.DEBUG, logger="flipperone"): + Linux(shell, log_output_limit=3).run("uname -r") + lines = [(r.name, r.getMessage()) for r in caplog.records] + assert lines[0][0] == "flipperone.linux" and lines[0][1].startswith("uname -r -> exit 0, ") + assert lines[1] == ("flipperone.linux.output", "uname -r:\n 7.4\n ... 3 B more")