refactor(feat[logging]) structured logging with lifecycle events (#637)

Add structured lifecycle logging across Server, Session, Window, and
Pane. All lifecycle operations (create, kill, rename, split) now emit
INFO-level log records with structured `extra` context using scalar
keys (`tmux_subcommand`, `tmux_session`, `tmux_window`, `tmux_pane`,
`tmux_target`) for filtering in log aggregators and test assertions
via `caplog.records`.

- **NullHandler**: add to library `__init__.py` per Python logging
  best practices
- **DEBUG logging**: structured `tmux_cmd` execution logs with
  `isEnabledFor` guards and heavy keys (`tmux_stdout`,
  `tmux_stderr`, `tmux_stdout_len`, `tmux_stderr_len`)
- **Lazy formatting**: replace f-string log formatting with `%s`
  throughout; replace `traceback.print_stack()` with
  `logger.debug(exc_info=True)`
- **Options warnings**: replace `logger.exception()` with
  `logger.warning()` and `tmux_option_key` structured context for
  recoverable parse failures
- **Cleanup**: remove unused logger definitions from modules that
  don't log

Bug fixes:

- **Window.rename_window()**: propagate errors instead of silently
  swallowing exceptions
- **Server.kill()**: check stderr, raise on unexpected errors,
  handle "no server running" gracefully
- **Server.new_session()**: raise `LibTmuxException` on
  `kill-session` stderr when `kill_session=True`
- **Session.kill_window()**: fix `self.window_name` →
  `self.session_name` for integer target formatting; widen type
  signature to `str | int | None`

Author: tony

AGENTS.md

@@ -307,13 +307,16 @@ Pass structured data on every log call where useful for filtering, searching, or
 | `tmux_session` | `str` | session name |
 | `tmux_window` | `str` | window name or index |
 | `tmux_pane` | `str` | pane identifier |
+| `tmux_option_key` | `str` | tmux option name |
 
 **Heavy/optional keys** (DEBUG only, potentially large):
 
 | Key | Type | Context |
 |-----|------|---------|
 | `tmux_stdout` | `list[str]` | tmux stdout lines (truncate or cap; `%(tmux_stdout)s` produces repr) |
 | `tmux_stderr` | `list[str]` | tmux stderr lines (same caveats) |
+| `tmux_stdout_len` | `int` | number of stdout lines |
+| `tmux_stderr_len` | `int` | number of stderr lines |
 
 Treat established keys as compatibility-sensitive — downstream users may build dashboards and alerts on them. Change deliberately.
 

CHANGES

@@ -36,6 +36,42 @@ $ uvx --from 'libtmux' --prerelease allow python
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+#### Structured lifecycle logging across Server, Session, Window, and Pane (#637)
+
+All lifecycle operations (create, kill, rename, split) now emit INFO-level log
+records with structured `extra` context. Every log call includes scalar keys
+such as `tmux_subcommand`, `tmux_session`, `tmux_window`, `tmux_pane`, and
+`tmux_target` for filtering in log aggregators and test assertions via
+`caplog.records`.
+
+- Add `NullHandler` to library `__init__.py` per Python logging best practices
+- Add DEBUG-level structured logs for `tmux_cmd` execution with `isEnabledFor` guards
+- Replace f-string log formatting with lazy `%s` formatting throughout
+- Replace `traceback.print_stack()` calls with proper `logger.debug(exc_info=True)`
+- Replace `logger.exception()` in options parsing with `logger.warning()` and `tmux_option_key` context
+- Remove unused logger definitions from modules that don't log
+
+### Bug fixes
+
+#### Window.rename_window() now raises on failure instead of silently swallowing (#637)
+
+Previously `rename_window()` caught all exceptions and logged them, masking
+tmux errors. It now propagates the error, consistent with all other command
+methods.
+
+#### Server.kill() captures stderr and handles "no server running" gracefully (#637)
+
+`Server.kill()` previously discarded the tmux return value. It now checks
+stderr, raises on unexpected errors, and silently returns for expected
+conditions ("no server running", "error connecting to").
+
+#### Server.new_session() checks kill-session stderr (#637)
+
+When `kill_session=True` and the existing session kill fails, `new_session()`
+now raises `LibTmuxException` with the stderr instead of proceeding silently.
+
 ## libtmux 0.53.1 (2026-02-18)
 
 ### Bug fixes

src/libtmux/__init__.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import logging
+
 from .__about__ import (
     __author__,
     __copyright__,
@@ -17,6 +19,8 @@
 from .session import Session
 from .window import Window
 
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
 __all__ = (
     "Pane",
     "Server",

src/libtmux/_internal/constants.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import io
-import logging
 import typing as t
 from dataclasses import dataclass, field
 
@@ -19,8 +18,6 @@
 TerminalFeatures = dict[str, list[str]]
 HookArray: TypeAlias = "dict[str, SparseArray[str]]"
 
-logger = logging.getLogger(__name__)
-
 
 @dataclass(repr=False)
 class ServerOptions(

src/libtmux/_internal/query_list.py

@@ -9,7 +9,6 @@
 
 import logging
 import re
-import traceback
 import typing as t
 from collections.abc import Callable, Iterable, Mapping, Sequence
 
@@ -105,9 +104,12 @@ def keygetter(
             elif hasattr(dct, sub_field):
                 dct = getattr(dct, sub_field)
 
-    except Exception as e:
-        traceback.print_stack()
-        logger.debug("The above error was %s", e)
+    except Exception:
+        logger.debug(
+            "key lookup failed for path: %s",
+            path,
+            exc_info=True,
+        )
         return None
 
     return dct
@@ -146,9 +148,12 @@ def parse_lookup(
             field_name = path.split(lookup, maxsplit=1)[0]
             if field_name is not None:
                 return keygetter(obj, field_name)
-    except Exception as e:
-        traceback.print_stack()
-        logger.debug("The above error was %s", e)
+    except Exception:
+        logger.debug(
+            "lookup parsing failed for path: %s",
+            path,
+            exc_info=True,
+        )
     return None
 
 

src/libtmux/common.py

@@ -270,7 +270,12 @@ def __init__(self, *args: t.Any) -> None:
             stdout, stderr = self.process.communicate()
             returncode = self.process.returncode
         except Exception:
-            logger.exception(f"Exception for {subprocess.list2cmdline(cmd)}")
+            logger.error(  # noqa: TRY400
+                "tmux subprocess failed",
+                extra={
+                    "tmux_cmd": subprocess.list2cmdline(cmd),
+                },
+            )
             raise
 
         self.returncode = returncode
@@ -288,12 +293,18 @@ def __init__(self, *args: t.Any) -> None:
         else:
             self.stdout = stdout_split
 
-        logger.debug(
-            "self.stdout for {cmd}: {stdout}".format(
-                cmd=" ".join(cmd),
-                stdout=self.stdout,
-            ),
-        )
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                "tmux command completed",
+                extra={
+                    "tmux_cmd": subprocess.list2cmdline(cmd),
+                    "tmux_exit_code": self.returncode,
+                    "tmux_stdout": self.stdout[:100],
+                    "tmux_stderr": self.stderr[:100],
+                    "tmux_stdout_len": len(self.stdout),
+                    "tmux_stderr_len": len(self.stderr),
+                },
+            )
 
 
 def get_version() -> LooseVersion:

src/libtmux/hooks.py

@@ -305,7 +305,7 @@ def show_hooks(
             elif len(parts) == 1:
                 key, val = parts[0], None
             else:
-                logger.warning(f"Error extracting hook: {item}")
+                logger.warning("failed to extract hook: %s", item)
                 continue
 
             if isinstance(val, str) and val.isdigit():

src/libtmux/neo.py

@@ -5,6 +5,7 @@
 import dataclasses
 import functools
 import logging
+import shlex
 import typing as t
 from collections.abc import Iterable
 
@@ -305,12 +306,38 @@ def fetch_objs(
 
     tmux_cmds.append(f"-F{format_string}")
 
+    cmd_str: str | None = None
+
+    if logger.isEnabledFor(logging.DEBUG):
+        cmd_str = shlex.join([str(x) for x in tmux_cmds])
+        logger.debug(
+            "tmux list queried",
+            extra={
+                "tmux_subcommand": list_cmd,
+                "tmux_cmd": cmd_str,
+            },
+        )
+
     proc = tmux_cmd(*tmux_cmds)  # output
 
     if proc.stderr:
         raise exc.LibTmuxException(proc.stderr)
 
-    return [parse_output(line) for line in proc.stdout]
+    outputs = [parse_output(line) for line in proc.stdout]
+
+    if logger.isEnabledFor(logging.DEBUG):
+        if cmd_str is None:
+            cmd_str = shlex.join([str(x) for x in tmux_cmds])
+        logger.debug(
+            "tmux list parsed",
+            extra={
+                "tmux_subcommand": list_cmd,
+                "tmux_cmd": cmd_str,
+                "tmux_stdout_len": len(proc.stdout),
+            },
+        )
+
+    return outputs
 
 
 def fetch_obj(

src/libtmux/options.py

@@ -429,7 +429,10 @@ def explode_arrays(
                     options[key][0] = val
             else:
                 options[key] = val
-            logger.exception("Error parsing options")
+            logger.warning(
+                "tmux options parse failed",
+                extra={"tmux_option_key": key},
+            )
     return options
 
 
@@ -513,7 +516,10 @@ def explode_complex(
                         term, features = item.split(":", maxsplit=1)
                         new_val[term] = features.split(":")
                     except Exception:  # NOQA: PERF203
-                        logger.exception("Error parsing options")
+                        logger.warning(
+                            "tmux options parse failed",
+                            extra={"tmux_option_key": key},
+                        )
                 options[key] = new_val
                 continue
             if isinstance(val, SparseArray) and key == "terminal-overrides":
@@ -537,7 +543,10 @@ def explode_complex(
                             elif feature:
                                 new_overrides[term][feature] = None
                     except Exception:  # NOQA: PERF203
-                        logger.exception("Error parsing options")
+                        logger.warning(
+                            "tmux options parse failed",
+                            extra={"tmux_option_key": key},
+                        )
                 options[key] = new_overrides
                 continue
             if isinstance(val, SparseArray) and key == "command-alias":
@@ -553,15 +562,21 @@ def explode_complex(
                             options[key] = {}
                         new_aliases[alias] = command
                     except Exception:  # NOQA: PERF203
-                        logger.exception("Error parsing options")
+                        logger.warning(
+                            "tmux options parse failed",
+                            extra={"tmux_option_key": key},
+                        )
                 options[key] = new_aliases
                 continue
             options[key] = val
             continue
 
         except Exception:
             options[key] = val
-            logger.exception("Error parsing options")
+            logger.warning(
+                "tmux options parse failed",
+                extra={"tmux_option_key": key},
+            )
     return options
 
 

src/libtmux/pane.py

@@ -567,6 +567,15 @@ def kill(
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
 
+        extra: dict[str, str] = {
+            "tmux_subcommand": "kill-pane",
+        }
+        if self.pane_id is not None:
+            extra["tmux_pane"] = str(self.pane_id)
+            extra["tmux_target"] = str(self.pane_id)
+        msg = "other panes killed" if all_except else "pane killed"
+        logger.info(msg, extra=extra)
+
     """
     Commands ("climber"-helpers)
 
@@ -769,7 +778,22 @@ def split(
             zip(["pane_id"], pane_output.split(FORMAT_SEPARATOR), strict=False),
         )
 
-        return self.from_pane_id(server=self.server, pane_id=pane_formatters["pane_id"])
+        pane = self.from_pane_id(server=self.server, pane_id=pane_formatters["pane_id"])
+
+        extra: dict[str, str] = {
+            "tmux_subcommand": "split-window",
+            "tmux_pane": str(pane.pane_id),
+        }
+        if self.session.session_name is not None:
+            extra["tmux_session"] = str(self.session.session_name)
+        if self.window.window_name is not None:
+            extra["tmux_window"] = str(self.window.window_name)
+        if target is not None:
+            extra["tmux_target"] = str(target)
+
+        logger.info("pane created", extra=extra)
+
+        return pane
 
     """
     Commands (helpers)