Skip to content

A programming framework for agentic AI

Organize logging (#138)

Jack Gerritsec17dd16ed43
diff --git a/python/docs/src/core-concepts/logging.md b/python/docs/src/core-concepts/logging.md
index 666df440f..8c284dd88 100644
--- a/python/docs/src/core-concepts/logging.md
+++ b/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"))
+```
diff --git a/python/src/agnext/application/logging/__init__.py b/python/src/agnext/application/logging/__init__.py
index 1696599c5..3daa29146 100644
--- a/python/src/agnext/application/logging/__init__.py
+++ b/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",
]
diff --git a/python/src/agnext/application/logging/_llm_usage.py b/python/src/agnext/application/logging/_llm_usage.py
index 0677b6fc9..04eb7b423 100644
--- a/python/src/agnext/application/logging/_llm_usage.py
+++ b/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):
diff --git a/python/src/agnext/application/logging/_events.py b/python/src/agnext/application/logging/events.py
similarity index 100%
rename from python/src/agnext/application/logging/_events.py
rename to python/src/agnext/application/logging/events.py
diff --git a/python/src/agnext/components/models/_openai_client.py b/python/src/agnext/components/models/_openai_client.py
index 7d74ca4bd..6fbd417cd 100644
--- a/python/src/agnext/components/models/_openai_client.py
+++ b/python/src/agnext/components/models/_openai_client.py
@@ -32,7 +32,8 @@ from openai.types.chat import (
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,
diff --git a/python/tests/test_llm_usage.py b/python/tests/test_llm_usage.py
index 47845e99a..bee329a4f 100644
--- a/python/tests/test_llm_usage.py
+++ b/python/tests/test_llm_usage.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: