Core Concepts

Understand what fapilog does for you and how it keeps your app fast and reliable.

Core Concepts

Overview

fapilog is built around a few core concepts that make it fast, reliable, and developer-friendly:

  • Pipeline Architecture - Why your log calls return immediately while I/O happens in the background

  • Envelope - How logs are structured so they’re easy to query and alert on

  • Context Binding - How to add request_id once and see it in every log automatically

  • Batching & Backpressure - What happens during traffic spikes (you choose: drop or wait)

  • Redaction - How secrets stay out of your logs without extra code

  • Sinks - Send logs anywhere—stdout, files, CloudWatch, databases

  • Metrics - See queue depth and dropped logs before problems hit production

  • Diagnostics & Resilience - How fapilog recovers from errors without crashing your app

Key Principles

Fapilog isn’t a thin wrapper over existing logging libraries—it’s an async-first logging pipeline designed to keep your app responsive under slow or bursty log sinks, with backpressure policies, redaction, and first-class FastAPI integration built in.

1. Your App Stays Fast

Log calls return immediately—they never wait for disk or network I/O:

  • A slow CloudWatch API won’t slow down your API responses

  • Traffic spikes don’t cause thread stalls

  • Works the same whether you use get_logger() or get_async_logger()

2. Memory-Efficient by Design

Fapilog processes logs without creating unnecessary copies:

  • Your app uses less memory per log entry

  • High-volume logging won’t trigger GC pauses that hurt response times

  • You can log more without budgeting extra RAM

3. Logs You Can Actually Query

All logs are structured JSON by default:

  • Filter by request_id, user_id, or any field in your log aggregator

  • Build dashboards and alerts without parsing text

  • Same format everywhere—stdout, files, cloud sinks

4. Extend Without Forking

Add functionality through plugins:

  • Send logs to any destination with custom sinks

  • Add context automatically with enrichers

  • Mask sensitive data with redactors

Architecture Overview

Your log call returns immediately. Everything after the queue happens in background workers:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ Application │───▶│   Context   │───▶│ Enrichers   │───▶│ Redactors   │
│             │    │ (request_id │    │ (add host,  │    │ (mask       │
│ log.info()  │    │  auto-added)│    │  version)   │    │  secrets)   │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
      ↑                                                        │
   Returns                                                     ↓
  immediately    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
                 │    Sinks    │◀───│    Queue    │◀───│ Processors  │
                 │ (CloudWatch,│    │ (buffer for │    │ (format,    │
                 │  stdout...) │    │  slow sinks)│    │  compress)  │
                 └─────────────┘    └─────────────┘    └─────────────┘

What You’ll Learn

  1. Pipeline Architecture - Why log calls never block your app

  2. Envelope - How logs are structured for easy querying

  3. Context Binding - Add request_id once, see it everywhere

  4. Batching & Backpressure - Control what happens during traffic spikes

  5. Redaction - Keep secrets out of logs automatically

  6. Sinks - Send logs to stdout, files, CloudWatch, databases

  7. Metrics - Monitor queue health before problems hit

  8. Diagnostics & Resilience - How fapilog handles errors gracefully

Next Steps

After understanding the core concepts:

Understanding these core concepts will help you make the most of fapilog’s capabilities.