feat: Route event printing through logging

[priyansh4320]

Why are these changes needed?

All the event print() calls now use a logger instead of raw print, so you can control AG2’s output (format, handlers, filters, mute) with normal logging config.

Related issue number

#2175

Checks

• I've included any doc changes needed for https://docs.ag2.ai/. See https://docs.ag2.ai/latest/docs/contributor-guide/documentation/ to build and test documentation locally.
• I've added tests (if relevant) corresponding to the changes introduced in this PR.
• I've made sure all auto checks have passed.

[joggrbot]

📝 Documentation Analysis

All docs are up to date! 🎉

---

✅ Latest commit analyzed: 20cc229 | Powered by Joggr

[priyansh4320]

@claude review this pull

[claude]

Claude finished @priyansh4320's task —— View job

---

Code Review for PR #2217

I've completed a thorough review of this PR that converts event printing from raw print() calls to use the logging module. Overall, this is a well-implemented feature that provides much-needed control over AG2's output formatting and handling. Here's my detailed analysis:

---

✅ Strengths

1. Clean Architecture: The implementation follows a good separation of concerns:

   • event_print() function in logger_utils.py provides the logging interface
   • resolve_print_callable() acts as the resolver that defaults to event_print
   • All event classes consistently use this pattern

2. Backward Compatibility: The changes maintain backward compatibility by allowing custom print functions to be passed while defaulting to the new logger-based approach.

3. Comprehensive Test Coverage: The PR includes good test coverage (94.94%) with tests for:

   • Custom logger and handler behavior
   • End/flush parameter handling
   • Integration with the event system

4. Consistent Implementation: All event classes (agent_events.py, client_events.py, print_event.py) were updated consistently, replacing f = f or print with f = resolve_print_callable(f).

---

⚠️ Issues and Concerns

1. Missing Coverage in logger_utils.py (4 lines)

According to codecov, there are 4 lines missing coverage in autogen/logger/logger_utils.py:67-82. Looking at the code:

Lines 71-81 (EventStreamHandler.emit):

def emit(self, record: logging.LogRecord) -> None:
    try:
        msg = self.format(record)
        end = getattr(record, _END_KEY, "\n")
        stream = self.stream
        stream.write(msg)
        stream.write(end)
        if getattr(record, _FLUSH_KEY, True):
            self.flush()
    except Exception:
        self.handleError(record)

Missing coverage:

• Line 80: The exception handler (except Exception:)
• Line 81: self.handleError(record)

Recommendation: While testing error paths can be challenging, consider adding a test that triggers the exception handler to improve coverage and ensure error handling works correctly.

2. Type Annotation Issue in EventStreamHandler.__init__

Location: autogen/logger/logger_utils.py:68

def __init__(self, stream=None):  # type: ignore [no-untyped-def]

Issue: Using # type: ignore to suppress type checking warnings is a code smell. The parameter should be properly typed.

Recommendation:

def __init__(self, stream: Any = None) -> None:

Or better yet, use the proper type from typing:

from typing import TextIO

def __init__(self, stream: TextIO | None = None) -> None:

3. Logger Configuration Concerns

Location: autogen/logger/logger_utils.py:84-93

def get_event_logger() -> logging.Logger:
    logger = logging.getLogger(_EVENT_LOGGER_NAME)
    if not logger.handlers:
        handler = EventStreamHandler(sys.stdout)  # type: ignore [no-untyped-call]
        handler.setFormatter(logging.Formatter("%(message)s"))
        logger.addHandler(handler)
        if logger.level == logging.NOTSET:
            logger.setLevel(logging.INFO)
    logger.propagate = False
    return logger

Concerns:

a. Global State Mutation: This function modifies global logger state on every call by setting propagate = False, even when handlers already exist. This could be unexpected.

Recommendation: Only set propagate = False when configuring a new logger:

def get_event_logger() -> logging.Logger:
    logger = logging.getLogger(_EVENT_LOGGER_NAME)
    if not logger.handlers:
        handler = EventStreamHandler(sys.stdout)
        handler.setFormatter(logging.Formatter("%(message)s"))
        logger.addHandler(handler)
        if logger.level == logging.NOTSET:
            logger.setLevel(logging.INFO)
        logger.propagate = False  # Only set once during initialization
    return logger

b. Handler Accumulation Risk: If a user calls get_event_logger() multiple times after manually clearing handlers, new handlers will be added each time. While this is standard logging behavior, it could lead to duplicate output.

c. Line 87 Type Ignore: Another # type: ignore [no-untyped-call] that should be addressed by properly typing the EventStreamHandler.__init__ method.

4. Documentation Gap

The PR description mentions this allows users to "control AG2's output (format, handlers, filters, mute) with normal logging config" but there's no documentation showing users how to do this.

Recommendation: Add documentation (either in docstrings or a separate doc file) showing:

• How to get and configure the event logger
• Examples of customizing format, handlers, or log level
• How to mute event output entirely
• Migration guide for users who might be relying on capturing stdout

Example usage that should be documented:

import logging
from autogen.logger.logger_utils import get_event_logger

# Mute all event output
get_event_logger().setLevel(logging.CRITICAL)

# Custom format
logger = get_event_logger()
for handler in logger.handlers:
    handler.setFormatter(logging.Formatter('[%(levelname)s] %(message)s'))

# Redirect to file
logger = get_event_logger()
logger.handlers.clear()
logger.addHandler(logging.FileHandler('events.log'))

5. Test File Changes

Location: test/io/test_console.py

The test mocking was correctly updated from builtins.print to autogen.events.base_event.event_print, which is good. However, the tests are now mocking the new implementation rather than testing integration with it. Consider adding integration tests that verify the actual logging behavior.

---

🔍 Minor Observations

1. String Formatting in _stringify (logger_utils.py:96-97):

   def _stringify(objects: Iterable[Any], sep: str) -> str:
       return sep.join(str(obj) for obj in objects)

   This is clean and efficient. Good implementation.

2. Custom Attributes Pattern: Using _END_KEY and _FLUSH_KEY as custom LogRecord attributes is a good pattern that preserves the end and flush parameters through the logging system.

3. Logger Name: "ag2.event.processor" is a good hierarchical name that allows users to configure parent loggers if needed.

---

📋 Summary

Approval Status: ✅ Approve with minor improvements recommended

This PR successfully achieves its goal of routing event printing through the logging module. The implementation is solid and maintains backward compatibility. The main concerns are:

1. Critical: Add documentation for users on how to configure event logging
2. Important: Fix type annotations to remove # type: ignore comments
3. Nice to have: Improve test coverage for error paths
4. Nice to have: Move logger.propagate = False inside the initialization block

The existing tests pass, CI is green, and the code quality is good. Once the documentation is added and type annotations are fixed, this will be ready to merge.

---

🎯 Recommendations for Follow-up

After merging, consider:

• Adding examples to the official docs at https://docs.ag2.ai/
• Creating a migration guide for users who capture stdout
• Adding structured logging capabilities (e.g., JSON formatting for production use)

---

Great work @priyansh4320! This is a valuable improvement to AG2's logging capabilities.

[marklysze]

@priyansh4320 thanks for doing this, looking good and @jsun-m has confirmed. Can you please resolve conflicts and we'll push forward with it.

[priyansh4320]

@marklysze thanks for the review. fixed the conflict and added a small setup documentation.

[marklysze]

Top notch work, thanks @priyansh4320!

[codecov]

Codecov Report

❌ Patch coverage is 94.93671% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
autogen/logger/logger_utils.py	89.47%	2 Missing and 2 partials ⚠️

Files with missing lines	Coverage Δ
autogen/events/agent_events.py	97.21% <100.00%> (-0.43%)	⬇️
autogen/events/base_event.py	90.19% <100.00%> (+0.61%)	⬆️
autogen/events/client_events.py	90.32% <100.00%> (ø)
autogen/events/print_event.py	75.00% <100.00%> (ø)
autogen/logger/logger_utils.py	93.10% <89.47%> (-6.90%)	⬇️

... and 19 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.