<!-- AUTO-GENERATED: do not edit by hand. Run scripts/generate_env_matrix.py -->
# Settings Reference

This guide documents Settings groups and fields.

## core

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `core.app_name` | str | fapilog | Logical application name |
| `core.log_level` | Literal | INFO | Default log level |
| `core.max_queue_size` | int | 10000 | Maximum in-memory queue size for async processing |
| `core.protected_queue_size` | int | None | — | Protected queue capacity in entries; None uses default derivation |
| `core.batch_max_size` | int | 256 | Maximum number of events per batch before a flush is triggered |
| `core.batch_timeout_seconds` | float | 0.25 | Maximum time to wait before flushing a partial batch |
| `core.backpressure_wait_ms` | int | 50 | Milliseconds to wait for queue space before dropping |
| `core.drop_on_full` | bool | True | If True, drop events after backpressure_wait_ms elapses when queue is full |
| `core.protected_levels` | list | PydanticUndefined | Log levels protected from queue-pressure dropping. When queue is full and a protected-level event arrives, an unprotected event is evicted. Set to [] to disable priority dropping (all events treated equally). |
| `core.enable_metrics` | bool | False | Enable Prometheus-compatible metrics |
| `core.context_binding_enabled` | bool | True | Enable per-task bound context via logger.bind/unbind/clear |
| `core.default_bound_context` | dict | PydanticUndefined | Default bound context applied at logger creation when enabled |
| `core.internal_logging_enabled` | bool | False | Emit DEBUG/WARN diagnostics for internal errors |
| `core.diagnostics_output` | Literal | stderr | Output stream for internal diagnostics: stderr (default, Unix convention) or stdout (backward compat) |
| `core.error_dedupe_window_seconds` | float | 5.0 | Seconds to suppress duplicate ERROR logs with the same message; 0 disables deduplication |
| `core.error_dedupe_max_entries` | int | 1000 | Maximum number of entries in the error deduplication dict; oldest entries are evicted when the cap is reached |
| `core.error_dedupe_ttl_multiplier` | float | 10.0 | Multiplier applied to error_dedupe_window_seconds to determine TTL for periodic sweep of stale dedupe entries |
| `core.shutdown_timeout_seconds` | float | 3.0 | Maximum time to flush on shutdown signals |
| `core.worker_count` | int | 1 | Number of worker tasks for flush processing |
| `core.sensitive_fields_policy` | list | PydanticUndefined | Optional list of dotted paths for sensitive fields policy; warning if no redactors configured |
| `core.enable_redactors` | bool | True | Enable redactors stage between enrichers and sink emission |
| `core.redactors_order` | list | PydanticUndefined | Ordered list of redactor plugin names to apply |
| `core.sinks` | list | PydanticUndefined | Sink plugins to use (by name); falls back to env-based default when empty |
| `core.enrichers` | list | PydanticUndefined | Enricher plugins to use (by name) |
| `core.redactors` | list | PydanticUndefined | Redactor plugins to use (by name); defaults to ['url_credentials'] for secure defaults; set to [] to disable all redaction |
| `core.processors` | list | PydanticUndefined | Processor plugins to use (by name) |
| `core.filters` | list | PydanticUndefined | Filter plugins to apply before enrichment (by name) |
| `core.redaction_max_depth` | int | None | 6 | Optional max depth guardrail for nested redaction |
| `core.redaction_max_keys_scanned` | int | None | 5000 | Optional max keys scanned guardrail for redaction |
| `core.exceptions_enabled` | bool | True | Enable structured exception serialization for log calls |
| `core.exceptions_max_frames` | int | 10 | Maximum number of stack frames to capture for exceptions |
| `core.exceptions_max_stack_chars` | int | 20000 | Maximum total characters for serialized stack string |
| `core.strict_envelope_mode` | bool | False | If True, drop emission when envelope cannot be produced; otherwise fallback to best-effort serialization with diagnostics |
| `core.capture_unhandled_enabled` | bool | False | Automatically install unhandled exception hooks (sys/asyncio) |
| `core.serialize_in_flush` | bool | False | If True, pre-serialize envelopes once during flush and pass SerializedView to sinks that support write_serialized |
| `core.resource_pool_max_size` | int | 8 | Default max size for resource pools |
| `core.resource_pool_acquire_timeout_seconds` | float | 2.0 | Default acquire timeout for pools |
| `core.sink_circuit_breaker_enabled` | bool | False | Enable circuit breaker for sink fault isolation |
| `core.sink_circuit_breaker_failure_threshold` | int | 5 | Number of consecutive failures before opening circuit |
| `core.sink_circuit_breaker_recovery_timeout_seconds` | float | 30.0 | Seconds to wait before probing a failed sink |
| `core.sink_circuit_breaker_fallback_sink` | str | None | — | Name of fallback sink to route events to when a circuit breaker opens. Must match a configured sink name. None means silent skip (default). |
| `core.sink_parallel_writes` | bool | False | Write to multiple sinks in parallel instead of sequentially |
| `core.sink_concurrency` | int | 1 | Max concurrent sink writes per worker per batch flush. Unlike sink_parallel_writes (fan-out across multiple sinks), this controls concurrency for multiple events to the same sink. |
| `core.fallback_redact_mode` | Literal | minimal | Redaction mode for fallback stderr output: 'inherit' uses pipeline redactors, 'minimal' applies built-in sensitive field masking, 'none' writes unredacted (opt-in to legacy behavior) |
| `core.redaction_fail_mode` | Literal | warn | Behavior when _apply_redactors() catches an unexpected exception: 'open' passes original event, 'closed' drops the event, 'warn' (default) passes event but emits diagnostic warning |
| `core.atexit_drain_enabled` | bool | True | Register atexit handler to drain pending logs on normal process exit |
| `core.atexit_drain_timeout_seconds` | float | 2.0 | Maximum seconds to wait for log drain during atexit handler |
| `core.signal_handler_enabled` | bool | True | Install signal handlers for SIGTERM/SIGINT to enable graceful drain |
| `core.flush_on_critical` | bool | False | Immediately flush ERROR and CRITICAL logs (bypass batching) to reduce log loss on abrupt shutdown |
| `core.emit_drop_summary` | bool | False | Emit summary log events when events are dropped due to backpressure or deduplicated due to error dedupe window |
| `core.drop_summary_window_seconds` | float | 60.0 | Window in seconds for aggregating drop/dedupe summary events. Summaries are emitted at most once per window. |
| `core.fallback_scrub_raw` | bool | True | Apply keyword scrubbing to raw (non-JSON) fallback output; set to False for debugging when raw output is needed |
| `core.fallback_raw_max_bytes` | int | None | — | Optional limit for raw fallback output bytes; payloads exceeding this are truncated with '[truncated]' marker |
| `core.benchmark_file_path` | str | None | — | Optional path used by performance benchmarks |

## adaptive

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `adaptive.enabled` | bool | False | Enable adaptive pressure monitoring task |
| `adaptive.check_interval_seconds` | float | 0.25 | Seconds between queue pressure samples |
| `adaptive.cooldown_seconds` | float | 2.0 | Minimum seconds between pressure level transitions |
| `adaptive.escalate_to_elevated` | float | 0.6 | Fill ratio to escalate NORMAL to ELEVATED |
| `adaptive.escalate_to_high` | float | 0.8 | Fill ratio to escalate ELEVATED to HIGH |
| `adaptive.escalate_to_critical` | float | 0.92 | Fill ratio to escalate HIGH to CRITICAL |
| `adaptive.filter_tightening` | bool | True | Enable adaptive filter tightening based on pressure level |
| `adaptive.worker_scaling` | bool | True | Enable dynamic worker scaling based on pressure level |
| `adaptive.batch_sizing` | bool | False | Enable adaptive batch sizing based on sink latency feedback |
| `adaptive.max_workers` | int | 8 | Maximum number of workers when dynamic scaling is active |
| `adaptive.circuit_pressure_boost` | float | 0.2 | Effective fill ratio boost per open sink circuit breaker |
| `adaptive.protected_shed_threshold` | float | 0.7 | Protected queue fill ratio that activates shedding |
| `adaptive.protected_recover_threshold` | float | 0.3 | Protected queue fill ratio that deactivates shedding |
| `adaptive.deescalate_from_critical` | float | 0.75 | Fill ratio below which CRITICAL de-escalates to HIGH |
| `adaptive.deescalate_from_high` | float | 0.6 | Fill ratio below which HIGH de-escalates to ELEVATED |
| `adaptive.deescalate_from_elevated` | float | 0.4 | Fill ratio below which ELEVATED de-escalates to NORMAL |

## security

| Field | Type | Default | Description |
|-------|------|---------|-------------|

### security.encryption

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `security.encryption.enabled` | bool | True | Enable encryption features |
| `security.encryption.algorithm` | Literal | AES-256 | Primary encryption algorithm |
| `security.encryption.key_source` | Optional | — | Source for key material |
| `security.encryption.env_var_name` | str | None | — | Environment variable holding key material |
| `security.encryption.key_file_path` | str | None | — | Filesystem path to key material |
| `security.encryption.key_id` | str | None | — | Key identifier for KMS/Vault sources |
| `security.encryption.rotate_interval_days` | int | 90 | Recommended key rotation interval |
| `security.encryption.min_tls_version` | Literal | 1.2 | Minimum TLS version for transport |

### security.access_control

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `security.access_control.enabled` | bool | True | Enable access control checks across the system |
| `security.access_control.auth_mode` | Literal | token | Authentication mode used by integrations (library-agnostic) |
| `security.access_control.allowed_roles` | list | PydanticUndefined | List of roles granted access to protected operations |
| `security.access_control.require_admin_for_sensitive_ops` | bool | True | Require admin role for sensitive or destructive operations |
| `security.access_control.allow_anonymous_read` | bool | False | Permit read access without authentication (discouraged) |
| `security.access_control.allow_anonymous_write` | bool | False | Permit write access without authentication (never recommended) |

## observability

| Field | Type | Default | Description |
|-------|------|---------|-------------|

### observability.monitoring

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `observability.monitoring.enabled` | bool | False | Enable health/monitoring checks and endpoints |
| `observability.monitoring.endpoint` | str | None | — | Monitoring endpoint URL |

### observability.metrics

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `observability.metrics.enabled` | bool | False | Enable internal metrics collection/export |
| `observability.metrics.exporter` | Literal | prometheus | Metrics exporter to use ('prometheus' or 'none') |
| `observability.metrics.port` | int | 8000 | TCP port for metrics exporter |

### observability.tracing

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `observability.tracing.enabled` | bool | False | Enable distributed tracing features |
| `observability.tracing.provider` | Literal | otel | Tracing backend provider ('otel' or 'none') |
| `observability.tracing.sampling_rate` | float | 0.1 | Trace sampling probability in range 0.0–1.0 |

### observability.logging

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `observability.logging.format` | Literal | json | Output format for logs (machine-friendly JSON or text) |
| `observability.logging.include_correlation` | bool | True | Include correlation IDs and trace/span metadata in logs |
| `observability.logging.sampling_rate` | float | 1.0 | DEPRECATED: Use core.filters=['sampling'] with filter_config.sampling instead. Log sampling probability in range 0.0–1.0. |

### observability.alerting

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `observability.alerting.enabled` | bool | False | Enable emitting alerts from the logging pipeline |
| `observability.alerting.min_severity` | Literal | ERROR | Minimum alert severity to emit (filter threshold) |

## plugins

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `plugins.enabled` | bool | True | Enable plugin loading |
| `plugins.allow_external` | bool | False | Allow loading plugins from entry points (security risk) |
| `plugins.allowlist` | list | PydanticUndefined | If non-empty, only these plugin names are allowed |
| `plugins.denylist` | list | PydanticUndefined | Plugin names to block from loading |
| `plugins.validation_mode` | str | disabled | Plugin validation mode: disabled, warn, or strict |