Tweaks

Remove bind_logger now that we report file path and line
Update Tracer for new logging

Author: GDYendell

docs/tutorials/static-drivers.md

@@ -409,7 +409,8 @@ DEMO:R1:Enabled_RBV            Off
 
 FastCS has convenient logging support to provide status and metrics from the
 application. To enable logging from the core framework call `configure_logging` with no
-arguments (the default logging level is INFO). To log messages from a driver, import the singleton `logger` directly.
+arguments (the default logging level is INFO). To log messages from a driver, import the
+singleton `logger` directly.
 
 Create a module-level logger to log status of the application start up. Create a class
 logger for `TemperatureControllerAttributeIO` to log the commands it sends.
@@ -431,7 +432,7 @@ Try setting a PV and check the console for the log message it prints.
 
 A similar log message could be added for the update method of the IO, but this would be
 very verbose. For this use case FastCS provides the `Tracer` class, which is inherited
-by `AttributeIO`, among other core FastCS classes. This adds a  enables logging `TRACE`
+by `AttributeIO`, among other core FastCS classes. This enables the logging of `TRACE`
 level log messages that are disabled by default, but can be enabled at runtime.
 
 Update the `send` method of the IO to log a message showing the query that was sent and
@@ -449,7 +450,8 @@ visible.
 ::::
 
 Enable tracing on the `power` attribute by calling `enable_tracing` and then enable a
-ramp so that the value updates. Check the console to see the messages.  Call `disable_tracing` to disable the log messages for `power.
+ramp so that the value updates. Check the console to see the messages.  Call
+`disable_tracing` to disable the log messages for `power`.
 
 ```
 In [1]: controller.power.enable_tracing()
@@ -469,7 +471,7 @@ In [1]: controller.power.enable_tracing()
 In [2]: controller.power.disable_tracing()
 ```
 
-These log messages includes other trace loggers that log messages with `power` as the
+These log messages include other trace loggers that log messages with `power` as the
 `topic`, so they also appear automatically, so the log messages show changes to the
 attribute throughout the stack: the query to the device and its response, the value the
 attribute is set to, and the value that the PV in the EPICS CA transport is set to.
@@ -481,7 +483,7 @@ The `Tracer` can also be used as a module-level instance for use in free functio
 ```python
 from fastcs.tracer import Tracer
 
-tracer = Tracer(__name__)
+tracer = Tracer()
 
 def handle_attribute(attr):
     tracer.log_event("Handling attribute", topic=attr)

src/fastcs/control_system.py

@@ -13,7 +13,7 @@
 from fastcs.tracer import Tracer
 from fastcs.transports import ControllerAPI, Transport
 
-tracer = Tracer(name=__name__)
+tracer = Tracer()
 
 
 class FastCS:

src/fastcs/logging/__init__.py

@@ -21,33 +21,30 @@
 and metrics in graylog.
 
 It is best to keep the message short and use extra fields for additional information for
-messages to be formatted nicely in the console. To add kwargs to format the message
-without them appearing as extra fields, prepend the key with ``_``.
+messages to be formatted nicely in the console.
 
 .. code-block:: python
 
     from fastcs.logging import logger
 
     logger.info("PV put: {pv} = {value}", pv=pv, value=value)
 
-By default messages will be logged with the name ``fastcs``. Within different modules
-and classes it can be useful to override this name. This can be done with the ``bind``
-method. To create a module logger with its name
+To add kwargs to format the message without them appearing as extra fields, prepend the
+key with ``_``.
+
+By default messages will be logged with the name ``fastcs``. Within a driver it may be
+useful to set a distinct logger name. This can be done with the ``bind`` method. To
+create a new logger with the the name of the driver, use the following in a logging.py
+module and use it throughout the package instead of the fastcs logger:
 
 .. code-block:: python
 
     from fastcs.logging import logger as _logger
 
-    logger = _logger.bind(logger_name=__name__)
-
-or to create a class logger with its name
-
-.. code-block:: python
-
-    self.logger = _logger.bind(logger_name=__class__.__name__)
+    logger = _logger.bind(logger_name="fastcs-driver")
 
 As standard ``loguru`` supports ``trace`` level monitoring, but it should not be used in
-fastcs. Instead there is a ``Tracer`` class for verbose logging with fine-grained
+fastcs. Instead there is a `Tracer` class for verbose logging with fine-grained
 controls that can be enabled by the user at runtime.
 
 Use ``configure_logging`` to re-configure the logger at runtime. For more advanced

src/fastcs/logging/_logging.py

@@ -90,6 +90,7 @@ def format_record(record) -> str:
     time = f"{_time}{_timezone}"
 
     name = record["extra"].pop("logger_name", None) or record["name"]
+    message_pad = max(0, 100 - len(name))
 
     sep = "<white>,</white> "
     if "extra" in record:
@@ -108,9 +109,8 @@ def format_record(record) -> str:
 
     return f"""\
 <level>[{time} {record["level"].name[0]}]</level> \
-{record["message"]:<80} \
-[{record["file"].path}:{record["line"]}] \
-<green>[{name}]</green> \
+{record["message"]:<{message_pad}} \
+<green>{name} [{record["file"].path}:{record["line"]}]</green> \
 {extras}
 {{exception}}\
 """

src/fastcs/tracer.py

@@ -1,7 +1,10 @@
 from collections import defaultdict
 from typing import Any
 
-from fastcs.logging import logger
+from fastcs.logging import logger as _logger
+
+# Pass depth so that reported line number in log messages is `log_event` call site
+logger = _logger.opt(depth=1)
 
 
 class Tracer:
@@ -16,9 +19,9 @@ class Tracer:
     object, or from another ``Tracer`` that uses the object as the ``topic``, will be
     logged.
 
-    Note: The global logger level must be set to ``TRACE`` for the messages to be logged
+    Note: The logger level must be set to ``TRACE`` for the messages to be logged
 
-    Example usage:
+    Example usage in interactive shell:
     .. code-block:: python
 
         controller.ramp_rate.enable_tracing()
@@ -27,23 +30,20 @@ class Tracer:
         controller.connection.add_tracing_filter("query", "V?")
         controller.connection.remove_tracing_filter("query", "V?")
         controller.connection.disable_tracing()
-
-    :param name: The name of the logger. Attached to log messages as ``logger_name``.
-
     """
 
-    def __init__(self, name: str | None = None):
+    def __init__(self):
         self.__tracing_enabled: bool = False
         self.__tracing_filters: dict[str, list[Any]] = defaultdict(list)
-        self.__logger_name = name if name is not None else self.__class__.__name__
 
     def log_event(self, event: str, topic: "Tracer | None" = None, *args, **kwargs):
         """Log an event only if tracing is enabled and the filter matches
 
-        :param event: A message describing the event
-        :param topic: Another `Tracer` related to this event to enable it to be logged
-        :param args: Positional arguments for underlying logger
-        :param kwargs: Keyword arguments for underlying logger
+        Args:
+            event: A message describing the event
+            topic: Another `Tracer` related to this event to enable it to be logged
+            args: Positional arguments for underlying logger
+            kwargs: Keyword arguments for underlying logger
 
         """
         if self.__tracing_enabled or (topic is not None and topic.__tracing_enabled):  # noqa: SLF001
@@ -54,7 +54,7 @@ def log_event(self, event: str, topic: "Tracer | None" = None, *args, **kwargs):
                 else:
                     return
 
-            logger.trace(event, *args, logger_name=self.__logger_name, **kwargs)
+            logger.trace(event, *args, **kwargs)
 
     def enable_tracing(self):
         """Enable trace logging for this object"""

src/fastcs/transports/controller_api.py

@@ -5,11 +5,8 @@
 
 from fastcs.attributes import Attribute, AttributeIORef, AttrR
 from fastcs.methods import Command, Scan, ScanCallback
-from fastcs.tracer import Tracer
 from fastcs.util import ONCE
 
-tracer = Tracer(name=__name__)
-
 
 @dataclass
 class ControllerAPI:

src/fastcs/transports/epics/ca/ioc.py

@@ -27,7 +27,7 @@
 EPICS_MAX_NAME_LENGTH = 60
 
 
-tracer = Tracer(name=__name__)
+tracer = Tracer()
 
 
 class EpicsCAIOC:

src/fastcs/transports/epics/pva/_pv_handlers.py

@@ -21,7 +21,7 @@
     p4p_timestamp_now,
 )
 
-tracer = Tracer(name=__name__)
+tracer = Tracer()
 
 
 class WritePvHandler: