> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Logging Configuration
> Control PraisonAI log output from the CLI or your own scripts
Control how PraisonAI logs run-time information from the CLI or your own Python scripts.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Logging Flow"
A[📝 Code] --> B[🔍 praisonai.* logger]
B --> C[📋 root logger]
C --> D[📤 stderr]
E[🖥️ CLI] -.->|configures| C
end
classDef code fill:#8B0000,stroke:#7C90A0,color:#fff
classDef logger fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
classDef cli fill:#F59E0B,stroke:#7C90A0,color:#fff
class A code
class B,C logger
class D output
class E cli
```
## Quick Start
Set `LOGLEVEL=INFO` (or `DEBUG`) before running PraisonAI commands to see more output.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export LOGLEVEL=INFO
praisonai agents.yaml
```
Call `configure_cli_logging("INFO")` once at app start, or wire your own `logging.basicConfig()`.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant CLI
participant Script
participant Logging
participant Output
Note over CLI,Script: CLI vs Library Import Paths
CLI->>Logging: configure_cli_logging()
Logging->>Output: Root logger configured
Script->>Logging: import praisonai (no auto-config)
Script->>Logging: configure_cli_logging() (optional)
Logging->>Output: Only if explicitly called
```
| 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 |
***
## 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.` logger; **never** mutates root. |
***
## Common Patterns
### Quieting PraisonAI in a Larger App
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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
Always use `get_logger("module")` instead of the root logger when writing library code.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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")
```
Libraries should never call `logging.basicConfig()` as it mutates global state. Let applications control their logging setup.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# ❌ 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")
```
Use the environment variable for temporary debugging instead of changing code.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Quick debug session
LOGLEVEL=DEBUG praisonai agents.yaml
# Production run
praisonai agents.yaml
```
When customizing PraisonAI logging, attach handlers to the `praisonai` logger tree rather than the root logger.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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-safe agent state and wrapper-layer improvements
Best practices for troubleshooting PraisonAI issues