TradingAgents/docs/LOGGING_QUICK_REFERENCE.md

Logging Quick Reference Guide

Quick Start

from tradingagents.utils.logging_config import (
    get_logger,
    get_api_logger,
    get_performance_logger,
    configure_logging,
)

# Initialize (done once at startup)
configure_logging(level="INFO", console=True)

# Get loggers
logger = get_logger("tradingagents.component", component="COMPONENT")
api_logger = get_api_logger()
perf_logger = get_performance_logger()

Basic Logging

Simple Messages

logger.debug("Detailed debugging information")
logger.info("General information")
logger.warning("Warning message")
logger.error("Error occurred")
logger.critical("Critical error")

With Context

logger.info(
    "Operation completed",
    extra={
        "context": {
            "operation": "analysis",
            "duration_ms": 1234.5,
            "items_processed": 42
        }
    }
)

With Exceptions

try:
    # some operation
    pass
except Exception as e:
    logger.error(
        f"Operation failed: {e}",
        extra={"context": {"error_type": type(e).__name__}},
        exc_info=True  # Include stack trace
    )

API Call Logging

api_logger.log_call(
    provider="openai",
    model="gpt-4o-mini",
    endpoint="/v1/chat/completions",
    tokens=150,
    cost=0.0015,
    duration=1234.5,
    status="success"
)

# Get statistics
stats = api_logger.get_stats()
# Returns: {"total_calls": 3, "total_tokens": 650}

Performance Logging

import time

start = time.time()
# ... do work ...
duration_ms = (time.time() - start) * 1000

perf_logger.log_timing(
    "operation_name",
    duration_ms,
    context={"details": "value"}
)

# Get average timing
avg = perf_logger.get_average_timing("operation_name")

# Log summary
perf_logger.log_summary()

Log Levels

Level	When to Use	Example
DEBUG	Detailed diagnostic information	Variable values, loop iterations
INFO	Confirmation things are working as expected	Session start, completion
WARNING	Something unexpected but handled	Deprecated API, fallback used
ERROR	Serious problem that needs attention	Failed operation, exception
CRITICAL	System failure, app may crash	Fatal error, out of resources

Log Files

File	Contents	Level
tradingagents.log	All logs	DEBUG+
api_calls.log	API tracking	INFO+
memory.log	Memory operations	INFO+
agents.log	Agent activities	INFO+
errors.log	Errors only	ERROR+
performance.log	Performance metrics	INFO+

Configuration

Change Log Level

from tradingagents.utils.logging_config import set_log_level

set_log_level("DEBUG")  # DEBUG, INFO, WARNING, ERROR, CRITICAL

Configure at Startup

configure_logging(
    level="INFO",           # Log level
    log_dir="logs",         # Directory for log files
    console=True           # Enable/disable console output
)

Custom Component Logger

# Creates logger: tradingagents.myapp
logger = get_logger("tradingagents.myapp", component="MYAPP")

# Logs appear as:
# 2025-01-15 10:30:00 | INFO | MYAPP | Message here

Common Patterns

Session Start/End

logger.info("=" * 70)
logger.info("Session Started")
logger.info("=" * 70)

# ... work ...

logger.info("Session completed", extra={
    "context": {"duration_ms": duration, "results": count}
})

Track State Changes

logger.info(
    f"State changed: {old_state} -> {new_state}",
    extra={
        "context": {
            "old_state": old_state,
            "new_state": new_state,
            "reason": "user_action"
        }
    }
)

Tool/Function Calls

logger.info(
    f"Calling tool: {tool_name}",
    extra={
        "context": {
            "tool": tool_name,
            "args": args_dict,
            "timestamp": timestamp
        }
    }
)

Report Generation

logger.info(
    f"Report generated: {section_name}",
    extra={
        "context": {
            "section": section_name,
            "file": str(file_path),
            "content_length": len(content)
        }
    }
)

Performance Timing

import time

start = time.time()
result = expensive_operation()
duration = (time.time() - start) * 1000

perf_logger.log_timing(
    "expensive_operation",
    duration,
    context={"result_size": len(result)}
)

CLI Integration Examples

MessageBuffer Logging

class MessageBuffer:
    def __init__(self):
        self.logger = get_logger("tradingagents.cli.buffer", component="BUFFER")
    
    def add_message(self, message_type, content):
        # ... add message ...
        self.logger.debug(
            f"Message added: {message_type}",
            extra={"context": {"type": message_type}}
        )

Analysis Session

def run_analysis():
    start_time = time.time()
    cli_logger.info("Starting trading analysis session")
    
    # ... analysis work ...
    
    total_duration = (time.time() - start_time) * 1000
    cli_logger.info(
        "Analysis completed",
        extra={"context": {"duration_ms": total_duration}}
    )

Viewing Logs

Tail Live Logs

tail -f logs/tradingagents.log

View Errors Only

cat logs/errors.log

Search Logs

# Find specific ticker
grep "AAPL" logs/tradingagents.log

# Find errors
grep "ERROR" logs/tradingagents.log

# Find performance issues (>10 seconds)
grep "duration_ms.*[1-9][0-9]\{4,\}" logs/performance.log

Filter by Component

grep "| CLI |" logs/tradingagents.log
grep "| BUFFER |" logs/tradingagents.log
grep "| API |" logs/tradingagents.log

Filter by Date/Time

grep "2025-01-15 10:" logs/tradingagents.log

Troubleshooting

No Logs Appearing

1. Check logging is initialized: configure_logging(level="INFO")
2. Check log level isn't too high: set_log_level("INFO")
3. Check log directory exists: ls -la logs/

Log Files Too Large

• System uses automatic rotation (10MB default)
• Check backup count: look for .log.1, .log.2, etc.
• Increase rotation settings in logging_config.py

Missing Context in Logs

# Bad - no context
logger.info("Analysis done")

# Good - with context
logger.info(
    "Analysis done",
    extra={
        "context": {
            "ticker": "AAPL",
            "duration_ms": 1234.5
        }
    }
)

Performance Impact

• File logging is asynchronous and minimal
• DEBUG level has most overhead
• Use INFO or WARNING in production
• Disable console logging if needed: configure_logging(console=False)

Best Practices

✅ DO

• Use appropriate log levels
• Include context in extra parameter
• Log at key decision points
• Use structured context (dicts)
• Enable exc_info for exceptions
• Use consistent component names

❌ DON'T

• Log sensitive data (passwords, keys)
• Log in tight loops (use sampling)
• Use print() instead of logger
• Log without context
• Ignore log rotation limits
• Mix logging and print statements

Example: Complete Integration

from tradingagents.utils.logging_config import (
    get_logger,
    get_api_logger,
    get_performance_logger,
    configure_logging,
)
import time

# Initialize
configure_logging(level="INFO", console=True)
logger = get_logger("tradingagents.mymodule", component="MYMODULE")
api_logger = get_api_logger()
perf_logger = get_performance_logger()

def process_data(data):
    """Process data with comprehensive logging."""
    start = time.time()
    
    logger.info("Starting data processing", extra={
        "context": {"items": len(data)}
    })
    
    try:
        # Simulate API call
        api_start = time.time()
        result = call_api(data)
        api_duration = (time.time() - api_start) * 1000
        
        api_logger.log_call(
            provider="openai",
            model="gpt-4o-mini",
            endpoint="/v1/chat/completions",
            tokens=150,
            duration=api_duration,
            status="success"
        )
        
        # Process result
        processed = transform(result)
        
        # Log completion
        total_duration = (time.time() - start) * 1000
        perf_logger.log_timing("process_data", total_duration)
        
        logger.info("Processing completed", extra={
            "context": {
                "items_processed": len(processed),
                "duration_ms": total_duration
            }
        })
        
        return processed
        
    except Exception as e:
        logger.error(
            f"Processing failed: {e}",
            extra={"context": {"error_type": type(e).__name__}},
            exc_info=True
        )
        raise

# Log performance summary at end
perf_logger.log_summary()

Summary

The comprehensive logging system provides:

• 🎯 Structured, contextual logs
• 📊 Performance tracking
• 💰 API cost monitoring
• 🔍 Easy debugging
• 📁 Organized log files
• 🔄 Automatic rotation
• ⚡ Minimal overhead

For detailed documentation, see docs/CLI_LOGGING_INTEGRATION.md