libtmux(fix[logging]): fix log formatting, structured context, and diagnostics

why: Bring logging calls into compliance with AGENTS.md logging standards.
what:
- common.py: Replace f-string and .format() in log calls with lazy formatting
  and structured extra; guard DEBUG with isEnabledFor; use logger.error()
  instead of logger.exception() for catch-log-reraise
- server.py: Add structured extra to session lifecycle log calls, fix message
  style to lowercase past tense
- hooks.py: Replace f-string with lazy %s formatting
- query_list.py: Replace traceback.print_stack() with logger.debug() using
  stack_info=True; remove traceback import
- pytest_plugin.py: Add structured extra to test session cleanup log call
- options.py: Change logger.exception() to logger.warning(exc_info=True)
  for recoverable parse failures; add structured extra with tmux_option_key

Author: tony

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,13 @@ 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,
+            stack_info=True,
+        )
         return None
 
     return dct
@@ -146,9 +149,13 @@ 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,
+            stack_info=True,
+        )
     return None
 
 

src/libtmux/common.py

@@ -270,7 +270,13 @@ 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(
+                "tmux subprocess failed",
+                exc_info=True,
+                extra={
+                    "tmux_cmd": subprocess.list2cmdline(cmd),
+                },
+            )
             raise
 
         self.returncode = returncode
@@ -288,12 +294,17 @@ 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),
+                },
+            )
 
 
 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/options.py

@@ -429,7 +429,11 @@ def explode_arrays(
                     options[key][0] = val
             else:
                 options[key] = val
-            logger.exception("Error parsing options")
+            logger.warning(
+                "tmux options parse failed",
+                exc_info=True,
+                extra={"tmux_option_key": key},
+            )
     return options
 
 
@@ -513,7 +517,11 @@ 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",
+                            exc_info=True,
+                            extra={"tmux_option_key": key},
+                        )
                 options[key] = new_val
                 continue
             if isinstance(val, SparseArray) and key == "terminal-overrides":
@@ -537,7 +545,11 @@ 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",
+                            exc_info=True,
+                            extra={"tmux_option_key": key},
+                        )
                 options[key] = new_overrides
                 continue
             if isinstance(val, SparseArray) and key == "command-alias":
@@ -553,15 +565,23 @@ def explode_complex(
                             options[key] = {}
                         new_aliases[alias] = command
                     except Exception:  # NOQA: PERF203
-                        logger.exception("Error parsing options")
+                        logger.warning(
+                            "tmux options parse failed",
+                            exc_info=True,
+                            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",
+                exc_info=True,
+                extra={"tmux_option_key": key},
+            )
     return options
 
 

src/libtmux/pytest_plugin.py

@@ -251,7 +251,13 @@ def session(
         server.switch_client(target_session=session_id)
 
     for old_test_session in old_test_sessions:
-        logger.debug("Old test test session %s found. Killing it.", old_test_session)
+        logger.debug(
+            "old test session found, killing",
+            extra={
+                "tmux_session": old_test_session,
+                "tmux_subcommand": "kill-session",
+            },
+        )
         server.kill_session(old_test_session)
     assert session.session_name == TEST_SESSION_NAME
     assert TEST_SESSION_NAME != "tmuxp"

src/libtmux/server.py

@@ -525,14 +525,26 @@ def new_session(
             if self.has_session(session_name):
                 if kill_session:
                     self.cmd("kill-session", target=session_name)
-                    logger.info("session %s exists. killed it.", session_name)
+                    logger.info(
+                        "existing session killed",
+                        extra={
+                            "tmux_session": session_name,
+                            "tmux_subcommand": "kill-session",
+                        },
+                    )
                 else:
                     msg = f"Session named {session_name} exists"
                     raise exc.TmuxSessionExists(
                         msg,
                     )
 
-        logger.debug("creating session %s", session_name)
+        logger.debug(
+            "creating session",
+            extra={
+                "tmux_session": session_name,
+                "tmux_subcommand": "new-session",
+            },
+        )
 
         env = os.environ.get("TMUX")