# How to Configure the Logging System for Production Deployments of TradingAgents-CN

> Configure TradingAgents CN logging for production. Enable the production block set environment variables and call init logging for effective monitoring.

- Repository: [hsliuping/TradingAgents-CN](https://github.com/hsliuping/tradingagents-cn)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Enable the `[logging.production]` block in [`config/logging.toml`](https://github.com/hsliuping/TradingAgents-CN/blob/main/config/logging.toml), set environment variables like `TRADINGAGENTS_LOG_LEVEL`, and call `init_logging()` at application startup to activate structured JSON logging for production monitoring.**

TradingAgents-CN provides a hierarchical logging framework built on Python’s standard `logging` module, designed specifically for high-throughput trading environments. Configuring this system correctly for production ensures you capture audit trails, error alerts, and structured telemetry without impacting performance.

## Understanding the TradingAgents-CN Logging Architecture

The logging system centers on two core modules in the `tradingagents/utils/` directory:

- **[`logging_manager.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/logging_manager.py)** – Defines the `TradingAgentsLogger` class, `StructuredFormatter`, and handler factories. The `_load_default_config()` method parses TOML settings at line 334, while `_setup_logging()` (lines 886-907) constructs the handler hierarchy.
- **[`logging_init.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/logging_init.py)** – Provides bootstrap helpers including `init_logging()` and `get_session_logger()` for request-scoped tracking.

Runtime configuration flows from **[`config/logging.toml`](https://github.com/hsliuping/TradingAgents-CN/blob/main/config/logging.toml)** (or **[`config/logging_docker.toml`](https://github.com/hsliuping/TradingAgents-CN/blob/main/config/logging_docker.toml)** for containers) and environment variables such as `DOCKER_CONTAINER`, `TRADINGAGENTS_LOG_LEVEL`, and `TRADINGAGENTS_LOG_DIR`.

## Step 1: Enable the Production Configuration Block

Edit [`config/logging.toml`](https://github.com/hsliuping/TradingAgents-CN/blob/main/config/logging.toml) and activate the production-specific settings:

```toml
[logging.production]
enabled = true                # Activates production mode

structured_only = true        # Emits only JSON-structured logs

error_notification = true     # Hooks for alerting on severe errors

max_log_size = "100MB"        # Larger rotation for long-running services

```

When `production.enabled` is `true`, `TradingAgentsLogger._load_default_config()` (line 334 in [`logging_manager.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/logging_manager.py)) respects the `structured_only` flag and attaches only the structured JSON handler to the root logger, suppressing human-readable console output unsuitable for log aggregators.

## Step 2: Configure Production Handlers

Define handlers under `[logging.handlers.*]` to capture different log streams:

### File Handler for Audit Trails

```toml
[logging.handlers.file]
enabled = true
level = "INFO"
max_size = "100MB"
backup_count = 10
directory = "/app/logs"
filename = "tradingagents.log"

```

### Error Handler for Critical Issues

```toml
[logging.handlers.error]
enabled = true
level = "WARNING"
max_size = "100MB"
backup_count = 10
directory = "/app/logs"
filename = "error.log"

```

### Structured Handler for Log Aggregation

```toml
[logging.handlers.structured]
enabled = true
level = "INFO"
directory = "/app/logs"
filename = "tradingagents_structured.log"

```

The `StructuredFormatter` class (lines 44-69 in [`logging_manager.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/logging_manager.py)) automatically injects extra fields like `session_id` and `stock_symbol` into the JSON payload, making these logs ready for ingestion into ELK, Loki, or Splunk.

## Step 3: Set Production Environment Variables

Export these variables before starting the process:

```bash
export DOCKER_CONTAINER=true            # Required for Docker-specific paths

export TRADINGAGENTS_LOG_LEVEL=INFO       # Global fallback level

export TRADINGAGENTS_LOG_DIR=/app/logs   # Base directory for all handlers

```

The bootstrap logger in [`logging_manager.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/logging_manager.py) (line 19) reads these variables before any user code executes, ensuring the correct log level and directory are applied even if the TOML file omits specific settings.

## Step 4: Initialize the Logger in Your Application

Call `init_logging()` as the very first operation in your entry point to prevent unconfigured log messages:

```python
from tradingagents.utils.logging_init import init_logging, log_startup_info

# Must execute before importing any module that might log

init_logging()

log_startup_info()

# Application logic follows...

```

The `init_logging()` function (lines 19-34 in [`logging_init.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/logging_init.py)) invokes `setup_logging()` to build the handler hierarchy and emits a concise startup banner with environment details.

## Step 5: Use Session-Scoped Loggers for Request Tracking

For per-request or per-session logging, use the session helper to automatically inject context fields:

```python
from tradingagents.utils.logging_init import get_session_logger

def run_analysis(session_id, stock_symbol):
    logger = get_session_logger(session_id, module_name='analysis')
    logger.info(
        "Analysis started",
        extra={'stock_symbol': stock_symbol, 'analysis_type': 'fundamentals'}
    )
    # ... analysis logic ...

    logger.info("Analysis finished", extra={'stock_symbol': stock_symbol})

```

The `StructuredFormatter` captures these extra fields and outputs them as JSON properties, enabling correlation of log entries by `session_id` or `stock_symbol` in your aggregation platform.

## Docker-Specific Configuration

For containerized deployments, generate a dedicated configuration file using the provided utility:

```bash
python scripts/fix_logging_config_error.py

```

This script writes [`config/logging_docker.toml`](https://github.com/hsliuping/TradingAgents-CN/blob/main/config/logging_docker.toml) with production-optimized settings. When `DOCKER_CONTAINER=true`, the manager automatically selects this file over the default [`logging.toml`](https://github.com/hsliuping/TradingAgents-CN/blob/main/logging.toml) (see line 334 in [`logging_manager.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/logging_manager.py)).

The Docker configuration typically disables console output and writes structured logs to `/app/logs/tradingagents_structured.log` for collection by the container runtime or sidecar agents.

## Verifying Your Production Logging Setup

Run this validation script after deployment:

```python
from tradingagents.utils.logging_init import init_logging, log_startup_info

init_logging()
log_startup_info()

import logging
log = logging.getLogger('tradingagents')
log.info("Production smoke test")
log.warning("Test warning for error handler")

```

Confirm the following:

- **Structured logs**: Check `/app/logs/tradingagents_structured.log` for JSON lines containing `"message": "Production smoke test"`.
- **Error isolation**: Verify `/app/logs/error.log` contains only the warning message.
- **Startup banner**: The console or container logs should display the production mode confirmation from `log_startup_info()`.

## Summary

- **Enable production mode** by setting `enabled = true` in the `[logging.production]` section of [`config/logging.toml`](https://github.com/hsliuping/TradingAgents-CN/blob/main/config/logging.toml).
- **Use structured logging** by setting `structured_only = true` to emit JSON for log aggregation services.
- **Set environment variables** including `DOCKER_CONTAINER`, `TRADINGAGENTS_LOG_LEVEL`, and `TRADINGAGENTS_LOG_DIR` before startup.
- **Initialize early** by calling `init_logging()` before any other imports in your entry point.
- **Leverage session loggers** via `get_session_logger()` to inject request-specific context into structured output.

## Frequently Asked Questions

### What is the difference between structured and console logging in TradingAgents-CN?

**Structured logging outputs JSON-formatted lines** containing timestamp, level, message, and custom fields like `session_id` or `stock_symbol`, making them ideal for ingestion into ELK, Loki, or Splunk. **Console logging** emits human-readable text to stdout/stderr, suitable for development but generally disabled in production via `structured_only = true` to prevent duplicate or non-machine-readable streams.

### How do I change the log level without restarting the application?

TradingAgents-CN reads the `TRADINGAGENTS_LOG_LEVEL` environment variable at startup in [`logging_manager.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/logging_manager.py) (line 19). For runtime changes without restart, you must implement a signal handler or configuration reload mechanism that calls `logging.getLogger('tradingagents').setLevel(new_level)`, as the current implementation does not provide a built-in hot-reload feature for the TOML configuration.

### Where should I place the logging.toml file in a Docker container?

Mount the configuration file at **[`/app/config/logging.toml`](https://github.com/hsliuping/TradingAgents-CN/blob/main//app/config/logging.toml)** (or use the auto-generated [`/app/config/logging_docker.toml`](https://github.com/hsliuping/TradingAgents-CN/blob/main//app/config/logging_docker.toml)) inside the container. Ensure the `TRADINGAGENTS_LOG_DIR` environment variable points to a writable volume such as `/app/logs`. The [`logging_manager.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/logging_manager.py) bootstrap process searches for the TOML file relative to the working directory or uses the Docker-specific path when `DOCKER_CONTAINER=true`.

### Can I send logs directly to an external aggregation service like ELK or Loki?

While TradingAgents-CN does not include built-in network handlers, **the structured JSON output is designed for exactly this purpose**. Configure the `structured` handler to write to a file or stdout, then use a sidecar container or log shipper (such as Fluent Bit, Filebeat, or Promtail) to forward the JSON lines to your ELK, Loki, or Splunk cluster. The `StructuredFormatter` in [`logging_manager.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/logging_manager.py) (lines 44-69) ensures the JSON schema is consistent for reliable parsing.