Metrics

Optional internal metrics for observability.

Enabling

Set core.enable_metrics=True (env: FAPILOG_CORE__ENABLE_METRICS=true). Metrics are recorded asynchronously; exporting is left to the application.

What is recorded

Events submitted/dropped
Queue high-watermark
Backpressure waits
Flush latency (per batch)
Sink errors
Priority queue evictions and drops

Prometheus Metrics Reference

Metric	Type	Labels	Description
`fapilog_events_submitted_total`	Counter	-	Events successfully enqueued
`fapilog_events_dropped_total`	Counter	`protected`	Events dropped due to backpressure
`fapilog_events_processed_total`	Counter	-	Events processed by workers
`fapilog_queue_high_watermark`	Gauge	-	Maximum queue depth observed
`fapilog_backpressure_waits_total`	Counter	-	Times backpressure was applied
`fapilog_flush_seconds`	Histogram	-	Batch flush latency
`fapilog_batch_size`	Histogram	-	Events per batch
`fapilog_sink_errors_total`	Counter	`sink`	Sink write failures
`fapilog_priority_evictions_total`	Counter	-	Evictions triggered by protected events
`fapilog_events_evicted_total`	Counter	`level`	Events evicted by log level
`fapilog_redacted_fields_total`	Counter	-	Total fields masked by redactors
`fapilog_policy_violations_total`	Counter	-	Policy violation flags from field_blocker
`fapilog_sensitive_fields_total`	Counter	-	Fields logged via `sensitive=`/`pii=` container
`fapilog_redaction_exceptions_total`	Counter	-	Redaction pipeline exceptions

Priority Queue Metrics

When using protected levels (default: ERROR, CRITICAL, FATAL), the queue tracks priority-based behavior:

# Priority protection effectiveness - how often eviction saved protected events
rate(fapilog_priority_evictions_total[5m])

# Protected events we failed to save (queue saturated with protected events)
rate(fapilog_events_dropped_total{protected="true"}[5m])

# What levels are being sacrificed to save errors?
topk(5, rate(fapilog_events_evicted_total[5m])) by (level)

# Ratio of protected vs unprotected drops
rate(fapilog_events_dropped_total{protected="true"}[5m])
  / rate(fapilog_events_dropped_total[5m])

Alerting on Protection Failures

# Alert when protected events are being dropped (queue saturated)
- alert: FapilogProtectedEventsDropped
  expr: rate(fapilog_events_dropped_total{protected="true"}[5m]) > 0
  for: 1m
  labels:
    severity: critical
  annotations:
    summary: "Protected log events being dropped - queue saturated"

Redaction Metrics

Redaction operational metrics are recorded automatically when core.enable_metrics=True. These counters track masking activity, policy enforcement, and pipeline health.

Metric	What It Tracks
`fapilog_redacted_fields_total`	Fields masked by any redactor (field_mask, regex_mask, string_truncate, etc.)
`fapilog_policy_violations_total`	Fields blocked by `field_blocker` (e.g., `body`, `payload`)
`fapilog_sensitive_fields_total`	Fields declared via `sensitive={}` or `pii={}` at log time
`fapilog_redaction_exceptions_total`	Unexpected exceptions in the redaction pipeline

PromQL Examples

# Redaction activity rate
rate(fapilog_redacted_fields_total[5m])

# Policy violations — are developers logging blocked fields?
rate(fapilog_policy_violations_total[5m])

# Sensitive container adoption — are developers using sensitive={}?
rate(fapilog_sensitive_fields_total[5m])

# Redaction pipeline health — any exceptions?
rate(fapilog_redaction_exceptions_total[5m])

Alerting on Redaction Issues

# Alert when redaction pipeline is throwing exceptions
- alert: FapilogRedactionExceptions
  expr: rate(fapilog_redaction_exceptions_total[5m]) > 0
  for: 1m
  labels:
    severity: warning
  annotations:
    summary: "Redaction pipeline exceptions detected"

# Alert on high policy violation rate (field_blocker blocking fields)
- alert: FapilogPolicyViolations
  expr: rate(fapilog_policy_violations_total[5m]) > 10
  for: 5m
  labels:
    severity: info
  annotations:
    summary: "High rate of policy violations — review blocked field usage"

System Metrics

System metrics (CPU usage, memory, disk I/O) are provided by the runtime_info enricher when the system extra is installed.

Platform Note: System metrics require psutil, which is only installed on Linux and macOS. On Windows, system metrics fields will not be populated.
# Linux/macOS - psutil installed, system metrics available
pip install fapilog[system]

# Windows - psutil not installed, system metrics unavailable
pip install fapilog[system]  # Installs fapilog but not psutil

Usage

from fapilog import Settings, get_logger

settings = Settings(core__enable_metrics=True)
logger = get_logger(settings=settings)
logger.info("metrics enabled")

Expose or scrape metrics from your application using your preferred exporter; fapilog does not start an HTTP metrics server itself.