User Guide

Practical usage patterns and configuration for fapilog.

Migration Guides:

Settings to Builder Migration - Migrate from Settings-based to Builder-based configuration
FastAPI Builder Migration - Migrate from setup_logging() to FastAPIBuilder

Overview

The User Guide covers everything you need to know to use fapilog effectively in real applications:

Configuration - Environment variables, settings, and configuration
Execution Modes - Understanding async and sync facades with dedicated thread architecture
Builder Configuration - Fluent API for programmatic configuration
Using the Logger - Logging methods, extra fields, exceptions
Context Enrichment - Adding business context and correlation
Rotating File Sink - File logging with rotation and retention
Graceful Shutdown - Proper cleanup and resource management
Performance Tuning - Optimizing for your use case
Integration Guide - FastAPI, Docker, Kubernetes

For data masking and security, see the dedicated Redaction section.

Quick Reference

Basic Logging (sync)

from fapilog import get_logger

logger = get_logger()
logger.debug("Debug message")
logger.info("Info message", user_id="123")
logger.warning("Warning message")
logger.error("Error message", exc_info=True)

Basic Logging (async)

from fapilog import get_async_logger

logger = await get_async_logger()
await logger.info("Async log entry", request_id="req-1")
await logger.error("Something went wrong", exc_info=True)
await logger.drain()

Context Management

logger = get_logger()

# Bind context for this request
logger.bind(request_id="req-123", user_id="user-456")

# Log with automatic context
logger.info("Request processed")

# Clear context when done
logger.clear_context()

Configuration

# Basic configuration
export FAPILOG_CORE__LOG_LEVEL=INFO

# File logging
export FAPILOG_FILE__DIRECTORY=/var/log/myapp
export FAPILOG_FILE__MAX_BYTES=10485760

# Performance tuning
export FAPILOG_CORE__BATCH_MAX_SIZE=100
export FAPILOG_CORE__MAX_QUEUE_SIZE=8192

What You’ll Learn

Configuration - Environment variables, settings classes, and configuration hierarchy
Execution Modes - Async and sync facades with dedicated thread architecture
Using the Logger - All logging methods, extra fields, and exception handling
Context Enrichment - Adding business context and correlation IDs
Rotating File Sink - File logging with automatic rotation and compression
Graceful Shutdown - Proper cleanup with runtime() / runtime_async()
Performance Tuning - Queue sizes, batching, and optimization
Integration Guide - FastAPI, Docker, Kubernetes, and more

For data masking and security, see the Redaction documentation.

Common Patterns

Request Logging

from fapilog import runtime_async

async def handle_request(request_id: str, user_id: str):
    async with runtime_async() as logger:
        logger.bind(request_id=request_id, user_id=user_id)
        await logger.info("Request started", endpoint="/api/users")
        try:
            result = await process_request()
            await logger.info("Request completed", status="success", duration_ms=45)
            return result
        except Exception:
            await logger.error("Request failed", exc_info=True)
            raise

Batch Processing

from fapilog import runtime

def process_batch(items):
    with runtime() as logger:
        logger.info("Batch processing started", batch_size=len(items))

        for i, item in enumerate(items):
            try:
                process_item(item)
                logger.debug("Item processed", item_index=i, item_id=item.id)
            except Exception as e:
                logger.error("Item processing failed", item_index=i, item_id=item.id, exc=e)

        logger.info("Batch processing completed")

Next Steps

Core Concepts - Understand the architecture
API Reference - Complete API documentation
Examples - Real-world usage patterns

The User Guide shows you how to use fapilog effectively in real applications.