Logging Configuration

Control PraisonAI log output from the CLI or your own scripts

from praisonaiagents import Agent

agent = Agent(
    name="logged-agent",
    instructions="Process tasks with full logging enabled.",
    verbose=True,
)
agent.start("Run this task with detailed logging.")

Control how PraisonAI logs run-time information from the CLI or your own Python scripts.

The user runs an agent with verbose logging; PraisonAI emits structured lines to stderr for debugging.

Quick Start

1. CLI Users

   Set LOGLEVEL=INFO (or DEBUG) before running PraisonAI commands to see more output.

   export LOGLEVEL=INFO
   praisonai agents.yaml
   
2. Script Users

   Call configure_cli_logging("INFO") once at app start, or wire your own logging.basicConfig().

   from praisonai import PraisonAI
   from praisonai._logging import configure_cli_logging
   
   configure_cli_logging("INFO")  # opt in to root-logger setup
   PraisonAI(agent_file="agents.yaml").run()
   

---

How It Works

Import Type	Root Logger Configuration	Default Level
CLI (praisonai command)	✅ Automatic via configure_cli_logging()	WARNING
Library (from praisonai import)	❌ No automatic configuration	N/A

As of PraisonAI v?.? (PR #1867), importing praisonai.inc.models (and any other internal module) no longer calls logging.basicConfig(). Library users keep full control of their own logging configuration; only configure_cli_logging() and LOGLEVEL= (via the CLI) touch the root logger.

---

Configuration Options

Option	Type	Default	Description
LOGLEVEL env var	str	WARNING	Read by configure_cli_logging(). Accepts standard Python levels.
configure_cli_logging(level)	str | int | None	None (uses LOGLEVEL or WARNING)	Idempotent; only the first call configures the root logger.
get_logger(name)	str | None	None (returns praisonai)	Returns a namespaced praisonai.<name> logger; never mutates root.

---

Common Patterns

Quieting PraisonAI in a Larger App

import logging
from praisonai import PraisonAI

# Set only the praisonai logger to WARNING
logging.getLogger("praisonai").setLevel(logging.WARNING)

# Your app's logging remains untouched
praisonai = PraisonAI(agent_file="agents.yaml")
praisonai.run()

Routing PraisonAI Logs to a File

import logging
from praisonai import PraisonAI

# Create file handler for praisonai logs only
handler = logging.FileHandler("praisonai.log")
handler.setFormatter(logging.Formatter("%(asctime)s - %(levelname)s - %(message)s"))

# Attach to praisonai logger tree
praisonai_logger = logging.getLogger("praisonai")
praisonai_logger.addHandler(handler)
praisonai_logger.setLevel(logging.INFO)

praisonai = PraisonAI(agent_file="agents.yaml")
praisonai.run()

One-off CLI Debugging

# Debug a specific run
LOGLEVEL=DEBUG praisonai agents.yaml

# Back to quiet mode
praisonai agents.yaml

---

Migration note for users upgrading past PR #1561:

Before this release, importing praisonai silently called logging.basicConfig and defaulted LOGLEVEL to INFO. From this release onward, only the CLI configures the root logger, and the default level is WARNING. If you embed PraisonAI in your own script and want the previous behaviour, call from praisonai._logging import configure_cli_logging; configure_cli_logging("INFO") at startup.

---

Best Practices

Use namespaced loggers in library code

Always use get_logger("module") instead of the root logger when writing library code.

from praisonai._logging import get_logger

logger = get_logger("mymodule")  # Creates praisonai.mymodule logger
logger.info("This won't interfere with the user's logging")

Do not call basicConfig from libraries

Libraries should never call logging.basicConfig() as it mutates global state. Let applications control their logging setup.

# ❌ Bad - mutates global logger
import logging
logging.basicConfig(level=logging.INFO)

# ✅ Good - use namespaced logger
from praisonai._logging import get_logger
logger = get_logger("mylibrary")

Prefer LOGLEVEL for one-shot debugging

Use the environment variable for temporary debugging instead of changing code.

# Quick debug session
LOGLEVEL=DEBUG praisonai agents.yaml

# Production run
praisonai agents.yaml

Attach handlers to praisonai not root

When customizing PraisonAI logging, attach handlers to the praisonai logger tree rather than the root logger.

import logging

# ✅ Good - only affects praisonai
praisonai_logger = logging.getLogger("praisonai")
praisonai_logger.addHandler(my_handler)

# ❌ Bad - affects all logging
root_logger = logging.getLogger()
root_logger.addHandler(my_handler)

---

Related

Thread Safety

Thread-safe agent state and wrapper-layer improvements

Debugging

Best practices for troubleshooting PraisonAI issues