Features

A comprehensive overview of what fapilog offers.

Core Logging

Feature	Why It Matters
Sync and async loggers	Use get_logger() in sync code or get_async_logger() in async code—both use the same non-blocking pipeline
Context managers	runtime() and runtime_async() automatically drain logs on exit, preventing lost messages
Custom log levels	Register domain-specific levels like AUDIT or TRACE with register_level()
Logger caching	Loggers are cached by name by default, so repeated get_logger("app") calls return the same instance

Configuration

Feature	Why It Matters
Presets	Start with dev, production, serverless, or hardened—sensible defaults for common scenarios
Environment detection	Automatically detects Lambda, Kubernetes, Docker, and CI environments to apply appropriate settings
Builder API	Fluent LoggerBuilder for programmatic configuration without YAML or config files
Pydantic settings	Configure via environment variables with type validation

Performance

Feature	Why It Matters
Non-blocking writes	Log calls enqueue and return immediately—I/O happens in background workers
Lock-free queue	NonBlockingRingQueue minimizes contention in high-throughput scenarios
Backpressure handling	Choose between dropping logs (protect latency) or blocking (protect durability) when the queue fills
Batching	Logs are batched before writing to reduce I/O overhead
Zero-copy processing	ZeroCopyProcessor avoids unnecessary memory copies during serialization
Adaptive pipeline	Automatic worker scaling, batch sizing, and filter tightening based on real-time pressure monitoring

Structured Output

Feature	Why It Matters
JSON Lines format	Machine-parseable output for log aggregators and analysis tools
Pretty-print mode	Human-readable output for local development (auto-detected when running in a terminal)
Structured envelope	Every log includes timestamp, level, message, context, diagnostics, and data fields
Origin tracking	Logs are tagged as native, stdlib, or third_party so you know where they came from

Context and Correlation

Feature	Why It Matters
Context binding	Attach fields to a logger with logger.bind(user_id="123") and they appear on every subsequent log
Context variables	bind_context() sets values that propagate across async boundaries
Request ID tracking	Built-in request_id, correlation_id, trace_id, and span_id fields for distributed tracing
Async context preservation	create_task_with_context() and @preserve_context keep context intact across task boundaries

Redaction and Compliance

Feature	Why It Matters
Field masking	Redact specific fields like password or data.credit_card by path
Regex patterns	Match and redact patterns like SSNs, credit card numbers, or API keys
URL credential scrubbing	Automatically redact credentials embedded in database URLs or API endpoints
Compliance presets	Built-in presets for GDPR_PII, HIPAA_PHI, PCI_DSS, CCPA_PII, and SOC2
Fail modes	Choose warn (log and continue) or closed (drop the log) when redaction fails

Sinks

Feature	Why It Matters
Multiple destinations	Write to stdout, files, HTTP endpoints, or cloud services simultaneously
Rotating files	RotatingFileSink handles size-based rotation and optional compression
Cloud-native sinks	Direct integration with CloudWatch, Loki, and PostgreSQL
Sink routing	Route logs by level—send errors to a database while info goes to stdout
Circuit breakers	Failing sinks are temporarily disabled to prevent cascade failures
Fallback sinks	Specify a fallback destination when the primary sink trips its circuit breaker

Filtering

Feature	Why It Matters
Level filtering	Drop logs below a threshold
Sampling	Randomly sample a percentage of logs to reduce volume
Rate limiting	Limit logs per key (e.g., per endpoint or per user) to prevent floods
Adaptive sampling	Automatically increase sampling during error spikes to capture more context
Trace sampling	Sample entire request traces together so you don’t get incomplete pictures

Enrichment

Feature	Why It Matters
Runtime info	Automatically add PID, hostname, and Python version to every log
Kubernetes metadata	Add pod name, namespace, and labels when running in K8s
Custom enrichers	Implement the enricher protocol to add your own fields

Exception Handling

Feature	Why It Matters
Full traceback capture	Exceptions include complete stack traces with configurable depth
Exception chaining	Chained exceptions (raise ... from ...) are preserved
Unhandled exception capture	Optionally log uncaught exceptions before they crash the process
Stack truncation	Limit stack trace size to prevent log bloat

FastAPI Integration

Feature	Why It Matters
Builder pattern	FastAPIBuilder().with_preset("fastapi").build() configures middleware and lifespan
Request/response logging	Automatic logging of incoming requests and outgoing responses
Timing	Request duration is captured and logged
Context injection	Use FastAPI dependencies to inject loggers with request context

Resilience

Feature	Why It Matters
Plugin isolation	A failing enricher or processor doesn’t crash your logging—errors are captured in diagnostics
Graceful shutdown	install_shutdown_handlers() ensures logs are flushed on SIGTERM/SIGINT
Drain operations	Explicitly drain pending logs before shutdown
Health checks	Per-plugin health checks for monitoring

Observability

Feature	Why It Matters
Prometheus metrics	Export logging metrics (queue depth, batch sizes, errors) for monitoring
Per-plugin timing	Track how long each enricher, processor, and sink takes
Diagnostics system	Internal issues are logged with rate limiting to avoid log storms

Extensibility

Feature	Why It Matters
Plugin architecture	Add custom enrichers, redactors, filters, processors, and sinks
Entry point discovery	Plugins can be installed as packages and auto-discovered
Allowlist/denylist	Control which plugins are loaded in production
Stdlib bridge	Route Python’s standard logging module through fapilog

Learn More

• Why Fapilog? - When to choose fapilog over alternatives

• Getting Started - Install and start logging

• Core Concepts - Understand the architecture

• Cookbook - Recipes for common problems