Implementation:Guardrails ai Guardrails Logger

Knowledge Sources	Guardrails
Domains	Logging, Observability
Last Updated	2026-02-14 00:00 GMT

Overview

The Logger module provides a scoped logging system for the Guardrails library, enabling log records to be organized and retrieved by named scopes.

Description

This module implements a custom logging infrastructure built around Python's standard logging module. The ScopeHandler class extends logging.Handler to store log records in a dictionary keyed by scope name, allowing logs from different execution contexts (e.g., different guard invocations) to be isolated and retrieved independently. The LoggerConfig class holds configuration state including the logging level, scope, and optional dictConfig settings. Module-level functions (get_logger, set_config, set_level, set_scope) provide a convenient API for configuring and retrieving the shared logger instance named "guardrails-ai". The module initializes a singleton logger instance on import.

Usage

Use this module to access the Guardrails library logger for emitting and retrieving scoped log records. Import the logger instance directly for standard logging. Use set_scope to isolate logs for a particular guard execution, and get_scope_handler().get_logs() to retrieve logs for a given scope.

Code Reference

Source Location

• Repository: Guardrails
• File: guardrails/logger.py

Signature

class ScopeHandler(Handler):
    scope: str
    scoped_logs: Dict[str, List[LogRecord]]

    def __init__(self, level=logging.NOTSET, scope=base_scope)
    def emit(self, record: LogRecord) -> None
    def set_scope(self, scope: str = base_scope)
    def get_all_logs(self) -> List[LogRecord]
    def get_logs(self, scope: Optional[str] = None) -> List[LogRecord]

class LoggerConfig:
    def __init__(self, config={}, level=logging.NOTSET, scope=base_scope)

def get_logger() -> logging.Logger
def set_config(config=None)
def set_level(level=None)
def set_scope(scope: str = base_scope)
def get_scope_handler() -> ScopeHandler

Import

from guardrails.logger import logger
from guardrails.logger import set_config, set_level, set_scope
from guardrails.logger import get_scope_handler, ScopeHandler

I/O Contract

ScopeHandler

Method	Parameters	Returns	Description
__init__	level: int, scope: str	N/A	Initializes the handler with a logging level and default scope
emit	record: LogRecord	None	Appends the log record to the list for the current scope
set_scope	scope: str	None	Changes the active scope for subsequent log records
get_all_logs	N/A	List[LogRecord]	Returns all log records across all scopes
get_logs	scope: Optional[str]	List[LogRecord]	Returns log records for the given scope, or all logs if scope is "all"

Module-Level Functions

Function	Parameters	Returns	Description
get_logger	N/A	logging.Logger	Returns the configured Guardrails logger instance
set_config	config: dict	None	Applies a dictConfig logging configuration
set_level	level: int	None	Sets the logging level for the Guardrails logger
set_scope	scope: str	None	Sets the active scope on both the config and handler
get_scope_handler	N/A	ScopeHandler	Retrieves or creates the ScopeHandler attached to the logger

Constants

Constant	Value	Description
name	"guardrails-ai"	Logger name
base_scope	"base"	Default scope name
all_scopes	"all"	Special scope name to retrieve logs from all scopes

Usage Examples

from guardrails.logger import logger, set_level, set_scope, get_scope_handler
import logging

# Set logging level to DEBUG
set_level(logging.DEBUG)

# Set a custom scope for a guard run
set_scope("guard_run_123")

# Log messages are stored under the current scope
logger.info("Starting guard execution")
logger.debug("Validating output schema")

# Retrieve logs for the current scope
handler = get_scope_handler()
logs = handler.get_logs("guard_run_123")
for record in logs:
    print(record.getMessage())

# Retrieve all logs across scopes
all_logs = handler.get_all_logs()

Related Pages

• Guardrails_ai_Guardrails_Telemetry_Common
• Guardrails_ai_Guardrails_Guard_Tracing