Rotating File Sink

Write logs to disk with size/time rotation.

Quick Start (Convenience Function)

from fapilog import get_logger
from fapilog.sinks import rotating_file

# Simple file logging
logger = get_logger(sinks=[rotating_file("logs/app.log")])

# With rotation and retention
logger = get_logger(
    sinks=[
        rotating_file(
            "logs/app.log",
            rotation="10 MB",
            retention=7,
            compression=True,
        )
    ]
)

Enable via environment

export FAPILOG_FILE__DIRECTORY=/var/log/myapp
export FAPILOG_FILE__MAX_BYTES="10 MB"
export FAPILOG_FILE__MAX_FILES=5
export FAPILOG_FILE__COMPRESS_ROTATED=true
# Optional time-based rotation
export FAPILOG_FILE__INTERVAL_SECONDS="daily"

"daily"/"hourly"/"weekly" are fixed intervals (e.g., 24 hours), not wall-clock boundaries.

Programmatic settings

from fapilog import Settings, get_logger
from fapilog.core.settings import RotatingFileSettings

settings = Settings(
    sink_config=Settings.SinkConfig(
        rotating_file=RotatingFileSettings(
            directory="logs",
            filename_prefix="app",
            max_bytes="10 MB",
            max_files=7,
            compress_rotated=True,
        )
    )
)
logger = get_logger(settings=settings)
logger.info("configured via Settings")

Usage

from fapilog import get_logger

logger = get_logger()
logger.info("to file", event="startup")

Direct Class Usage

For full control, instantiate the sink class directly:

from pathlib import Path
from fapilog.plugins.sinks.rotating_file import RotatingFileSink, RotatingFileSinkConfig

config = RotatingFileSinkConfig(
    directory=Path("./logs"),
    filename_prefix="app",
    max_bytes=10_000_000,  # 10 MB
    max_files=5,
    compress_rotated=True,
)
sink = RotatingFileSink(config)

Config fields: directory, filename_prefix, mode, max_bytes, interval_seconds, max_files, max_total_bytes, compress_rotated, strict_envelope_mode.

Migration

See docs/guides/migration-file-rotation.md for a before/after conversion from RotatingFileSinkConfig to the rotating_file() convenience factory.

What to expect

• Files named like fapilog-20250111-120000.jsonl (or .log in text mode).

• Rotation by size (max_bytes) or interval; optional retention and compression.

Tips

• Ensure the directory exists and is writable by the app user.

• Set FAPILOG_FILE__MODE to json (default) for structured output.

• For containers, ensure volume mounts persist /var/log/myapp.