Schema Guide
Settings JSON Schemas
CoreSettings
{
"description": "Core logging and performance settings.\n\nKeep this minimal and stable; prefer plugin-specific settings elsewhere.",
"properties": {
"app_name": {
"default": "fapilog",
"description": "Logical application name",
"title": "App Name",
"type": "string"
},
"atexit_drain_enabled": {
"default": true,
"description": "Register atexit handler to drain pending logs on normal process exit",
"title": "Atexit Drain Enabled",
"type": "boolean"
},
"atexit_drain_timeout_seconds": {
"default": 2.0,
"description": "Maximum seconds to wait for log drain during atexit handler",
"exclusiveMinimum": 0.0,
"title": "Atexit Drain Timeout Seconds",
"type": "number"
},
"backpressure_wait_ms": {
"default": 50,
"description": "Milliseconds to wait for queue space before dropping",
"minimum": 0,
"title": "Backpressure Wait Ms",
"type": "integer"
},
"batch_max_size": {
"default": 256,
"description": "Maximum number of events per batch before a flush is triggered",
"minimum": 1,
"title": "Batch Max Size",
"type": "integer"
},
"batch_timeout_seconds": {
"default": 0.25,
"description": "Maximum time to wait before flushing a partial batch",
"exclusiveMinimum": 0.0,
"title": "Batch Timeout Seconds",
"type": "number"
},
"benchmark_file_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional path used by performance benchmarks",
"title": "Benchmark File Path"
},
"capture_unhandled_enabled": {
"default": false,
"description": "Automatically install unhandled exception hooks (sys/asyncio)",
"title": "Capture Unhandled Enabled",
"type": "boolean"
},
"context_binding_enabled": {
"default": true,
"description": "Enable per-task bound context via logger.bind/unbind/clear",
"title": "Context Binding Enabled",
"type": "boolean"
},
"default_bound_context": {
"additionalProperties": true,
"description": "Default bound context applied at logger creation when enabled",
"title": "Default Bound Context",
"type": "object"
},
"diagnostics_output": {
"default": "stderr",
"description": "Output stream for internal diagnostics: stderr (default, Unix convention) or stdout (backward compat)",
"enum": [
"stderr",
"stdout"
],
"title": "Diagnostics Output",
"type": "string"
},
"drop_on_full": {
"default": true,
"description": "If True, drop events after backpressure_wait_ms elapses when queue is full",
"title": "Drop On Full",
"type": "boolean"
},
"drop_summary_window_seconds": {
"default": 60.0,
"description": "Window in seconds for aggregating drop/dedupe summary events. Summaries are emitted at most once per window.",
"minimum": 1.0,
"title": "Drop Summary Window Seconds",
"type": "number"
},
"emit_drop_summary": {
"default": false,
"description": "Emit summary log events when events are dropped due to backpressure or deduplicated due to error dedupe window",
"title": "Emit Drop Summary",
"type": "boolean"
},
"enable_metrics": {
"default": false,
"description": "Enable Prometheus-compatible metrics",
"title": "Enable Metrics",
"type": "boolean"
},
"enable_redactors": {
"default": true,
"description": "Enable redactors stage between enrichers and sink emission",
"title": "Enable Redactors",
"type": "boolean"
},
"enrichers": {
"description": "Enricher plugins to use (by name)",
"items": {
"type": "string"
},
"title": "Enrichers",
"type": "array"
},
"error_dedupe_max_entries": {
"default": 1000,
"description": "Maximum number of entries in the error deduplication dict; oldest entries are evicted when the cap is reached",
"minimum": 1,
"title": "Error Dedupe Max Entries",
"type": "integer"
},
"error_dedupe_ttl_multiplier": {
"default": 10.0,
"description": "Multiplier applied to error_dedupe_window_seconds to determine TTL for periodic sweep of stale dedupe entries",
"exclusiveMinimum": 0.0,
"title": "Error Dedupe Ttl Multiplier",
"type": "number"
},
"error_dedupe_window_seconds": {
"default": 5.0,
"description": "Seconds to suppress duplicate ERROR logs with the same message; 0 disables deduplication",
"minimum": 0.0,
"title": "Error Dedupe Window Seconds",
"type": "number"
},
"exceptions_enabled": {
"default": true,
"description": "Enable structured exception serialization for log calls",
"title": "Exceptions Enabled",
"type": "boolean"
},
"exceptions_max_frames": {
"default": 10,
"description": "Maximum number of stack frames to capture for exceptions",
"minimum": 1,
"title": "Exceptions Max Frames",
"type": "integer"
},
"exceptions_max_stack_chars": {
"default": 20000,
"description": "Maximum total characters for serialized stack string",
"minimum": 1000,
"title": "Exceptions Max Stack Chars",
"type": "integer"
},
"fallback_raw_max_bytes": {
"anyOf": [
{
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional limit for raw fallback output bytes; payloads exceeding this are truncated with '[truncated]' marker",
"title": "Fallback Raw Max Bytes"
},
"fallback_redact_mode": {
"default": "minimal",
"description": "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)",
"enum": [
"inherit",
"minimal",
"none"
],
"title": "Fallback Redact Mode",
"type": "string"
},
"fallback_scrub_raw": {
"default": true,
"description": "Apply keyword scrubbing to raw (non-JSON) fallback output; set to False for debugging when raw output is needed",
"title": "Fallback Scrub Raw",
"type": "boolean"
},
"filters": {
"description": "Filter plugins to apply before enrichment (by name)",
"items": {
"type": "string"
},
"title": "Filters",
"type": "array"
},
"flush_on_critical": {
"default": false,
"description": "Immediately flush ERROR and CRITICAL logs (bypass batching) to reduce log loss on abrupt shutdown",
"title": "Flush On Critical",
"type": "boolean"
},
"internal_logging_enabled": {
"default": false,
"description": "Emit DEBUG/WARN diagnostics for internal errors",
"title": "Internal Logging Enabled",
"type": "boolean"
},
"log_level": {
"default": "INFO",
"description": "Default log level",
"enum": [
"DEBUG",
"INFO",
"WARNING",
"ERROR"
],
"title": "Log Level",
"type": "string"
},
"max_queue_size": {
"default": 10000,
"description": "Maximum in-memory queue size for async processing",
"minimum": 1,
"title": "Max Queue Size",
"type": "integer"
},
"processors": {
"description": "Processor plugins to use (by name)",
"items": {
"type": "string"
},
"title": "Processors",
"type": "array"
},
"protected_levels": {
"description": "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).",
"items": {
"type": "string"
},
"title": "Protected Levels",
"type": "array"
},
"protected_queue_size": {
"anyOf": [
{
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Protected queue capacity in entries; None uses default derivation",
"title": "Protected Queue Size"
},
"redaction_fail_mode": {
"default": "warn",
"description": "Behavior when _apply_redactors() catches an unexpected exception: 'open' passes original event, 'closed' drops the event, 'warn' (default) passes event but emits diagnostic warning",
"enum": [
"open",
"closed",
"warn"
],
"title": "Redaction Fail Mode",
"type": "string"
},
"redaction_max_depth": {
"anyOf": [
{
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": 6,
"description": "Optional max depth guardrail for nested redaction",
"title": "Redaction Max Depth"
},
"redaction_max_keys_scanned": {
"anyOf": [
{
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": 5000,
"description": "Optional max keys scanned guardrail for redaction",
"title": "Redaction Max Keys Scanned"
},
"redactors": {
"description": "Redactor plugins to use (by name); defaults to ['url_credentials'] for secure defaults; set to [] to disable all redaction",
"items": {
"type": "string"
},
"title": "Redactors",
"type": "array"
},
"redactors_order": {
"description": "Ordered list of redactor plugin names to apply",
"items": {
"type": "string"
},
"title": "Redactors Order",
"type": "array"
},
"resource_pool_acquire_timeout_seconds": {
"default": 2.0,
"description": "Default acquire timeout for pools",
"exclusiveMinimum": 0.0,
"title": "Resource Pool Acquire Timeout Seconds",
"type": "number"
},
"resource_pool_max_size": {
"default": 8,
"description": "Default max size for resource pools",
"minimum": 1,
"title": "Resource Pool Max Size",
"type": "integer"
},
"sensitive_fields_policy": {
"description": "Optional list of dotted paths for sensitive fields policy; warning if no redactors configured",
"items": {
"type": "string"
},
"title": "Sensitive Fields Policy",
"type": "array"
},
"serialize_in_flush": {
"default": false,
"description": "If True, pre-serialize envelopes once during flush and pass SerializedView to sinks that support write_serialized",
"title": "Serialize In Flush",
"type": "boolean"
},
"shutdown_timeout_seconds": {
"default": 3.0,
"description": "Maximum time to flush on shutdown signals",
"exclusiveMinimum": 0.0,
"title": "Shutdown Timeout Seconds",
"type": "number"
},
"signal_handler_enabled": {
"default": true,
"description": "Install signal handlers for SIGTERM/SIGINT to enable graceful drain",
"title": "Signal Handler Enabled",
"type": "boolean"
},
"sink_circuit_breaker_enabled": {
"default": false,
"description": "Enable circuit breaker for sink fault isolation",
"title": "Sink Circuit Breaker Enabled",
"type": "boolean"
},
"sink_circuit_breaker_failure_threshold": {
"default": 5,
"description": "Number of consecutive failures before opening circuit",
"minimum": 1,
"title": "Sink Circuit Breaker Failure Threshold",
"type": "integer"
},
"sink_circuit_breaker_fallback_sink": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name of fallback sink to route events to when a circuit breaker opens. Must match a configured sink name. None means silent skip (default).",
"title": "Sink Circuit Breaker Fallback Sink"
},
"sink_circuit_breaker_recovery_timeout_seconds": {
"default": 30.0,
"description": "Seconds to wait before probing a failed sink",
"exclusiveMinimum": 0.0,
"title": "Sink Circuit Breaker Recovery Timeout Seconds",
"type": "number"
},
"sink_concurrency": {
"default": 1,
"description": "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.",
"minimum": 1,
"title": "Sink Concurrency",
"type": "integer"
},
"sink_parallel_writes": {
"default": false,
"description": "Write to multiple sinks in parallel instead of sequentially",
"title": "Sink Parallel Writes",
"type": "boolean"
},
"sinks": {
"description": "Sink plugins to use (by name); falls back to env-based default when empty",
"items": {
"type": "string"
},
"title": "Sinks",
"type": "array"
},
"strict_envelope_mode": {
"default": false,
"description": "If True, drop emission when envelope cannot be produced; otherwise fallback to best-effort serialization with diagnostics",
"title": "Strict Envelope Mode",
"type": "boolean"
},
"worker_count": {
"default": 1,
"description": "Number of worker tasks for flush processing",
"minimum": 1,
"title": "Worker Count",
"type": "integer"
}
},
"title": "CoreSettings",
"type": "object"
}
SecuritySettings
{
"$defs": {
"AccessControlSettings": {
"description": "Settings for access control and authorization.",
"properties": {
"allow_anonymous_read": {
"default": false,
"description": "Permit read access without authentication (discouraged)",
"title": "Allow Anonymous Read",
"type": "boolean"
},
"allow_anonymous_write": {
"default": false,
"description": "Permit write access without authentication (never recommended)",
"title": "Allow Anonymous Write",
"type": "boolean"
},
"allowed_roles": {
"description": "List of roles granted access to protected operations",
"items": {
"type": "string"
},
"title": "Allowed Roles",
"type": "array"
},
"auth_mode": {
"default": "token",
"description": "Authentication mode used by integrations (library-agnostic)",
"enum": [
"none",
"basic",
"token",
"oauth2"
],
"title": "Auth Mode",
"type": "string"
},
"enabled": {
"default": true,
"description": "Enable access control checks across the system",
"title": "Enabled",
"type": "boolean"
},
"require_admin_for_sensitive_ops": {
"default": true,
"description": "Require admin role for sensitive or destructive operations",
"title": "Require Admin For Sensitive Ops",
"type": "boolean"
}
},
"title": "AccessControlSettings",
"type": "object"
},
"EncryptionSettings": {
"description": "Settings controlling encryption for sensitive data and transport.\n\nThis model is intentionally conservative with defaults matching\nenterprise expectations.",
"properties": {
"algorithm": {
"default": "AES-256",
"description": "Primary encryption algorithm",
"enum": [
"AES-256",
"ChaCha20-Poly1305",
"AES-128"
],
"title": "Algorithm",
"type": "string"
},
"enabled": {
"default": true,
"description": "Enable encryption features",
"title": "Enabled",
"type": "boolean"
},
"env_var_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Environment variable holding key material",
"title": "Env Var Name"
},
"key_file_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Filesystem path to key material",
"title": "Key File Path"
},
"key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Key identifier for KMS/Vault sources",
"title": "Key Id"
},
"key_source": {
"anyOf": [
{
"enum": [
"env",
"file",
"kms",
"vault"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source for key material",
"title": "Key Source"
},
"min_tls_version": {
"default": "1.2",
"description": "Minimum TLS version for transport",
"enum": [
"1.2",
"1.3"
],
"title": "Min Tls Version",
"type": "string"
},
"rotate_interval_days": {
"default": 90,
"description": "Recommended key rotation interval",
"minimum": 0,
"title": "Rotate Interval Days",
"type": "integer"
}
},
"title": "EncryptionSettings",
"type": "object"
}
},
"description": "Aggregated security settings for the library.",
"properties": {
"access_control": {
"$ref": "#/$defs/AccessControlSettings",
"description": "Authentication/authorization and role-based access control"
},
"encryption": {
"$ref": "#/$defs/EncryptionSettings",
"description": "Cryptography, key management, and data protection settings"
}
},
"title": "SecuritySettings",
"type": "object"
}
ObservabilitySettings
{
"$defs": {
"AlertingSettings": {
"properties": {
"enabled": {
"default": false,
"description": "Enable emitting alerts from the logging pipeline",
"title": "Enabled",
"type": "boolean"
},
"min_severity": {
"default": "ERROR",
"description": "Minimum alert severity to emit (filter threshold)",
"enum": [
"INFO",
"WARNING",
"ERROR",
"CRITICAL"
],
"title": "Min Severity",
"type": "string"
}
},
"title": "AlertingSettings",
"type": "object"
},
"LoggingSettings": {
"properties": {
"format": {
"default": "json",
"description": "Output format for logs (machine-friendly JSON or text)",
"enum": [
"json",
"text"
],
"title": "Format",
"type": "string"
},
"include_correlation": {
"default": true,
"description": "Include correlation IDs and trace/span metadata in logs",
"title": "Include Correlation",
"type": "boolean"
},
"sampling_rate": {
"default": 1.0,
"description": "DEPRECATED: Use core.filters=['sampling'] with filter_config.sampling instead. Log sampling probability in range 0.0\u20131.0.",
"maximum": 1.0,
"minimum": 0.0,
"title": "Sampling Rate",
"type": "number"
}
},
"title": "LoggingSettings",
"type": "object"
},
"MetricsSettings": {
"properties": {
"enabled": {
"default": false,
"description": "Enable internal metrics collection/export",
"title": "Enabled",
"type": "boolean"
},
"exporter": {
"default": "prometheus",
"description": "Metrics exporter to use ('prometheus' or 'none')",
"enum": [
"prometheus",
"none"
],
"title": "Exporter",
"type": "string"
},
"port": {
"default": 8000,
"description": "TCP port for metrics exporter",
"maximum": 65535,
"minimum": 1,
"title": "Port",
"type": "integer"
}
},
"title": "MetricsSettings",
"type": "object"
},
"MonitoringSettings": {
"properties": {
"enabled": {
"default": false,
"description": "Enable health/monitoring checks and endpoints",
"title": "Enabled",
"type": "boolean"
},
"endpoint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Monitoring endpoint URL",
"title": "Endpoint"
}
},
"title": "MonitoringSettings",
"type": "object"
},
"TracingSettings": {
"properties": {
"enabled": {
"default": false,
"description": "Enable distributed tracing features",
"title": "Enabled",
"type": "boolean"
},
"provider": {
"default": "otel",
"description": "Tracing backend provider ('otel' or 'none')",
"enum": [
"otel",
"none"
],
"title": "Provider",
"type": "string"
},
"sampling_rate": {
"default": 0.1,
"description": "Trace sampling probability in range 0.0\u20131.0",
"maximum": 1.0,
"minimum": 0.0,
"title": "Sampling Rate",
"type": "number"
}
},
"title": "TracingSettings",
"type": "object"
}
},
"properties": {
"alerting": {
"$ref": "#/$defs/AlertingSettings",
"description": "Alerting configuration"
},
"logging": {
"$ref": "#/$defs/LoggingSettings",
"description": "Logging output format and correlation settings"
},
"metrics": {
"$ref": "#/$defs/MetricsSettings",
"description": "Metrics configuration (exporter and port)"
},
"monitoring": {
"$ref": "#/$defs/MonitoringSettings",
"description": "Monitoring configuration (health/endpoint)"
},
"tracing": {
"$ref": "#/$defs/TracingSettings",
"description": "Tracing configuration"
}
},
"title": "ObservabilitySettings",
"type": "object"
}
PluginsSettings
{
"description": "Settings controlling plugin behavior.",
"properties": {
"allow_external": {
"default": false,
"description": "Allow loading plugins from entry points (security risk)",
"title": "Allow External",
"type": "boolean"
},
"allowlist": {
"description": "If non-empty, only these plugin names are allowed",
"items": {
"type": "string"
},
"title": "Allowlist",
"type": "array"
},
"denylist": {
"description": "Plugin names to block from loading",
"items": {
"type": "string"
},
"title": "Denylist",
"type": "array"
},
"enabled": {
"default": true,
"description": "Enable plugin loading",
"title": "Enabled",
"type": "boolean"
},
"validation_mode": {
"default": "disabled",
"description": "Plugin validation mode: disabled, warn, or strict",
"title": "Validation Mode",
"type": "string"
}
},
"title": "PluginsSettings",
"type": "object"
}
LogEnvelope Schema
LogEnvelope v1.x (from file)
{
"$id": "https://fapilog.dev/schemas/log_envelope_v1.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"description": "Canonical log schema v1.1 with semantic field groupings: context (request/trace identifiers), diagnostics (runtime/operational data), and data (user-provided structured data).",
"properties": {
"log": {
"additionalProperties": true,
"properties": {
"context": {
"additionalProperties": true,
"description": "Request/trace context - identifies WHO and WHAT request. message_id uniquely identifies each log entry; correlation_id is always present (null when no correlation context is active).",
"properties": {
"correlation_id": {
"description": "Shared identifier across related log entries. Always present; null when no correlation context is active.",
"type": [
"string",
"null"
]
},
"message_id": {
"description": "Unique identifier for each log entry (always present)",
"type": "string"
},
"request_id": {
"type": "string"
},
"span_id": {
"type": "string"
},
"tenant_id": {
"type": "string"
},
"trace_id": {
"type": "string"
},
"user_id": {
"type": "string"
}
},
"required": [
"message_id",
"correlation_id"
],
"type": "object"
},
"data": {
"additionalProperties": true,
"description": "User-provided structured data from log call extra args",
"type": "object"
},
"diagnostics": {
"additionalProperties": true,
"description": "Runtime/operational context - identifies WHERE and system state",
"properties": {
"env": {
"type": "string"
},
"exception": {
"type": "object"
},
"host": {
"type": "string"
},
"pid": {
"type": "integer"
},
"python": {
"type": "string"
},
"service": {
"type": "string"
}
},
"type": "object"
},
"level": {
"description": "Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL",
"type": "string"
},
"logger": {
"description": "Logger name",
"type": "string"
},
"message": {
"description": "Human-readable log message",
"type": "string"
},
"tags": {
"items": {
"type": "string"
},
"type": "array"
},
"timestamp": {
"description": "RFC3339 UTC timestamp with Z suffix and millisecond precision",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{3})?Z$",
"type": "string"
}
},
"required": [
"timestamp",
"level",
"message",
"context",
"diagnostics",
"data"
],
"type": "object"
},
"schema_version": {
"const": "1.1",
"type": "string"
}
},
"required": [
"schema_version",
"log"
],
"title": "Fapilog Log Envelope v1.1",
"type": "object"
}