Organize logging (#138)

Author: jackgerrits

python/docs/src/core-concepts/logging.md

@@ -1,16 +1,97 @@
 # Logging
 
 AGNext uses Python's built-in [`logging`](https://docs.python.org/3/library/logging.html) module.
-The logger names are:
 
-- `agnext` for the main logger.
+There are two kinds of logging:
 
-Example of how to use the logger:
+- **Trace logging**: This is used for debugging and is human readable messages to indicate what is going on. This is intended for a developer to understand what is happening in the code. The content and format of these logs should not be depended on by other systems.
+    - Name: {py:attr}`~agnext.application.logging.TRACE_LOGGER_NAME`.
+- **Structured logging**: This logger emits structured events that can be consumed by other systems. The content and format of these logs should be can be depended on by other systems.
+    - Name: {py:attr}`~agnext.application.logging.EVENT_LOGGER_NAME`.
+    - See the module {py:mod}`agnext.application.logging.events` to see the available events.
+- {py:attr}`~agnext.application.logging.ROOT_LOGGER` can be used to enable or disable all logs at the same time.
+
+## Enabling logging output
+
+To enable trace logging, you can use the following code:
 
 ```python
 import logging
 
+from agnext.application.logging import TRACE_LOGGER_NAME
+
 logging.basicConfig(level=logging.WARNING)
-logger = logging.getLogger('agnext')
+logger = logging.getLogger(TRACE_LOGGER_NAME)
 logger.setLevel(logging.DEBUG)
 ```
+
+### Structured logging
+
+Structured logging allows you to write handling logic that deals with the actual events including all fields rather than just a formatted string.
+
+For example, if you had defined this custom event and were emitting it. Then you could write the following handler to receive it.
+
+```python
+import logging
+from dataclasses import dataclass
+
+@dataclass
+class MyEvent:
+    timestamp: str
+    message: str
+
+class MyHandler(logging.Handler):
+    def __init__(self) -> None:
+        super().__init__()
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            # Use the StructuredMessage if the message is an instance of it
+            if isinstance(record.msg, MyEvent):
+                print(f"Timestamp: {record.msg.timestamp}, Message: {record.msg.message}")
+        except Exception:
+            self.handleError(record)
+```
+
+And this is how you could use it:
+
+```python
+logger = logging.getLogger(EVENT_LOGGER_NAME)
+logger.setLevel(logging.INFO)
+my_handler = MyHandler()
+logger.handlers = [my_handler]
+```
+
+
+## Emitting logs
+
+These two names are the root loggers for these types. Code that emits logs should use a child logger of these loggers. For example, if you are writing a module `my_module` and you want to emit trace logs, you should use the logger named:
+
+```python
+import logging
+
+from agnext.application.logging import TRACE_LOGGER_NAME
+logger = logging.getLogger(f"{TRACE_LOGGER_NAME}.my_module")
+```
+
+### Emitting structured logs
+
+If your event looks like:
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class MyEvent:
+    timestamp: str
+    message: str
+```
+
+Then it could be emitted in code like this:
+
+```python
+from agnext.application.logging import EVENT_LOGGER_NAME
+
+logger = logging.getLogger(EVENT_LOGGER_NAME + ".my_module")
+logger.info(MyEvent("timestamp", "message"))
+```

python/src/agnext/application/logging/__init__.py

@@ -1,13 +1,18 @@
-from ._events import DeliveryStage, LLMCallEvent, MessageEvent, MessageKind
 from ._llm_usage import LLMUsageTracker
 
+ROOT_LOGGER_NAME = "agnext"
+"""str: Logger name used for structured event logging"""
+
 EVENT_LOGGER_NAME = "agnext.events"
+"""str: Logger name used for structured event logging"""
+
+
+TRACE_LOGGER_NAME = "agnext.trace"
+"""str: Logger name used for developer intended trace logging. The content and format of this log should not be depended upon."""
 
 __all__ = [
-    "LLMCallEvent",
+    "ROOT_LOGGER_NAME",
     "EVENT_LOGGER_NAME",
+    "TRACE_LOGGER_NAME",
     "LLMUsageTracker",
-    "MessageEvent",
-    "MessageKind",
-    "DeliveryStage",
 ]

python/src/agnext/application/logging/_llm_usage.py

@@ -1,6 +1,6 @@
 import logging
 
-from ._events import LLMCallEvent
+from .events import LLMCallEvent
 
 
 class LLMUsageTracker(logging.Handler):

python/src/agnext/application/logging/_events.py renamed to python/src/agnext/application/logging/events.py

@@ -32,7 +32,8 @@
 from openai.types.shared_params import FunctionDefinition, FunctionParameters
 from typing_extensions import Unpack
 
-from ...application.logging import EVENT_LOGGER_NAME, LLMCallEvent
+from ...application.logging import EVENT_LOGGER_NAME
+from ...application.logging.events import LLMCallEvent
 from .. import (
     FunctionCall,
     Image,

python/src/agnext/components/models/_openai_client.py

@@ -1,6 +1,7 @@
 import logging
 
-from agnext.application.logging import EVENT_LOGGER_NAME, LLMCallEvent, LLMUsageTracker
+from agnext.application.logging import EVENT_LOGGER_NAME, LLMUsageTracker
+from agnext.application.logging.events import LLMCallEvent
 
 
 def test_llm_usage() -> None: