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.mdindex 666df440f..8c284dd88 100644--- a/python/docs/src/core-concepts/logging.md+++ b/python/docs/src/core-concepts/logging.md@@ -1,16 +1,97 @@# LoggingAGNext 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:```pythonimport 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__.pyindex 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, MessageKindfrom ._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.pyindex 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 LLMCallEventclass LLMUsageTracker(logging.Handler):diff --git a/python/src/agnext/application/logging/_events.py b/python/src/agnext/application/logging/events.pysimilarity index 100%rename from python/src/agnext/application/logging/_events.pyrename to python/src/agnext/application/logging/events.pydiff --git a/python/src/agnext/components/models/_openai_client.py b/python/src/agnext/components/models/_openai_client.pyindex 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, FunctionParametersfrom typing_extensions import Unpack-from ...application.logging import EVENT_LOGGER_NAME, LLMCallEvent+from ...application.logging import EVENT_LOGGER_NAME+from ...application.logging.events import LLMCallEventfrom .. import (FunctionCall,Image,diff --git a/python/tests/test_llm_usage.py b/python/tests/test_llm_usage.pyindex 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 LLMCallEventdef test_llm_usage() -> None: