Document structured logging and define failure ownership

CHANGES

@@ -45,6 +45,105 @@ $ uvx --from 'libtmux' --prerelease allow python
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Breaking changes
+
+#### Query records use the command logger (#748)
+
+Calls through {func}`~libtmux.neo.fetch_objs` no longer emit the `tmux list
+queried` and `tmux list parsed` `DEBUG` records from `libtmux.neo`. They produce
+`tmux command dispatched` and `tmux command completed` records from
+`libtmux.common` instead. Applications that configure module-specific logging
+now select the command logger:
+
+```python
+import logging
+
+# Before
+query_logger = logging.getLogger("libtmux.neo")
+
+# After
+query_logger = logging.getLogger("libtmux.common")
+```
+
+`libtmux.common` carries every tmux subprocess rather than list queries alone.
+Filter a handler on the `tmux_subcommand` field to isolate queries again;
+{ref}`logging` shows the filter.
+
+#### Raised failures stay in the exception channel (#748)
+
+A failure that libtmux propagates or translates no longer emits an `ERROR`
+record first. Applications that consumed those records now log at their own
+exception boundary.
+
+```python
+import logging
+
+from libtmux import exc
+
+logger = logging.getLogger(__name__)
+
+# Before
+operation()
+
+# After
+try:
+    operation()
+except exc.LibTmuxException:
+    logger.exception("libtmux operation failed")
+    raise
+```
+
+#### Unusable tmux executables share one exception (#748)
+
+Missing, non-executable, and malformed tmux executables now raise
+{exc}`~libtmux.exc.TmuxCommandNotFound` from
+{class}`~libtmux.common.tmux_cmd` and
+{meth}`Server.raise_if_dead() <libtmux.Server.raise_if_dead>`. Attempted
+launches preserve the operating-system message and cause. Other launch
+failures remain native `OSError` values.
+
+```python
+available = True
+try:
+    server.raise_if_dead()
+# Before: except (exc.TmuxCommandNotFound, OSError):
+# After:
+except exc.TmuxCommandNotFound:
+    available = False
+```
+
+### What's new
+
+#### Structured records identify tmux work (#748)
+
+Command `DEBUG` records add best-effort subcommand and socket fields while
+retaining the complete command, exit status, bounded output snapshots, and
+line counts. Lifecycle `INFO` records consistently identify affected sockets,
+sessions, windows, panes, and targets.
+
+Applications can route and format these fields independently through
+standard-library handlers without modifying the original records.
+
+#### Handled failures produce one diagnostic (#748)
+
+{attr}`Server.sessions <libtmux.Server.sessions>`,
+{attr}`Server.attached_sessions <libtmux.Server.attached_sessions>`, and
+{attr}`Server.clients <libtmux.Server.clients>` now emit one `ERROR` record
+when they convert a tmux execution failure to an empty result. Expected probes
+and failures returned to callers stay quiet.
+
+Malformed `terminal-features`, `terminal-overrides`, and `command-alias`
+entries produce one aggregate `WARNING` per option with the skipped-entry
+count.
+
+### Fixes
+
+#### Caller-controlled log context stays on one line (#748)
+
+Command arguments, socket labels, object identities, targets, and failed
+lookup paths escape control characters before rendering, so one value cannot
+forge additional log lines.
+
 ### Documentation
 
 #### Cleaner `from_env` examples (#719)
@@ -57,6 +156,12 @@ environment-setup plumbing, so each example leads with the constructor call it
 demonstrates instead of the socket-path and `$TMUX` boilerplate needed to run
 it.
 
+#### Logging configuration and record reference (#748)
+
+{ref}`logging` documents logger ownership, levels, structured fields, failure
+routing, payload policy, handler filtering and formatting, and `caplog`
+assertions.
+
 ### Development
 
 #### CI actions updated to current majors

MIGRATION

@@ -113,6 +113,111 @@ sections below for detailed migration examples and code samples.
 _Detailed migration steps for the next version will be posted here._
 <!-- END PLACEHOLDER - ADD NEW MIGRATION ENTRIES BELOW THIS LINE -->
 
+## libtmux 0.63.x: Failure and logging channels (#748)
+
+### An unusable tmux binary raises `TmuxCommandNotFound`
+
+{class}`~libtmux.common.tmux_cmd` and
+{meth}`Server.raise_if_dead() <libtmux.Server.raise_if_dead>` translate a
+missing, non-executable, or malformed tmux executable into
+{exc}`~libtmux.exc.TmuxCommandNotFound`. That exception subclasses
+{exc}`~libtmux.exc.LibTmuxException`, not `OSError`. Through 0.62.0 a
+non-executable binary surfaced as `PermissionError` and a malformed one as
+`OSError`, so a handler written for either class stops firing.
+
+**Who is affected:** code catching `OSError` or `PermissionError` around a
+tmux launch. Launch failures carrying any other errno still propagate as a
+native `OSError`.
+
+**Before:**
+
+```python
+try:
+    server.raise_if_dead()
+except OSError:
+    available = False
+```
+
+**After:**
+
+```python
+from libtmux import exc
+
+try:
+    server.raise_if_dead()
+except exc.TmuxCommandNotFound:
+    available = False
+```
+
+The operating system's diagnostic survives the translation whenever the launch
+was attempted: the message carries it and `__cause__` holds the original
+`OSError`. A tmux binary absent from `PATH` is never launched, so its
+`__cause__` is `None`.
+
+```python
+from libtmux import exc
+
+try:
+    server.raise_if_dead()
+except exc.TmuxCommandNotFound as error:
+    errno = getattr(error.__cause__, "errno", None)
+```
+
+### Raised failures no longer emit an `ERROR` record
+
+Through 0.62.0 libtmux logged an `ERROR` record before propagating or
+translating a failure. A raised failure now reaches the caller through the
+exception channel alone. `ERROR` records mark the opposite case, a boundary
+that swallowed a failure and returned an empty result:
+{attr}`Server.sessions <libtmux.Server.sessions>`,
+{attr}`Server.attached_sessions <libtmux.Server.attached_sessions>`, and
+{attr}`Server.clients <libtmux.Server.clients>`.
+
+**Who is affected:** alerting and log scraping that counted libtmux `ERROR`
+records to detect failed operations. Log at your own exception boundary:
+
+```python
+import logging
+
+from libtmux import exc
+
+logger = logging.getLogger(__name__)
+
+try:
+    operation()
+except exc.LibTmuxException:
+    logger.exception("libtmux operation failed")
+    raise
+```
+
+### Query `DEBUG` records come from `libtmux.common`
+
+{func}`~libtmux.neo.fetch_objs`, the query path behind the object list
+accessors, emitted `tmux list queried` and `tmux list parsed` on `libtmux.neo`
+through 0.62.0. The shared command producer emits `tmux command dispatched`
+and `tmux command completed` on `libtmux.common` in their place.
+
+**Who is affected:** logging configuration naming `libtmux.neo`, and
+assertions on the old message text. `libtmux.common` carries every tmux
+subprocess rather than list queries alone; filter a handler on the
+`tmux_subcommand` field to isolate queries. See {ref}`logging`.
+
+**Before:**
+
+```python
+import logging
+
+logging.getLogger("libtmux.neo").setLevel(logging.DEBUG)
+```
+
+**After:**
+
+```python
+import logging
+
+logging.getLogger("libtmux.common").setLevel(logging.DEBUG)
+```
+
 ## libtmux 0.62.0: Query exceptions join the hierarchy (#718)
 
 {exc}`~libtmux.exc.ObjectDoesNotExist` and

conftest.py

@@ -58,6 +58,7 @@ def add_doctest_fixtures(
             session=session,
         )
         doctest_namespace["monkeypatch"] = request.getfixturevalue("monkeypatch")
+        doctest_namespace["caplog"] = request.getfixturevalue("caplog")
 
 
 @pytest.fixture(autouse=True)

docs/topics/index.md

@@ -55,6 +55,13 @@ Create sessions, windows, and panes programmatically.
 Common patterns for scripting and automation.
 :::
 
+:::{grid-item-card} Logging
+:link: logging
+:link-type: doc
+Structured log records, the `tmux_` field schema, and application-owned
+handlers.
+:::
+
 :::{grid-item-card} Context Managers
 :link: context_managers
 :link-type: doc
@@ -96,6 +103,7 @@ floating_panes
 workspace_setup
 automation_patterns
 context_managers
+logging
 options_and_hooks
 clients
 format-tokens