exporter: Allow logging of serial traffic

Lab admins running shared boards have no independent record of what
is happening on the serial console.  The per-client --logfile option
captures output for the user who set it, but the lab owner has no way
to see traffic across all sessions, which hampers post-mortem when a
board ends up in a bad state and the question is which commands got
it there.

Add support for centralised serial-traffic logging on the exporter
host.  When LG_SERIAL_TRACE_DIR is set, the exporter passes ser2net's
trace-both option for each acquire, capturing every byte that flows
in either direction to a per-board, per-user file under that directory.

ser2net is started fresh on each resource acquire and stopped
on release, so each instance can include both the board (group
name) and the acquiring user in the filename: <board>-<user>.log
(e.g. bbb-okaro_sjg.log).  Repeated acquires by the same user on the
same board append to the same file.

The user identity comes from the coordinator via the new 'user' field
in ExporterSetAcquiredRequest (added in a previous commit).  The group
name is plumbed from the resource config through add_resource() into
the ResourceExport so the trace path can use the human-readable board
name instead of the device path.

trace-both-timestamp is enabled so each line is timestamped, which
makes correlating with other audit logs straightforward.

Signed-off-by: Simon Glass <sjg@chromium.org>
Co-developed-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: sjg20

doc/man/exporter.rst

@@ -77,13 +77,29 @@ for more information.
 
 ENVIRONMENT VARIABLES
 ---------------------
-The following environment variable can be used to configure labgrid-exporter.
+The following environment variables can be used to configure
+labgrid-exporter.
 
 LG_COORDINATOR
 ~~~~~~~~~~~~~~
 This variable can be used to set the default coordinator in the format
 ``HOST[:PORT]`` (instead of using the ``-x`` option).
 
+LG_SERIAL_TRACE_DIR
+~~~~~~~~~~~~~~~~~~~
+When set, the exporter records all serial-port traffic for each
+acquired resource into ``<LG_SERIAL_TRACE_DIR>/<board>-<user>.log``,
+where ``<board>`` is the resource group name and ``<user>`` is the
+acquiring user identity reported by the coordinator (in
+``host/user`` form, with ``/`` rewritten to ``_``).  Both directions
+are captured and each line is timestamped, giving the lab admin an
+independent record of every session that is not affected by
+per-client logging options.
+
+The directory is created on demand.  A fresh ser2net instance is
+started for each acquire, so repeated acquires by the same user on
+the same board append to the same file.
+
 EXAMPLES
 --------
 

doc/usage.rst

@@ -166,6 +166,43 @@ allocated before returning.
 A reservation will time out after a short time, if it is neither refreshed nor
 used by locked places.
 
+Logging Serial Traffic on the Exporter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When several developers (or CI jobs) share the same boards through a
+single coordinator, it is often useful for the lab admin to keep an
+independent record of every serial-console session.  The per-client
+``--logfile`` option only records output for the user who set it, so
+it does not help the operator answer questions like *which commands
+left this board in a bad state?* after the fact.
+
+To enable a centralised log on the exporter host, set the
+``LG_SERIAL_TRACE_DIR`` environment variable before starting
+``labgrid-exporter``:
+
+.. code-block:: bash
+
+   $ export LG_SERIAL_TRACE_DIR=/var/log/labgrid/serial
+   $ labgrid-exporter my-config.yaml
+
+For each acquire, the exporter then asks ``ser2net`` to record both
+sides of the serial connection to a file named ``<board>-<user>.log``
+under that directory, where ``<board>`` is the resource group name
+and ``<user>`` is the host/user identity reported by the coordinator
+(slashes are rewritten to underscores so the result is filesystem
+safe).  Each line is timestamped, which makes it easy to correlate a
+trace with other audit logs.
+
+Because ``ser2net`` is started fresh on each acquire and stopped on
+release, the trace covers exactly one session per acquire.  Repeated
+acquires by the same user on the same board append to the same file,
+so a long-running developer ends up with a single, continuous log per
+board.
+
+This feature complements rather than replaces the per-client
+``--logfile``: the client log is what the developer sees in their
+terminal, the exporter trace is the operator's independent record.
+
 Library
 -------
 labgrid can be used directly as a Python library, without the infrastructure

labgrid/remote/exporter.py

@@ -67,6 +67,7 @@ class ResourceExport(ResourceEntry):
     host = attr.ib(default=gethostname(), validator=attr.validators.instance_of(str))
     proxy = attr.ib(default=None)
     proxy_required = attr.ib(default=False)
+    group_name = attr.ib(default="")
     user = attr.ib(default=None, init=False)
     local = attr.ib(init=False)
     local_params = attr.ib(init=False)
@@ -231,6 +232,34 @@ def _get_params(self):
             },
         }
 
+    @staticmethod
+    def _build_trace_args(group_name, user, path):
+        """Return ser2net YAML args for trace logging, or [] if disabled
+
+        Reads LG_SERIAL_TRACE_DIR; when set, creates the directory and
+        builds a per-board, per-user file path under it, then returns
+        the YAML option pairs needed to enable trace-both for that
+        file.  The board comes from the resource's group name when
+        available, falling back to the basename of the device path so
+        the filename is still meaningful.  The user is the host/user
+        identity passed in by the coordinator (slashes are rewritten
+        to underscores so it is filesystem-safe), or ``unknown`` when
+        the coordinator did not send one.
+        """
+        trace_dir = os.environ.get("LG_SERIAL_TRACE_DIR")
+        if not trace_dir:
+            return []
+        os.makedirs(trace_dir, exist_ok=True)
+        board = group_name or os.path.basename(path)
+        user_label = (user or "unknown").replace("/", "_")
+        trace_path = os.path.join(trace_dir, f"{board}-{user_label}.log")
+        return [
+            "-Y",
+            f"    trace-both: {trace_path}",
+            "-Y",
+            "    trace-both-timestamp: true",
+        ]
+
     def _start(self, start_params):
         """Start ``ser2net`` subprocess"""
         assert self.local.avail
@@ -264,6 +293,12 @@ def _start(self, start_params):
                 "-Y",
                 "    max-connections: 10",
             ]
+            # If LG_SERIAL_TRACE_DIR is set, ask ser2net to log all
+            # serial traffic for this device.  Useful for centralised
+            # audit on the exporter host.  ser2net is started fresh
+            # on each acquire and stopped on release, so the trace
+            # file scope is one acquire session.
+            cmd += self._build_trace_args(self.group_name, self.user, start_params["path"])
         else:
             cmd = [
                 self.ser2net_bin,
@@ -1030,7 +1065,11 @@ async def add_resource(self, group_name, resource_name, cls, params):
         proxy_req = self.isolated
         if issubclass(export_cls, ResourceExport):
             res = group[resource_name] = export_cls(
-                config, host=self.hostname, proxy=getfqdn(), proxy_required=proxy_req
+                config,
+                host=self.hostname,
+                proxy=getfqdn(),
+                proxy_required=proxy_req,
+                group_name=group_name,
             )
             res.poll()
         else:

man/labgrid-exporter.1

@@ -100,11 +100,26 @@ See <\X'tty: link https://labgrid.readthedocs.io/en/latest/configuration.html#ex
 for more information.
 .SS ENVIRONMENT VARIABLES
 .sp
-The following environment variable can be used to configure labgrid\-exporter.
+The following environment variables can be used to configure
+labgrid\-exporter.
 .SS LG_COORDINATOR
 .sp
 This variable can be used to set the default coordinator in the format
 \fBHOST[:PORT]\fP (instead of using the \fB\-x\fP option).
+.SS LG_SERIAL_TRACE_DIR
+.sp
+When set, the exporter records all serial\-port traffic for each
+acquired resource into \fB<LG_SERIAL_TRACE_DIR>/<board>\-<user>.log\fP,
+where \fB<board>\fP is the resource group name and \fB<user>\fP is the
+acquiring user identity reported by the coordinator (in
+\fBhost/user\fP form, with \fB/\fP rewritten to \fB_\fP).  Both directions
+are captured and each line is timestamped, giving the lab admin an
+independent record of every session that is not affected by
+per\-client logging options.
+.sp
+The directory is created on demand.  A fresh ser2net instance is
+started for each acquire, so repeated acquires by the same user on
+the same board append to the same file.
 .SS EXAMPLES
 .sp
 Start the exporter with the configuration file \fBmy\-config.yaml\fP:

tests/test_exporter_trace.py

@@ -0,0 +1,64 @@
+"""Tests for the LG_SERIAL_TRACE_DIR feature in labgrid-exporter."""
+
+import pytest
+
+from labgrid.remote.exporter import SerialPortExport
+
+
+@pytest.fixture
+def trace_args(monkeypatch):
+    """Return a builder bound to whatever LG_SERIAL_TRACE_DIR is set."""
+
+    def _build(group_name="bbb", user="okaro/sjg", path="/dev/ttyUSB0"):
+        return SerialPortExport._build_trace_args(group_name, user, path)
+
+    return _build
+
+
+def test_returns_empty_when_env_unset(trace_args, monkeypatch):
+    monkeypatch.delenv("LG_SERIAL_TRACE_DIR", raising=False)
+    assert trace_args() == []
+
+
+def test_builds_yaml_args(trace_args, monkeypatch, tmp_path):
+    monkeypatch.setenv("LG_SERIAL_TRACE_DIR", str(tmp_path))
+    args = trace_args(group_name="bbb", user="okaro/sjg")
+    assert args == [
+        "-Y",
+        f"    trace-both: {tmp_path}/bbb-okaro_sjg.log",
+        "-Y",
+        "    trace-both-timestamp: true",
+    ]
+
+
+def test_creates_missing_directory(trace_args, monkeypatch, tmp_path):
+    target = tmp_path / "newdir"
+    assert not target.exists()
+    monkeypatch.setenv("LG_SERIAL_TRACE_DIR", str(target))
+    trace_args()
+    assert target.is_dir()
+
+
+def test_user_slashes_rewritten(trace_args, monkeypatch, tmp_path):
+    monkeypatch.setenv("LG_SERIAL_TRACE_DIR", str(tmp_path))
+    args = trace_args(user="myhost/alice")
+    assert args[1] == f"    trace-both: {tmp_path}/bbb-myhost_alice.log"
+
+
+def test_unknown_user_when_none(trace_args, monkeypatch, tmp_path):
+    monkeypatch.setenv("LG_SERIAL_TRACE_DIR", str(tmp_path))
+    args = trace_args(user=None)
+    assert args[1] == f"    trace-both: {tmp_path}/bbb-unknown.log"
+
+
+def test_falls_back_to_path_basename(trace_args, monkeypatch, tmp_path):
+    monkeypatch.setenv("LG_SERIAL_TRACE_DIR", str(tmp_path))
+    args = trace_args(group_name="", path="/dev/ttyUSB7")
+    assert args[1] == f"    trace-both: {tmp_path}/ttyUSB7-okaro_sjg.log"
+
+
+def test_existing_dir_is_reused(trace_args, monkeypatch, tmp_path):
+    """If the dir already exists, makedirs(exist_ok=True) must not fail."""
+    monkeypatch.setenv("LG_SERIAL_TRACE_DIR", str(tmp_path))
+    trace_args()
+    trace_args()  # second call would error if exist_ok wasn't honoured