Plugin Development

Extend fapilog to send logs anywhere, add context automatically, or mask custom secrets.

Plugin Development

• Plugin Author Quickstart
  • Overview
  • Minimal Sink Plugin
  • Registering via Entry Points
  • Plugin Validation Modes
  • Plugin Protocols
  • Security Considerations
  • Testing Your Plugin
  • Example: HTTP Webhook Sink
  • Example: Sampling Filter
  • Plugin Metadata (Optional)
  • Next Steps
• Authoring Fapilog Plugins
  • Entry Points
  • Naming Convention
  • PLUGIN_METADATA
  • API Versioning
  • Protocols
  • Configuration Pattern
• Plugin Contracts and API Versioning
  • Public Protocols
  • Plugin API Version
  • Plugin Metadata Keys
  • Load-time Enforcement
  • Plugin min_fapilog_version Policy
  • Backward Compatibility
• Redactors
  • Stage Placement and Lifecycle
  • Built-in Redactors
  • Configuration
  • Authoring Custom Redactors
  • Diagnostics and Metrics
  • Integration Order
• Sinks
  • Implementing a sink
  • Registering a sink
  • Built-in sinks (code-supported)
  • Usage
  • Optional: write_serialized fast path
• Enrichers
  • Implementing an enricher
  • Registering an enricher
  • Built-in enrichers
  • Usage
  • Configuration Pattern
  • Kubernetes Enricher
• Filters
  • Sampling Filters
  • Rate Limiting Filter
  • Implementing a filter
  • Registering a filter
  • Contract
  • Built-in filters
  • Configuration
• Processors
  • When to use processors
  • Implementing a processor
  • SizeGuardProcessor
  • Built-in processors
  • Registration
  • Configuration and order
• Plugin Testing
  • Installation
  • Quick Start
  • Config Validation
  • Mock Plugins
  • Validators
  • pytest Fixtures
  • Benchmarks
  • CI/CD Integration
• Plugin Configuration
  • Selecting Plugins
  • Per-Plugin Configuration
  • Loader Behavior
  • Integrity Wrapping
• Plugin Health Checks
  • Checking health from code
  • Implementing in a custom plugin
• Plugin Error Handling
  • Core Principle: Contain Errors (With Sink Exception)
  • When Raising Is Acceptable
  • Diagnostics API (rate-limited)
  • Patterns by Plugin Type
  • What Fapilog Does If You Raise
  • Health Checks Reflecting Error State
  • Retry for Transient Failures
  • Quick Reference

See also: Integration Patterns for reusable sink and processor patterns.

Overview

Plugins let you customize fapilog without forking:

• Send logs anywhere - Build a sink for your internal system, a new cloud provider, or a message queue

• Add context automatically - Enrich every log with deployment info, feature flags, or tenant IDs

• Mask your secrets - Create redactors for proprietary data formats or company-specific PII

• Control log volume - Filter out noise, sample high-frequency events, or rate-limit by key

Plugin Types

Sinks

Send logs where you need them—your database, a message queue, a custom API, or a cloud service fapilog doesn’t support yet.

Enrichers

Add context to every log automatically. Examples: deployment version, feature flags, tenant ID, or Kubernetes pod info.

Redactors

Mask sensitive data before it reaches your sinks. Create patterns for company-specific secrets, custom PII formats, or proprietary data.

Filters

Control what gets logged. Drop debug logs in production, sample high-frequency events, or rate-limit noisy sources.

Processors

Transform logs before they’re sent. Compress for cost savings, encrypt for compliance, or reformat for your aggregation tool.

Error Handling

Handle plugin failures gracefully. Learn how to contain errors so a broken sink doesn’t crash your app.

Getting Started

• Quickstart - Create your first plugin in 10 minutes

• Plugin Authoring Guide - Learn how to create plugins

• Contracts and Versioning - Understand plugin compatibility

• Redaction Plugins - Data security and compliance

• Plugin Testing - Validate contracts, benchmarks, and fixtures

---

This section provides comprehensive guidance for plugin development and integration.