Logging Configuration

from praisonaiagents import Agent

agent = Agent(
    name="logged-agent",
    instructions="Process tasks with full logging enabled.",
    output="verbose",
)
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

CLI Users

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

export LOGLEVEL=INFO
praisonai agents.yaml

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.

Import-time behaviour (PR #5219)

import praisonaiagents no longer overwrites host environment variables or silences the host’s asyncio logger. Reference: PraisonAI PR #5219, fixes #5162. For the full fork-safety story, see Python Import Safety & Fork Behaviour.

Environment variables: setdefault, not overwrite

praisonaiagents._logging._configure_environment() now uses os.environ.setdefault(key, value) instead of an unconditional assignment. A value the host exported before launch is preserved and no longer leaks a different value into any subprocess spawned afterwards.

# The host sets LITELLM_LOG before launching your script.
export LITELLM_LOG=DEBUG
python my_script.py     # imports praisonaiagents

import os
import praisonaiagents  # calls _configure_environment() at import

# The host's DEBUG value is kept — setdefault does not overwrite it.
assert os.environ["LITELLM_LOG"] == "DEBUG"

When the host has not set a value, the SDK still fills these in (verified against _logging._configure_environment at head):

Variable	Default set when unset
`LITELLM_TELEMETRY`	`False`
`LITELLM_DROP_PARAMS`	`True`
`LITELLM_LOG`	`ERROR`
`LITELLM_DEBUG`	`False`
`LITELLM_SUPPRESS_DEBUG_INFO`	`True`
`LITELLM_VERBOSE`	`False`
`LITELLM_SET_VERBOSE`	`False`
`HTTPX_DISABLE_WARNINGS`	`True`
`HTTPX_LOG_LEVEL`	`ERROR`
`PYDANTIC_WARNINGS_ENABLED`	`False`

asyncio logger is no longer suppressed

"asyncio" has been removed from the SDK’s noisy-logger list, so import praisonaiagents no longer forces logging.getLogger("asyncio") to CRITICAL or clears its handlers. Host application asyncio errors — Task exception was never retrieved, coroutine-scheduling failures, and similar — surface again as your own logging config intends. If you relied on the old import-time behaviour to hide those messages, set the level yourself in your own code:

import logging
import praisonaiagents  # no longer touches the asyncio logger

# Opt back into suppression explicitly if you want it.
logging.getLogger("asyncio").setLevel(logging.CRITICAL)

PR #5219 intentionally kept two other import-time behaviours — do not assume they were fixed:

The root logger is still reconfigured via logging.basicConfig(force=True). If your host configured logging before importing PraisonAI, its handler is still closed and replaced.
warnings.warn / warnings.warn_explicit remain monkeypatched to suppress a hardcoded pattern list plus UserWarnings mentioning “pydantic”.

See Python Import Safety → What is still not safe on import for the workarounds.

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)

Import Safety (Python)

Fork-safe imports, setdefault env vars, and untouched asyncio logging

Thread Safety

Thread-safe agent state and wrapper-layer improvements

Debugging

Best practices for troubleshooting PraisonAI issues

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Logging Configuration

Quick Start

How It Works

Configuration Options

Common Patterns

Quieting PraisonAI in a Larger App

Routing PraisonAI Logs to a File

One-off CLI Debugging

Import-time behaviour (PR #5219)

Environment variables: setdefault, not overwrite

asyncio logger is no longer suppressed

Best Practices

Import Safety (Python)

Thread Safety

Debugging

​Quick Start

​How It Works

​Configuration Options

​Common Patterns

​Quieting PraisonAI in a Larger App

​Routing PraisonAI Logs to a File

​One-off CLI Debugging

​Import-time behaviour (PR #5219)

​Environment variables: setdefault, not overwrite

​asyncio logger is no longer suppressed

​Best Practices

​Related

Import Safety (Python)

Thread Safety

Debugging

Quick Start

How It Works

Configuration Options

Common Patterns

Quieting PraisonAI in a Larger App

Routing PraisonAI Logs to a File

One-off CLI Debugging

Import-time behaviour (PR #5219)

Environment variables: setdefault, not overwrite

asyncio logger is no longer suppressed

Best Practices

Related