Configuration Reference

Quick reference for all fapilog settings with their environment variable names and builder API equivalents.

Looking for a specific setting? Use Ctrl+F / Cmd+F to search by name.

Environment Variable Naming

Pattern: FAPILOG_<SECTION>__<SETTING>

Use double underscore (__) to separate nested levels
All uppercase
Examples:
- core.log_level → FAPILOG_CORE__LOG_LEVEL
- sink_config.rotating_file.max_bytes → FAPILOG_SINK_CONFIG__ROTATING_FILE__MAX_BYTES
- filter_config.sampling.sample_rate → FAPILOG_FILTER_CONFIG__SAMPLING__SAMPLE_RATE

Type conversion: Environment variables are strings. Fapilog automatically converts:

Booleans: true, false, 1, 0, yes, no, on, off
Integers: 100, 10000
Floats: 0.5, 1.0
Durations: 5s, 1m, 30s, daily, hourly
Sizes: 10 MB, 1 GB, 256 KB
Lists: ["a", "b"] (JSON) or a,b,c (CSV)
Dicts: {"key": "value"} (JSON only)

Core Settings

Settings path: core.*

Setting	Env Var	Builder Method	Default	Description
`core.app_name`	`FAPILOG_CORE__APP_NAME`	`.with_app_name("name")`	`"fapilog"`	Logical application name
`core.log_level`	`FAPILOG_CORE__LOG_LEVEL`	`.with_level("INFO")`	`"INFO"`	Default log level (DEBUG, INFO, WARNING, ERROR)
`core.max_queue_size`	`FAPILOG_CORE__MAX_QUEUE_SIZE`	`.with_queue_size(10000)`	`10000`	Maximum in-memory queue size
`core.protected_queue_size`	`FAPILOG_CORE__PROTECTED_QUEUE_SIZE`	`.with_queue_size(10000, protected_entries=2000)`	`None`	Protected queue capacity; None derives from main
`core.batch_max_size`	`FAPILOG_CORE__BATCH_MAX_SIZE`	`.with_batch_size(256)`	`256`	Maximum events per batch
`core.batch_timeout_seconds`	`FAPILOG_CORE__BATCH_TIMEOUT_SECONDS`	`.with_batch_timeout("0.25s")`	`0.25`	Max time before flushing partial batch
`core.backpressure_wait_ms`	`FAPILOG_CORE__BACKPRESSURE_WAIT_MS`	`.with_backpressure(wait_ms=50)`	`50`	Kept for backward compatibility; enqueue is always non-blocking
`core.drop_on_full`	`FAPILOG_CORE__DROP_ON_FULL`	`.with_backpressure(drop_on_full=True)`	`True`	Drop events when queue is full (always non-blocking)
`core.enable_metrics`	`FAPILOG_CORE__ENABLE_METRICS`	`.with_metrics(enabled=True)`	`False`	Enable Prometheus-compatible metrics
`core.worker_count`	`FAPILOG_CORE__WORKER_COUNT`	`.with_workers(count=1)`	`1`	Number of worker tasks for flush processing (see Validation Limits below)
`core.shutdown_timeout_seconds`	`FAPILOG_CORE__SHUTDOWN_TIMEOUT_SECONDS`	`.with_shutdown_timeout("3s")`	`3.0`	Maximum time to flush on shutdown
`core.error_dedupe_window_seconds`	`FAPILOG_CORE__ERROR_DEDUPE_WINDOW_SECONDS`	`.with_error_deduplication(5.0)`	`5.0`	Seconds to suppress duplicate ERROR logs

Context and Diagnostics

Setting	Env Var	Builder Method	Default	Description
`core.context_binding_enabled`	`FAPILOG_CORE__CONTEXT_BINDING_ENABLED`	Settings only	`True`	Enable per-task bound context
`core.default_bound_context`	`FAPILOG_CORE__DEFAULT_BOUND_CONTEXT`	`.with_context(**kwargs)`	`{}`	Default bound context at logger creation
`core.internal_logging_enabled`	`FAPILOG_CORE__INTERNAL_LOGGING_ENABLED`	`.with_diagnostics(enabled=True)`	`False`	Emit DEBUG/WARN diagnostics for internal errors
`core.diagnostics_output`	`FAPILOG_CORE__DIAGNOSTICS_OUTPUT`	`.with_diagnostics(output="stderr")`	`"stderr"`	Output stream: stderr or stdout

Exception Handling

Setting	Env Var	Builder Method	Default	Description
`core.exceptions_enabled`	`FAPILOG_CORE__EXCEPTIONS_ENABLED`	`.with_exceptions(enabled=True)`	`True`	Enable structured exception serialization
`core.exceptions_max_frames`	`FAPILOG_CORE__EXCEPTIONS_MAX_FRAMES`	`.with_exceptions(max_frames=10)`	`10`	Maximum stack frames to capture
`core.exceptions_max_stack_chars`	`FAPILOG_CORE__EXCEPTIONS_MAX_STACK_CHARS`	`.with_exceptions(max_stack_chars=20000)`	`20000`	Maximum total characters for stack string
`core.capture_unhandled_enabled`	`FAPILOG_CORE__CAPTURE_UNHANDLED_ENABLED`	`.with_unhandled_exception_capture(True)`	`False`	Install unhandled exception hooks

Graceful Shutdown

Setting	Env Var	Builder Method	Default	Description
`core.atexit_drain_enabled`	`FAPILOG_CORE__ATEXIT_DRAIN_ENABLED`	`.with_atexit_drain(enabled=True)`	`True`	Register atexit handler for log drain
`core.atexit_drain_timeout_seconds`	`FAPILOG_CORE__ATEXIT_DRAIN_TIMEOUT_SECONDS`	`.with_atexit_drain(timeout="2s")`	`2.0`	Maximum seconds for atexit drain
`core.signal_handler_enabled`	`FAPILOG_CORE__SIGNAL_HANDLER_ENABLED`	`.with_signal_handlers(enabled=True)`	`True`	Install SIGTERM/SIGINT handlers
`core.flush_on_critical`	`FAPILOG_CORE__FLUSH_ON_CRITICAL`	`.with_flush_on_critical(enabled=True)`	`False`	Immediately flush ERROR/CRITICAL logs

Circuit Breaker

Setting	Env Var	Builder Method	Default	Description
`core.sink_circuit_breaker_enabled`	`FAPILOG_CORE__SINK_CIRCUIT_BREAKER_ENABLED`	`.with_circuit_breaker(enabled=True)`	`False`	Enable circuit breaker for sinks
`core.sink_circuit_breaker_failure_threshold`	`FAPILOG_CORE__SINK_CIRCUIT_BREAKER_FAILURE_THRESHOLD`	`.with_circuit_breaker(failure_threshold=5)`	`5`	Consecutive failures before opening
`core.sink_circuit_breaker_recovery_timeout_seconds`	`FAPILOG_CORE__SINK_CIRCUIT_BREAKER_RECOVERY_TIMEOUT_SECONDS`	`.with_circuit_breaker(recovery_timeout="30s")`	`30.0`	Seconds before probing failed sink
`core.sink_parallel_writes`	`FAPILOG_CORE__SINK_PARALLEL_WRITES`	`.with_parallel_sink_writes(True)`	`False`	Fan-out writes across multiple sinks in parallel
`core.sink_concurrency`	`FAPILOG_CORE__SINK_CONCURRENCY`	`.with_sink_concurrency(limit=8)`	`1`	Max concurrent event writes per worker per batch flush. Unlike `sink_parallel_writes` (multi-sink fan-out), this controls within-sink concurrency for multiple events

Redaction Settings

Setting	Env Var	Builder Method	Default	Description
`core.enable_redactors`	`FAPILOG_CORE__ENABLE_REDACTORS`	Settings only	`True`	Enable redactors stage
`core.redactors`	`FAPILOG_CORE__REDACTORS`	`.with_redaction(...)`	`["url_credentials"]`	Redactor plugins to use
`core.redactors_order`	`FAPILOG_CORE__REDACTORS_ORDER`	Settings only	`["field-mask", "regex-mask", "url-credentials"]`	Order of redactor application
`core.redaction_max_depth`	`FAPILOG_CORE__REDACTION_MAX_DEPTH`	`.with_redaction(max_depth=6)`	`6`	Max nested depth for redaction
`core.redaction_max_keys_scanned`	`FAPILOG_CORE__REDACTION_MAX_KEYS_SCANNED`	`.with_redaction(max_keys=5000)`	`5000`	Max keys scanned during redaction
`core.fallback_redact_mode`	`FAPILOG_CORE__FALLBACK_REDACT_MODE`	`.with_fallback_redaction(fallback_mode="minimal")`	`"minimal"`	Redaction mode for fallback: inherit, minimal, none
`core.redaction_fail_mode`	`FAPILOG_CORE__REDACTION_FAIL_MODE`	`.with_fallback_redaction(fail_mode="warn")`	`"warn"`	Behavior on redaction failure: open, closed, warn
`core.fallback_scrub_raw`	`FAPILOG_CORE__FALLBACK_SCRUB_RAW`	`.with_fallback_redaction(scrub_raw=True)`	`True`	Apply keyword scrubbing to raw fallback
`core.fallback_raw_max_bytes`	`FAPILOG_CORE__FALLBACK_RAW_MAX_BYTES`	`.with_fallback_redaction(raw_max_bytes=1000)`	`None`	Optional byte limit for raw fallback

Drop/Dedupe Visibility

Setting	Env Var	Builder Method	Default	Description
`core.emit_drop_summary`	`FAPILOG_CORE__EMIT_DROP_SUMMARY`	`.with_drop_summary(enabled=True)`	`False`	Emit summary when events dropped
`core.drop_summary_window_seconds`	`FAPILOG_CORE__DROP_SUMMARY_WINDOW_SECONDS`	`.with_drop_summary(window_seconds=60)`	`60.0`	Window for aggregating summaries

Plugin Selection

Setting	Env Var	Builder Method	Default	Description
`core.sinks`	`FAPILOG_CORE__SINKS`	`.add_file()`, `.add_stdout()`, etc.	`[]`	Sink plugins to use
`core.enrichers`	`FAPILOG_CORE__ENRICHERS`	`.with_enrichers(...)`	`["runtime_info", "context_vars"]`	Enricher plugins to use
`core.filters`	`FAPILOG_CORE__FILTERS`	`.with_filters(...)`	`[]`	Filter plugins to apply
`core.processors`	`FAPILOG_CORE__PROCESSORS`	Settings only	`[]`	Processor plugins to use

Advanced

Setting	Env Var	Builder Method	Default	Description
`core.strict_envelope_mode`	`FAPILOG_CORE__STRICT_ENVELOPE_MODE`	`.with_strict_mode(True)`	`False`	Drop on envelope serialization failure
`core.serialize_in_flush`	`FAPILOG_CORE__SERIALIZE_IN_FLUSH`	Settings only	`False`	Pre-serialize envelopes in flush
`core.resource_pool_max_size`	`FAPILOG_CORE__RESOURCE_POOL_MAX_SIZE`	Settings only	`8`	Default max size for resource pools
`core.resource_pool_acquire_timeout_seconds`	`FAPILOG_CORE__RESOURCE_POOL_ACQUIRE_TIMEOUT_SECONDS`	Settings only	`2.0`	Default acquire timeout for pools
`core.sensitive_fields_policy`	`FAPILOG_CORE__SENSITIVE_FIELDS_POLICY`	Settings only	`[]`	Optional list for sensitive fields warning

Validation Limits

Configuration values are validated at logger creation. Invalid values raise ValueError.

Hard limits (rejected if violated):

Setting	Minimum	Error
`max_queue_size`	1	`queue_capacity must be at least 1`
`batch_max_size`	1	`batch_max_size must be at least 1`
`batch_timeout_seconds`	>0	`batch_timeout_seconds must be positive`
`worker_count`	1	`num_workers must be at least 1`

Soft limits (warning emitted via diagnostics):

Setting	Warning Threshold	Recommendation
`worker_count`	>32	More workers increase memory and context-switching overhead
`max_queue_size`	>1,000,000	Large queues consume significant memory
`batch_max_size`	>10,000	Very large batches may cause latency spikes

Relationship warning:

If batch_max_size > max_queue_size, a warning is emitted because batches can never reach their maximum size.

Adaptive Pipeline Settings

Settings path: adaptive.*

Short env var aliases are available (e.g., FAPILOG_ADAPTIVE__ENABLED).

Setting	Env Var	Builder Method	Default	Description
`adaptive.enabled`	`FAPILOG_ADAPTIVE__ENABLED`	`.with_adaptive(enabled=True)`	`False`	Enable adaptive pipeline controller
`adaptive.check_interval_seconds`	`FAPILOG_ADAPTIVE__CHECK_INTERVAL_SECONDS`	`.with_adaptive(check_interval_seconds=0.25)`	`0.25`	Seconds between queue pressure samples
`adaptive.cooldown_seconds`	`FAPILOG_ADAPTIVE__COOLDOWN_SECONDS`	`.with_adaptive(cooldown_seconds=2.0)`	`2.0`	Minimum seconds between pressure level transitions
`adaptive.escalate_to_elevated`	`FAPILOG_ADAPTIVE__ESCALATE_TO_ELEVATED`	Settings only	`0.60`	Fill ratio to escalate NORMAL to ELEVATED
`adaptive.escalate_to_high`	`FAPILOG_ADAPTIVE__ESCALATE_TO_HIGH`	Settings only	`0.80`	Fill ratio to escalate ELEVATED to HIGH
`adaptive.escalate_to_critical`	`FAPILOG_ADAPTIVE__ESCALATE_TO_CRITICAL`	Settings only	`0.92`	Fill ratio to escalate HIGH to CRITICAL
`adaptive.deescalate_from_elevated`	`FAPILOG_ADAPTIVE__DEESCALATE_FROM_ELEVATED`	Settings only	`0.40`	Fill ratio to de-escalate ELEVATED to NORMAL
`adaptive.deescalate_from_high`	`FAPILOG_ADAPTIVE__DEESCALATE_FROM_HIGH`	Settings only	`0.60`	Fill ratio to de-escalate HIGH to ELEVATED
`adaptive.deescalate_from_critical`	`FAPILOG_ADAPTIVE__DEESCALATE_FROM_CRITICAL`	Settings only	`0.75`	Fill ratio to de-escalate CRITICAL to HIGH
`adaptive.max_workers`	`FAPILOG_ADAPTIVE__MAX_WORKERS`	`.with_adaptive(max_workers=8)`	`8`	Maximum workers when dynamic scaling is active
`adaptive.batch_sizing`	`FAPILOG_ADAPTIVE__BATCH_SIZING`	`.with_adaptive(batch_sizing=True)`	`False`	Enable adaptive batch sizing
`adaptive.circuit_pressure_boost`	`FAPILOG_ADAPTIVE__CIRCUIT_PRESSURE_BOOST`	`.with_adaptive(circuit_pressure_boost=0.20)`	`0.20`	Pressure boost per open circuit breaker
`adaptive.filter_tightening`	`FAPILOG_ADAPTIVE__FILTER_TIGHTENING`	`.with_adaptive(filter_tightening=True)`	`True`	Enable adaptive filter tightening based on pressure level
`adaptive.worker_scaling`	`FAPILOG_ADAPTIVE__WORKER_SCALING`	`.with_adaptive(worker_scaling=True)`	`True`	Enable dynamic worker scaling based on pressure level

Sink Settings

Rotating File Sink

Settings path: sink_config.rotating_file.*

Setting	Env Var	Builder Method	Default	Description
`sink_config.rotating_file.directory`	`FAPILOG_SINK_CONFIG__ROTATING_FILE__DIRECTORY`	`.add_file(directory="...")`	`None`	Log directory
`sink_config.rotating_file.filename_prefix`	`FAPILOG_SINK_CONFIG__ROTATING_FILE__FILENAME_PREFIX`	Settings only	`"fapilog"`	Filename prefix
`sink_config.rotating_file.mode`	`FAPILOG_SINK_CONFIG__ROTATING_FILE__MODE`	Settings only	`"json"`	Output format: json or text
`sink_config.rotating_file.max_bytes`	`FAPILOG_SINK_CONFIG__ROTATING_FILE__MAX_BYTES`	`.add_file(max_bytes="10 MB")`	`10485760`	Max bytes before rotation
`sink_config.rotating_file.interval_seconds`	`FAPILOG_SINK_CONFIG__ROTATING_FILE__INTERVAL_SECONDS`	`.add_file(interval="daily")`	`None`	Rotation interval (hourly, daily, etc.)
`sink_config.rotating_file.max_files`	`FAPILOG_SINK_CONFIG__ROTATING_FILE__MAX_FILES`	`.add_file(max_files=10)`	`None`	Max rotated files to keep
`sink_config.rotating_file.max_total_bytes`	`FAPILOG_SINK_CONFIG__ROTATING_FILE__MAX_TOTAL_BYTES`	Settings only	`None`	Max total bytes across all files
`sink_config.rotating_file.compress_rotated`	`FAPILOG_SINK_CONFIG__ROTATING_FILE__COMPRESS_ROTATED`	`.add_file(compress=True)`	`False`	Compress rotated files with gzip

HTTP Sink

Settings path: sink_config.http.* or http.*

Setting	Env Var	Builder Method	Default	Description
`http.endpoint`	`FAPILOG_HTTP__ENDPOINT`	`.add_http(endpoint="...")`	`None`	HTTP endpoint URL
`http.headers`	`FAPILOG_HTTP__HEADERS`	`.add_http(headers={...})`	`{}`	Default headers
`http.headers_json`	`FAPILOG_HTTP__HEADERS_JSON`	Settings only	`None`	JSON-encoded headers map
`http.timeout_seconds`	`FAPILOG_HTTP__TIMEOUT_SECONDS`	`.add_http(timeout="30s")`	`5.0`	Request timeout
`http.retry_max_attempts`	`FAPILOG_HTTP__RETRY_MAX_ATTEMPTS`	Settings only	`None`	Max retry attempts
`http.retry_backoff_seconds`	`FAPILOG_HTTP__RETRY_BACKOFF_SECONDS`	Settings only	`None`	Base backoff between retries
`http.batch_size`	`FAPILOG_HTTP__BATCH_SIZE`	Settings only	`1`	Events per HTTP request
`http.batch_timeout_seconds`	`FAPILOG_HTTP__BATCH_TIMEOUT_SECONDS`	Settings only	`5.0`	Max seconds before flush
`http.batch_format`	`FAPILOG_HTTP__BATCH_FORMAT`	Settings only	`"array"`	Format: array, ndjson, wrapped
`http.batch_wrapper_key`	`FAPILOG_HTTP__BATCH_WRAPPER_KEY`	Settings only	`"logs"`	Wrapper key when format=wrapped

Webhook Sink

Settings path: sink_config.webhook.*

Setting	Env Var	Builder Method	Default	Description
`sink_config.webhook.endpoint`	`FAPILOG_SINK_CONFIG__WEBHOOK__ENDPOINT`	`.add_webhook(endpoint="...")`	`None`	Webhook destination URL
`sink_config.webhook.secret`	`FAPILOG_SINK_CONFIG__WEBHOOK__SECRET`	`.add_webhook(secret="...")`	`None`	Shared secret for signing
`sink_config.webhook.headers`	`FAPILOG_SINK_CONFIG__WEBHOOK__HEADERS`	`.add_webhook(headers={...})`	`{}`	Additional HTTP headers
`sink_config.webhook.timeout_seconds`	`FAPILOG_SINK_CONFIG__WEBHOOK__TIMEOUT_SECONDS`	`.add_webhook(timeout="5s")`	`5.0`	Request timeout
`sink_config.webhook.retry_max_attempts`	`FAPILOG_SINK_CONFIG__WEBHOOK__RETRY_MAX_ATTEMPTS`	Settings only	`None`	Max retry attempts
`sink_config.webhook.retry_backoff_seconds`	`FAPILOG_SINK_CONFIG__WEBHOOK__RETRY_BACKOFF_SECONDS`	Settings only	`None`	Backoff between retries
`sink_config.webhook.batch_size`	`FAPILOG_SINK_CONFIG__WEBHOOK__BATCH_SIZE`	Settings only	`1`	Events per request
`sink_config.webhook.batch_timeout_seconds`	`FAPILOG_SINK_CONFIG__WEBHOOK__BATCH_TIMEOUT_SECONDS`	Settings only	`5.0`	Max seconds before flush

CloudWatch Sink

Settings path: sink_config.cloudwatch.*

Short env var aliases are available (e.g., FAPILOG_CLOUDWATCH__REGION).

Setting	Env Var	Builder Method	Default	Description
`sink_config.cloudwatch.log_group_name`	`FAPILOG_CLOUDWATCH__LOG_GROUP_NAME`	`.add_cloudwatch(log_group="...")`	`"/fapilog/default"`	CloudWatch log group name
`sink_config.cloudwatch.log_stream_name`	`FAPILOG_CLOUDWATCH__LOG_STREAM_NAME`	`.add_cloudwatch(stream="...")`	`None`	Log stream name
`sink_config.cloudwatch.region`	`FAPILOG_CLOUDWATCH__REGION`	`.add_cloudwatch(region="...")`	`None`	AWS region
`sink_config.cloudwatch.endpoint_url`	`FAPILOG_CLOUDWATCH__ENDPOINT_URL`	`.add_cloudwatch(endpoint_url="...")`	`None`	Custom endpoint (LocalStack)
`sink_config.cloudwatch.create_log_group`	`FAPILOG_CLOUDWATCH__CREATE_LOG_GROUP`	`.add_cloudwatch(create_group=True)`	`True`	Create log group if missing
`sink_config.cloudwatch.create_log_stream`	`FAPILOG_CLOUDWATCH__CREATE_LOG_STREAM`	`.add_cloudwatch(create_stream=True)`	`True`	Create log stream if missing
`sink_config.cloudwatch.batch_size`	`FAPILOG_CLOUDWATCH__BATCH_SIZE`	`.add_cloudwatch(batch_size=100)`	`100`	Events per batch
`sink_config.cloudwatch.batch_timeout_seconds`	`FAPILOG_CLOUDWATCH__BATCH_TIMEOUT_SECONDS`	`.add_cloudwatch(batch_timeout="5s")`	`5.0`	Max seconds before flush
`sink_config.cloudwatch.max_retries`	`FAPILOG_CLOUDWATCH__MAX_RETRIES`	`.add_cloudwatch(max_retries=3)`	`3`	Max retries for PutLogEvents
`sink_config.cloudwatch.retry_base_delay`	`FAPILOG_CLOUDWATCH__RETRY_BASE_DELAY`	`.add_cloudwatch(retry_delay=0.5)`	`0.5`	Base delay for backoff
`sink_config.cloudwatch.circuit_breaker_enabled`	`FAPILOG_CLOUDWATCH__CIRCUIT_BREAKER_ENABLED`	`.add_cloudwatch(circuit_breaker=True)`	`True`	Enable circuit breaker
`sink_config.cloudwatch.circuit_breaker_threshold`	`FAPILOG_CLOUDWATCH__CIRCUIT_BREAKER_THRESHOLD`	`.add_cloudwatch(circuit_breaker_threshold=5)`	`5`	Failures before opening

Loki Sink

Settings path: sink_config.loki.*

Short env var aliases are available (e.g., FAPILOG_LOKI__URL).

Setting	Env Var	Builder Method	Default	Description
`sink_config.loki.url`	`FAPILOG_LOKI__URL`	`.add_loki(url="...")`	`"http://localhost:3100"`	Loki push endpoint
`sink_config.loki.tenant_id`	`FAPILOG_LOKI__TENANT_ID`	`.add_loki(tenant_id="...")`	`None`	Multi-tenant identifier
`sink_config.loki.labels`	`FAPILOG_LOKI__LABELS`	`.add_loki(labels={...})`	`{"service": "fapilog"}`	Static labels for streams
`sink_config.loki.label_keys`	`FAPILOG_LOKI__LABEL_KEYS`	`.add_loki(label_keys=[...])`	`["level"]`	Event keys to promote to labels
`sink_config.loki.batch_size`	`FAPILOG_LOKI__BATCH_SIZE`	`.add_loki(batch_size=100)`	`100`	Events per batch
`sink_config.loki.batch_timeout_seconds`	`FAPILOG_LOKI__BATCH_TIMEOUT_SECONDS`	`.add_loki(batch_timeout="5s")`	`5.0`	Max seconds before flush
`sink_config.loki.timeout_seconds`	`FAPILOG_LOKI__TIMEOUT_SECONDS`	`.add_loki(timeout="10s")`	`10.0`	HTTP timeout
`sink_config.loki.max_retries`	`FAPILOG_LOKI__MAX_RETRIES`	`.add_loki(max_retries=3)`	`3`	Max retries on failure
`sink_config.loki.retry_base_delay`	`FAPILOG_LOKI__RETRY_BASE_DELAY`	`.add_loki(retry_delay=0.5)`	`0.5`	Base delay for backoff
`sink_config.loki.auth_username`	`FAPILOG_LOKI__AUTH_USERNAME`	`.add_loki(auth_username="...")`	`None`	Basic auth username
`sink_config.loki.auth_password`	`FAPILOG_LOKI__AUTH_PASSWORD`	`.add_loki(auth_password="...")`	`None`	Basic auth password
`sink_config.loki.auth_token`	`FAPILOG_LOKI__AUTH_TOKEN`	`.add_loki(auth_token="...")`	`None`	Bearer token
`sink_config.loki.circuit_breaker_enabled`	`FAPILOG_LOKI__CIRCUIT_BREAKER_ENABLED`	`.add_loki(circuit_breaker=True)`	`True`	Enable circuit breaker
`sink_config.loki.circuit_breaker_threshold`	`FAPILOG_LOKI__CIRCUIT_BREAKER_THRESHOLD`	`.add_loki(circuit_breaker_threshold=5)`	`5`	Failures before opening

PostgreSQL Sink

Settings path: sink_config.postgres.*

Short env var aliases are available (e.g., FAPILOG_POSTGRES__HOST).

Setting	Env Var	Builder Method	Default	Description
`sink_config.postgres.dsn`	`FAPILOG_POSTGRES__DSN`	`.add_postgres(dsn="...")`	`None`	Full connection string
`sink_config.postgres.host`	`FAPILOG_POSTGRES__HOST`	`.add_postgres(host="...")`	`"localhost"`	Database host
`sink_config.postgres.port`	`FAPILOG_POSTGRES__PORT`	`.add_postgres(port=5432)`	`5432`	Database port
`sink_config.postgres.database`	`FAPILOG_POSTGRES__DATABASE`	`.add_postgres(database="...")`	`"fapilog"`	Database name
`sink_config.postgres.user`	`FAPILOG_POSTGRES__USER`	`.add_postgres(user="...")`	`"fapilog"`	Username
`sink_config.postgres.password`	`FAPILOG_POSTGRES__PASSWORD`	`.add_postgres(password="...")`	`None`	Password
`sink_config.postgres.table_name`	`FAPILOG_POSTGRES__TABLE_NAME`	`.add_postgres(table="...")`	`"logs"`	Target table
`sink_config.postgres.schema_name`	`FAPILOG_POSTGRES__SCHEMA_NAME`	`.add_postgres(schema="...")`	`"public"`	Database schema
`sink_config.postgres.create_table`	`FAPILOG_POSTGRES__CREATE_TABLE`	`.add_postgres(create_table=True)`	`True`	Auto-create table
`sink_config.postgres.min_pool_size`	`FAPILOG_POSTGRES__MIN_POOL_SIZE`	`.add_postgres(min_pool=2)`	`2`	Minimum pool connections
`sink_config.postgres.max_pool_size`	`FAPILOG_POSTGRES__MAX_POOL_SIZE`	`.add_postgres(max_pool=10)`	`10`	Maximum pool connections
`sink_config.postgres.pool_acquire_timeout`	`FAPILOG_POSTGRES__POOL_ACQUIRE_TIMEOUT`	`.add_postgres(pool_acquire_timeout="10s")`	`10.0`	Pool acquire timeout
`sink_config.postgres.batch_size`	`FAPILOG_POSTGRES__BATCH_SIZE`	`.add_postgres(batch_size=100)`	`100`	Events per batch
`sink_config.postgres.batch_timeout_seconds`	`FAPILOG_POSTGRES__BATCH_TIMEOUT_SECONDS`	`.add_postgres(batch_timeout="5s")`	`5.0`	Max seconds before flush
`sink_config.postgres.max_retries`	`FAPILOG_POSTGRES__MAX_RETRIES`	`.add_postgres(max_retries=3)`	`3`	Max retries
`sink_config.postgres.retry_base_delay`	`FAPILOG_POSTGRES__RETRY_BASE_DELAY`	`.add_postgres(retry_delay=0.5)`	`0.5`	Base delay for backoff
`sink_config.postgres.circuit_breaker_enabled`	`FAPILOG_POSTGRES__CIRCUIT_BREAKER_ENABLED`	`.add_postgres(circuit_breaker=True)`	`True`	Enable circuit breaker
`sink_config.postgres.circuit_breaker_threshold`	`FAPILOG_POSTGRES__CIRCUIT_BREAKER_THRESHOLD`	`.add_postgres(circuit_breaker_threshold=5)`	`5`	Failures before opening
`sink_config.postgres.use_jsonb`	`FAPILOG_POSTGRES__USE_JSONB`	`.add_postgres(use_jsonb=True)`	`True`	Use JSONB column type
`sink_config.postgres.include_raw_json`	`FAPILOG_POSTGRES__INCLUDE_RAW_JSON`	`.add_postgres(include_raw_json=True)`	`True`	Store full event JSON
`sink_config.postgres.extract_fields`	`FAPILOG_POSTGRES__EXTRACT_FIELDS`	`.add_postgres(extract_fields=[...])`	`["timestamp", "level", ...]`	Fields to promote to columns

Sealed Sink (Tamper-Evident)

Settings path: sink_config.sealed.*

Setting	Env Var	Builder Method	Default	Description
`sink_config.sealed.inner_sink`	`FAPILOG_SINK_CONFIG__SEALED__INNER_SINK`	Settings only	`"rotating_file"`	Inner sink to wrap
`sink_config.sealed.inner_config`	`FAPILOG_SINK_CONFIG__SEALED__INNER_CONFIG`	Settings only	`{}`	Inner sink configuration
`sink_config.sealed.manifest_path`	`FAPILOG_SINK_CONFIG__SEALED__MANIFEST_PATH`	Settings only	`None`	Manifest directory
`sink_config.sealed.sign_manifests`	`FAPILOG_SINK_CONFIG__SEALED__SIGN_MANIFESTS`	Settings only	`True`	Sign manifests when keys available
`sink_config.sealed.key_id`	`FAPILOG_SINK_CONFIG__SEALED__KEY_ID`	Settings only	`None`	Signing key identifier
`sink_config.sealed.key_provider`	`FAPILOG_SINK_CONFIG__SEALED__KEY_PROVIDER`	Settings only	`"env"`	Key provider for signing
`sink_config.sealed.chain_state_path`	`FAPILOG_SINK_CONFIG__SEALED__CHAIN_STATE_PATH`	Settings only	`None`	Chain state directory
`sink_config.sealed.rotate_chain`	`FAPILOG_SINK_CONFIG__SEALED__ROTATE_CHAIN`	Settings only	`False`	Reset chain on rotation
`sink_config.sealed.fsync_on_write`	`FAPILOG_SINK_CONFIG__SEALED__FSYNC_ON_WRITE`	Settings only	`False`	Fsync on every write
`sink_config.sealed.fsync_on_rotate`	`FAPILOG_SINK_CONFIG__SEALED__FSYNC_ON_ROTATE`	Settings only	`True`	Fsync after rotation
`sink_config.sealed.compress_rotated`	`FAPILOG_SINK_CONFIG__SEALED__COMPRESS_ROTATED`	Settings only	`False`	Compress rotated files
`sink_config.sealed.use_kms_signing`	`FAPILOG_SINK_CONFIG__SEALED__USE_KMS_SIGNING`	Settings only	`False`	Sign via external KMS

Sink Routing

Settings path: sink_routing.*

Short env var aliases are available (e.g., FAPILOG_SINK_ROUTING__ENABLED).

Setting	Env Var	Builder Method	Default	Description
`sink_routing.enabled`	`FAPILOG_SINK_ROUTING__ENABLED`	`.with_routing(rules=[...])`	`False`	Enable level-based routing
`sink_routing.rules`	`FAPILOG_SINK_ROUTING__RULES`	`.with_routing(rules=[...])`	`[]`	Routing rules in priority order
`sink_routing.overlap`	`FAPILOG_SINK_ROUTING__OVERLAP`	`.with_routing(overlap=True)`	`True`	Allow multiple rule matches
`sink_routing.fallback_sinks`	`FAPILOG_SINK_ROUTING__FALLBACK_SINKS`	`.with_routing(fallback=[...])`	`[]`	Sinks when no rules match

Routing rules format:

[
  {"levels": ["ERROR", "CRITICAL"], "sinks": ["cloudwatch"]},
  {"levels": ["INFO", "DEBUG"], "sinks": ["file"]}
]

Redaction Settings

Field Mask Redactor

Settings path: redactor_config.field_mask.*

Setting	Env Var	Builder Method	Default	Description
`redactor_config.field_mask.fields_to_mask`	`FAPILOG_REDACTOR_CONFIG__FIELD_MASK__FIELDS_TO_MASK`	`.with_redaction(fields=[...])`	`[]`	Field names to mask
`redactor_config.field_mask.mask_string`	`FAPILOG_REDACTOR_CONFIG__FIELD_MASK__MASK_STRING`	`.with_redaction(mask="***")`	`"***"`	Replacement string
`redactor_config.field_mask.block_on_unredactable`	`FAPILOG_REDACTOR_CONFIG__FIELD_MASK__BLOCK_ON_UNREDACTABLE`	`.with_redaction(block_on_failure=True)`	`False`	Block if redaction fails
`redactor_config.field_mask.max_depth`	`FAPILOG_REDACTOR_CONFIG__FIELD_MASK__MAX_DEPTH`	Settings only	`16`	Max nested depth
`redactor_config.field_mask.max_keys_scanned`	`FAPILOG_REDACTOR_CONFIG__FIELD_MASK__MAX_KEYS_SCANNED`	Settings only	`1000`	Max keys to scan

Regex Mask Redactor

Settings path: redactor_config.regex_mask.*

Setting	Env Var	Builder Method	Default	Description
`redactor_config.regex_mask.patterns`	`FAPILOG_REDACTOR_CONFIG__REGEX_MASK__PATTERNS`	`.with_redaction(patterns=[...])`	`[]`	Regex patterns to mask
`redactor_config.regex_mask.mask_string`	`FAPILOG_REDACTOR_CONFIG__REGEX_MASK__MASK_STRING`	`.with_redaction(mask="***")`	`"***"`	Replacement string
`redactor_config.regex_mask.block_on_unredactable`	`FAPILOG_REDACTOR_CONFIG__REGEX_MASK__BLOCK_ON_UNREDACTABLE`	`.with_redaction(block_on_failure=True)`	`False`	Block if redaction fails
`redactor_config.regex_mask.max_depth`	`FAPILOG_REDACTOR_CONFIG__REGEX_MASK__MAX_DEPTH`	Settings only	`16`	Max nested depth
`redactor_config.regex_mask.max_keys_scanned`	`FAPILOG_REDACTOR_CONFIG__REGEX_MASK__MAX_KEYS_SCANNED`	Settings only	`1000`	Max keys to scan

URL Credentials Redactor

Settings path: redactor_config.url_credentials.*

Setting	Env Var	Builder Method	Default	Description
`redactor_config.url_credentials.max_string_length`	`FAPILOG_REDACTOR_CONFIG__URL_CREDENTIALS__MAX_STRING_LENGTH`	`.with_redaction(url_max_length=4096)`	`4096`	Max string length to parse

Redaction presets: For compliance-ready redaction, see the Redaction Presets documentation covering GDPR_PII, HIPAA_PHI, PCI_DSS, CREDENTIALS, and more.

Filter Settings

Sampling Filter

Settings path: filter_config.sampling.*

Setting	Env Var	Builder Method	Default	Description
`filter_config.sampling.sample_rate`	`FAPILOG_FILTER_CONFIG__SAMPLING__SAMPLE_RATE`	`.with_sampling(rate=0.1)`	`1.0`	Sample rate 0.0-1.0
`filter_config.sampling.seed`	`FAPILOG_FILTER_CONFIG__SAMPLING__SEED`	`.with_sampling(seed=42)`	`None`	Random seed for reproducibility

Adaptive Sampling Filter

Settings path: filter_config.adaptive_sampling.*

Setting	Env Var	Builder Method	Default	Description
`filter_config.adaptive_sampling.min_rate`	`FAPILOG_FILTER_CONFIG__ADAPTIVE_SAMPLING__MIN_RATE`	`.with_adaptive_sampling(min_rate=0.01)`	`0.01`	Minimum sample rate
`filter_config.adaptive_sampling.max_rate`	`FAPILOG_FILTER_CONFIG__ADAPTIVE_SAMPLING__MAX_RATE`	`.with_adaptive_sampling(max_rate=1.0)`	`1.0`	Maximum sample rate
`filter_config.adaptive_sampling.target_events_per_sec`	`FAPILOG_FILTER_CONFIG__ADAPTIVE_SAMPLING__TARGET_EVENTS_PER_SEC`	`.with_adaptive_sampling(target_events_per_sec=1000)`	`1000.0`	Target throughput
`filter_config.adaptive_sampling.window_seconds`	`FAPILOG_FILTER_CONFIG__ADAPTIVE_SAMPLING__WINDOW_SECONDS`	`.with_adaptive_sampling(window_seconds=60)`	`60.0`	Measurement window

Trace Sampling Filter

Settings path: filter_config.trace_sampling.*

Setting	Env Var	Builder Method	Default	Description
`filter_config.trace_sampling.default_rate`	`FAPILOG_FILTER_CONFIG__TRACE_SAMPLING__DEFAULT_RATE`	`.with_trace_sampling(default_rate=0.1)`	`1.0`	Default rate when no trace context
`filter_config.trace_sampling.honor_upstream`	`FAPILOG_FILTER_CONFIG__TRACE_SAMPLING__HONOR_UPSTREAM`	`.with_trace_sampling(honor_upstream=True)`	`True`	Honor upstream decisions

Rate Limit Filter

Settings path: filter_config.rate_limit.*

Setting	Env Var	Builder Method	Default	Description
`filter_config.rate_limit.capacity`	`FAPILOG_FILTER_CONFIG__RATE_LIMIT__CAPACITY`	`.with_rate_limit(capacity=10)`	`10`	Token bucket capacity
`filter_config.rate_limit.refill_rate_per_sec`	`FAPILOG_FILTER_CONFIG__RATE_LIMIT__REFILL_RATE_PER_SEC`	`.with_rate_limit(refill_rate=5.0)`	`5.0`	Tokens per second
`filter_config.rate_limit.key_field`	`FAPILOG_FILTER_CONFIG__RATE_LIMIT__KEY_FIELD`	`.with_rate_limit(key_field="...")`	`None`	Field for partitioning
`filter_config.rate_limit.max_keys`	`FAPILOG_FILTER_CONFIG__RATE_LIMIT__MAX_KEYS`	`.with_rate_limit(max_keys=10000)`	`10000`	Max buckets
`filter_config.rate_limit.overflow_action`	`FAPILOG_FILTER_CONFIG__RATE_LIMIT__OVERFLOW_ACTION`	`.with_rate_limit(overflow_action="drop")`	`"drop"`	Action: drop or mark

First Occurrence Filter

Settings path: filter_config.first_occurrence.*

Setting	Env Var	Builder Method	Default	Description
`filter_config.first_occurrence.window_seconds`	`FAPILOG_FILTER_CONFIG__FIRST_OCCURRENCE__WINDOW_SECONDS`	`.with_first_occurrence(window_seconds=300)`	`300.0`	Dedup window
`filter_config.first_occurrence.max_entries`	`FAPILOG_FILTER_CONFIG__FIRST_OCCURRENCE__MAX_ENTRIES`	`.with_first_occurrence(max_entries=10000)`	`10000`	Max tracked messages
`filter_config.first_occurrence.key_fields`	`FAPILOG_FILTER_CONFIG__FIRST_OCCURRENCE__KEY_FIELDS`	`.with_first_occurrence(key_fields=[...])`	`None`	Fields for dedup key

Processor Settings

Size Guard Processor

Settings path: processor_config.size_guard.*

Short env var aliases are available (e.g., FAPILOG_SIZE_GUARD__MAX_BYTES).

Setting	Env Var	Builder Method	Default	Description
`processor_config.size_guard.max_bytes`	`FAPILOG_SIZE_GUARD__MAX_BYTES`	`.with_size_guard(max_bytes="256 KB")`	`256000`	Maximum payload size
`processor_config.size_guard.action`	`FAPILOG_SIZE_GUARD__ACTION`	`.with_size_guard(action="truncate")`	`"truncate"`	Action: truncate, drop, warn
`processor_config.size_guard.preserve_fields`	`FAPILOG_SIZE_GUARD__PRESERVE_FIELDS`	`.with_size_guard(preserve_fields=[...])`	`["level", "timestamp", ...]`	Fields to never remove

Observability Settings

Settings path: observability.*

Monitoring

Setting	Env Var	Builder Method	Default	Description
`observability.monitoring.enabled`	`FAPILOG_OBSERVABILITY__MONITORING__ENABLED`	Settings only	`False`	Enable health/monitoring
`observability.monitoring.endpoint`	`FAPILOG_OBSERVABILITY__MONITORING__ENDPOINT`	Settings only	`None`	Monitoring endpoint URL

Metrics

Setting	Env Var	Builder Method	Default	Description
`observability.metrics.enabled`	`FAPILOG_OBSERVABILITY__METRICS__ENABLED`	Settings only	`False`	Enable metrics collection
`observability.metrics.exporter`	`FAPILOG_OBSERVABILITY__METRICS__EXPORTER`	Settings only	`"prometheus"`	Exporter: prometheus or none
`observability.metrics.port`	`FAPILOG_OBSERVABILITY__METRICS__PORT`	Settings only	`8000`	Metrics exporter port

Tracing

Setting	Env Var	Builder Method	Default	Description
`observability.tracing.enabled`	`FAPILOG_OBSERVABILITY__TRACING__ENABLED`	Settings only	`False`	Enable distributed tracing
`observability.tracing.provider`	`FAPILOG_OBSERVABILITY__TRACING__PROVIDER`	Settings only	`"otel"`	Provider: otel or none
`observability.tracing.sampling_rate`	`FAPILOG_OBSERVABILITY__TRACING__SAMPLING_RATE`	Settings only	`0.1`	Trace sampling rate 0.0-1.0

Logging

Setting	Env Var	Builder Method	Default	Description
`observability.logging.format`	`FAPILOG_OBSERVABILITY__LOGGING__FORMAT`	Settings only	`"json"`	Output format: json or text
`observability.logging.include_correlation`	`FAPILOG_OBSERVABILITY__LOGGING__INCLUDE_CORRELATION`	Settings only	`True`	Include correlation IDs
`observability.logging.sampling_rate`	`FAPILOG_OBSERVABILITY__LOGGING__SAMPLING_RATE`	Settings only	`1.0`	Log sampling rate (deprecated)

Alerting

Setting	Env Var	Builder Method	Default	Description
`observability.alerting.enabled`	`FAPILOG_OBSERVABILITY__ALERTING__ENABLED`	Settings only	`False`	Enable alerting
`observability.alerting.min_severity`	`FAPILOG_OBSERVABILITY__ALERTING__MIN_SEVERITY`	Settings only	`"ERROR"`	Minimum alert severity

Plugin Settings

Settings path: plugins.*

Setting	Env Var	Builder Method	Default	Description
`plugins.enabled`	`FAPILOG_PLUGINS__ENABLED`	`.with_plugins(enabled=True)`	`True`	Enable plugin loading
`plugins.allow_external`	`FAPILOG_PLUGINS__ALLOW_EXTERNAL`	`.with_plugins(allow_external=True)`	`False`	Allow entry point plugins
`plugins.allowlist`	`FAPILOG_PLUGINS__ALLOWLIST`	`.with_plugins(allowlist=[...])`	`[]`	Only allow these plugins
`plugins.denylist`	`FAPILOG_PLUGINS__DENYLIST`	`.with_plugins(denylist=[...])`	`[]`	Block these plugins
`plugins.validation_mode`	`FAPILOG_PLUGINS__VALIDATION_MODE`	`.with_plugins(validation_mode="warn")`	`"disabled"`	Mode: disabled, warn, strict

Enricher Settings

Integrity Enricher (Tamper-Evident)

Settings path: enricher_config.integrity.*

Setting	Env Var	Builder Method	Default	Description
`enricher_config.integrity.algorithm`	`FAPILOG_ENRICHER_CONFIG__INTEGRITY__ALGORITHM`	Settings only	`"sha256"`	MAC algorithm: sha256 or ed25519
`enricher_config.integrity.key_id`	`FAPILOG_ENRICHER_CONFIG__INTEGRITY__KEY_ID`	Settings only	`None`	Key identifier
`enricher_config.integrity.key_provider`	`FAPILOG_ENRICHER_CONFIG__INTEGRITY__KEY_PROVIDER`	Settings only	`"env"`	Key provider
`enricher_config.integrity.chain_state_path`	`FAPILOG_ENRICHER_CONFIG__INTEGRITY__CHAIN_STATE_PATH`	Settings only	`None`	Chain state directory
`enricher_config.integrity.rotate_chain`	`FAPILOG_ENRICHER_CONFIG__INTEGRITY__ROTATE_CHAIN`	Settings only	`False`	Reset chain after rotation
`enricher_config.integrity.use_kms_signing`	`FAPILOG_ENRICHER_CONFIG__INTEGRITY__USE_KMS_SIGNING`	Settings only	`False`	Sign via KMS provider

Configuration Reference

Environment Variable Naming

Core Settings

Context and Diagnostics

Exception Handling

Graceful Shutdown

Circuit Breaker

Redaction Settings

Drop/Dedupe Visibility

Plugin Selection

Advanced

Validation Limits

Adaptive Pipeline Settings

Sink Settings

Rotating File Sink

HTTP Sink

Webhook Sink

CloudWatch Sink

Loki Sink

PostgreSQL Sink

Sealed Sink (Tamper-Evident)

Sink Routing

Redaction Settings

Field Mask Redactor

Regex Mask Redactor

URL Credentials Redactor

Filter Settings

Sampling Filter

Adaptive Sampling Filter

Trace Sampling Filter

Rate Limit Filter

First Occurrence Filter

Processor Settings

Size Guard Processor

Observability Settings

Monitoring

Metrics

Tracing

Logging

Alerting

Plugin Settings

Enricher Settings

Integrity Enricher (Tamper-Evident)

See Also