Configuration Presets

Presets provide pre-configured settings for common deployment scenarios. Choose a preset that matches your use case to get sensible defaults without manual configuration.

Quick Reference

Preset	Use Case	Drops Logs?	File Output	Redaction
`dev`	Local development	No	No	No
`production`	Production with adaptive scaling	Backpressure retry	Fallback only	Yes (CREDENTIALS)
`serverless`	Lambda/Cloud Run	If needed	No	Yes (CREDENTIALS)
`hardened`	Compliance (HIPAA/PCI)	Never	Yes	Yes (HIPAA + PCI + CREDENTIALS)
`minimal`	Maximum control	Default	Default	No

Note: The adaptive preset name is deprecated. Use production instead — it now includes all adaptive features (dynamic worker scaling, filter tightening, circuit breaker).

Choosing a Preset

Is this for local development?
├─ Yes → dev
└─ No → Is this for serverless (Lambda/Cloud Run)?
         ├─ Yes → serverless
         └─ No → Do you need HIPAA/PCI compliance?
                  ├─ Yes → hardened
                  └─ No → Is this a production deployment?
                           ├─ Yes → production (adaptive scaling, backpressure, circuit breaker)
                           └─ No → minimal (maximum control)

Usage

from fapilog import get_logger, LoggerBuilder

# Simple usage
logger = get_logger(preset="production")

# Builder API
logger = (
    LoggerBuilder()
    .with_preset("production")
    .build()
)

# Customize a preset
logger = (
    LoggerBuilder()
    .with_preset("production")
    .with_redaction(preset="HIPAA_PHI")  # Add HIPAA compliance
    .with_level("DEBUG")                  # Override log level
    .build()
)

Performance Settings

Preset	Workers	Batch Size	Queue Size	Enrichers
`dev`	1	1	256	runtime_info, context_vars
`production`	2 (up to 4)	256	10000 (fixed)	runtime_info, context_vars
`serverless`	2	25	256	runtime_info, context_vars
`hardened`	2	256	256	runtime_info, context_vars
`minimal`	1	256	256	runtime_info, context_vars

Performance note: Production-oriented presets use 2 workers for ~30x better throughput compared to single-worker defaults. See Performance Tuning for details.

Reliability Settings

Preset	`drop_on_full`	`redaction_fail_mode`	`strict_envelope_mode`	File Rotation
`dev`	N/A	N/A	`False`	None
`production`	`False`	`warn`	`False`	Fallback only (50MB x 10, gzip)
`serverless`	`True`	`warn`	`False`	None
`hardened`	`False`	`closed`	`True`	50MB x 10, gzip
`minimal`	`True`	N/A	`False`	None

Understanding `drop_on_full`

False (production, hardened): The caller thread retries with exponential backoff up to backpressure_wait_ms (default 50ms) before dropping. This ensures durability with bounded latency impact.
True (serverless, minimal): Drops events immediately when queue is full, maintaining application throughput. Events may be lost under extreme load.

See Reliability Defaults for detailed backpressure behavior.

Redaction Settings

Preset	Auto-Applied Presets	`fallback_redact_mode`	`fallback_scrub_raw`
`dev`	None	N/A	N/A
`production`	CREDENTIALS	`minimal`	`False`
`serverless`	CREDENTIALS	`minimal`	`False`
`hardened`	HIPAA_PHI + PCI_DSS + CREDENTIALS	`inherit`	`True`
`minimal`	None	N/A	N/A

The CREDENTIALS preset automatically redacts:

password, api_key, token, secret
authorization, api_secret, private_key
ssn, credit_card

See Redaction Presets for the complete field list and compliance presets.

Preset Details

dev

Local development with maximum visibility.

logger = get_logger(preset="dev")

Settings:

DEBUG level shows all messages
Immediate flushing (batch_size=1) for real-time debugging
Pretty console output for readability
Internal diagnostics enabled
No redaction (safe for local secrets)

Use when: Debugging locally, running tests, exploring fapilog features.

production

Production deployment with adaptive scaling, backpressure retry, and circuit breaker fallback.

logger = get_logger(preset="production")

Settings:

INFO level filters noise
batch_max_size=256, batch_timeout_seconds=0.25
max_queue_size=10000, sink_concurrency=8, shutdown_timeout_seconds=25.0
Adaptive pipeline enabled: dynamic worker scaling (2-4), filter tightening, fixed queue capacity
Circuit breaker with rotating file fallback — failing sinks are isolated, events reroute to local files
File rotation: ./logs/fapilog-*.log, 50MB max, 10 files, gzip compressed (fallback only)
drop_on_full=False — bounded backpressure retry before dropping
Protected levels: ERROR, CRITICAL (routed to dedicated queue)
Automatic redaction of credentials

Use when: Any production deployment — audit trails, high-throughput APIs, microservices, variable-load workloads.

Trade-off: Under extreme load, logging may briefly retry (up to 50ms default) on the caller thread to ensure durability. For latency-sensitive workloads, override with .with_backpressure(drop_on_full=True).

For fine-grained control over adaptive behavior, use the builder:

logger = (
    LoggerBuilder()
    .with_preset("production")
    .with_adaptive(max_workers=6)
    .with_circuit_breaker(fallback_sink="rotating_file")
    .build()
)

# Enable batch sizing when using batch-aware sinks (CloudWatch, Loki, PostgreSQL)
logger = (
    LoggerBuilder()
    .with_preset("production")
    .with_adaptive(batch_sizing=True)
    .add_cloudwatch("/myapp/prod")
    .build()
)

See Adaptive Pipeline for a detailed guide on tuning thresholds and actuators.

serverless

Optimized for AWS Lambda, Google Cloud Run, Azure Functions.

logger = get_logger(preset="serverless")

Settings:

Stdout-only (cloud providers capture stdout automatically)
drop_on_full=True (don’t block in time-constrained environments)
Smaller batch size (25) for quick flushing before function timeout
Automatic redaction of credentials
2 workers for throughput

Use when: Lambda functions, Cloud Run services, any short-lived serverless workload.

hardened

Maximum security for regulated environments (HIPAA, PCI-DSS, financial services).

logger = get_logger(preset="hardened")

Settings:

All strict security settings enabled:
- redaction_fail_mode="closed" — drops events if redaction fails
- strict_envelope_mode=True — rejects malformed envelopes
- fallback_redact_mode="inherit" — full redaction on fallback output
- fallback_scrub_raw=True — scrubs raw fallback output
- drop_on_full=False — never drops logs
Comprehensive redaction from HIPAA_PHI, PCI_DSS, and CREDENTIALS presets
File rotation for audit trails

Use when: Healthcare (HIPAA), payment processing (PCI-DSS), financial services, any environment requiring fail-closed security.

Trade-off: Prioritizes security over availability — may drop events that fail redaction or have malformed data.

minimal

Matches get_logger() with no arguments. Use for explicit preset selection while maintaining backwards compatibility.

logger = get_logger(preset="minimal")

Settings:

Default values for everything
No redaction configured
No file output

Use when: Migrating from another logging library, gradual adoption, explicit “no preset” behavior.

Migration: `adaptive` to `production`

The adaptive preset name is deprecated as of Story 1.53. All adaptive features are now included in the production preset.

Before:

logger = get_logger(preset="adaptive")  # DeprecationWarning

After:

logger = get_logger(preset="production")  # Same features, no warning

The adaptive name continues to work as an alias but emits a DeprecationWarning.

Customizing Presets

Presets are applied first, then builder methods override specific values:

from fapilog import LoggerBuilder

# Start with production, customize for your needs
logger = (
    LoggerBuilder()
    .with_preset("production")
    .with_level("DEBUG")                          # Override log level
    .with_redaction(preset="HIPAA_PHI")           # Add HIPAA fields
    .with_sampling(rate=0.1)                      # Sample 10%
    .add_cloudwatch("/myapp/prod")                # Add CloudWatch sink
    .build()
)

Sinks are merged, not replaced:

# Production preset has stdout_json (primary) + rotating_file (fallback)
# This adds CloudWatch without removing those
logger = (
    LoggerBuilder()
    .with_preset("production")
    .add_cloudwatch("/myapp/prod")  # Now has 2 primary sinks + fallback
    .build()
)

Trade-offs Explained

Latency vs Durability

The fundamental trade-off in production logging:

Durability-first (production, hardened): Set drop_on_full=False. The caller thread retries with bounded backpressure (exponential backoff up to backpressure_wait_ms) before dropping. Best for audit trails and debugging.
Latency-first (serverless): Set drop_on_full=True. Events are dropped if the queue is full, ensuring the application never blocks on logging. Best for latency-sensitive workloads. For production with latency priority, use production with .with_backpressure(drop_on_full=True).

Worker Count Impact

Workers	Throughput	Use Case
1	~3,500/sec	Development, low-volume
2	~105,000/sec	Production workloads

All production-oriented presets default to 2 workers. See Performance Tuning for benchmarks.

Redaction Modes

warn (default): Log a warning if redaction fails, emit event anyway. Production-safe default.
closed (hardened only): Drop the event entirely if redaction fails. Maximum security, may lose events.

Listing Available Presets

from fapilog import list_presets

print(list_presets())
# ['adaptive', 'dev', 'hardened', 'minimal', 'production', 'serverless']

Configuration Presets

Quick Reference

Choosing a Preset

Usage

Performance Settings

Reliability Settings

Understanding drop_on_full

Redaction Settings

Preset Details

dev

production

serverless

hardened

minimal

Migration: adaptive to production

Customizing Presets

Trade-offs Explained

Latency vs Durability

Worker Count Impact

Redaction Modes

Listing Available Presets

Related

Understanding `drop_on_full`

Migration: `adaptive` to `production`