File log output

Opt-in file output handler for Piko's logger, with built-in size-based rotation, gzip compression of rotated files, and configurable JSON or pretty-text format.

Overview

This output writes structured log entries to a path on disk and rotates the file once it reaches 10 MB, keeping up to 3 compressed backups for 7 days. A single Enable call wires the rotating, compressing file output into the global logger. There is no provider to register, no struct to hold, and no piko.With* step. The AsJSON flag selects between JSON output (via slog.NewJSONHandler) and a non-coloured pretty handler for human-readable text logs.

The output reuses Piko's own machinery instead of a third-party library. The rotation and gzip compression writer, the shared pretty and JSON handlers, and the sandboxed filesystem all come from Piko internals, so behaviour matches the rest of the logger. Rotation runs in a background goroutine that compresses old backups and removes expired ones. A panic recovery wraps the goroutine, and compression writes to a temporary file before an atomic rename, so a crash mid-rotation does not corrupt a backup.

The package is opt-in. If you do not need file output, omitting the import keeps the rotation and compression code out of the binary. The package needs no build tag and no CGO, so it runs in interpreted dev-i mode as well as compiled builds.

Enable returns no value. The handler logs failures (typically a non-writable directory) as a warning and skips silently instead of failing startup. The handler is safe for concurrent use.

Requirements

Write permission on the directory containing Config.Path. The rotator creates the directory tree if it does not exist; it does not require a pre-existing directory.
A long-lived context.Context to control the rotator's background goroutine, typically the application's root context.

Configuration

import (
    "context"
    "log/slog"

    "piko.sh/piko/wdk/logger/logger_output_file"
)

logger_output_file.Enable(ctx, "app-file", logger_output_file.Config{
    Path:   "/var/log/app/piko.log", // required; absolute or relative path to the log file
    Level:  slog.LevelInfo,          // optional; minimum slog level (default LevelInfo)
    AsJSON: true,                    // optional; JSON output instead of pretty text
})

The path resolves to an absolute path internally, so a relative Path works too. The rotator runs every file operation through a Piko safedisk sandbox scoped to the log directory. The sandbox creates the directory in read-write mode and confines reads, writes, and backup cleanup to that one directory.

Default handler replacement

Piko starts with a default pretty handler on stdout. The first explicit handler added through the logger state replaces that default. Calling Enable therefore moves logging off stdout and into the file. To keep both stdout and file output, add a console output as well so the file handler joins it instead of replacing it.

Set the PIKO_DISABLE_CONSOLE_LOG environment variable to true for no default handler at startup.

Shutdown

Enable registers the file as a closer on the logger state. The logger shutdown function flushes and closes the file. Cancelling the supplied context does not close the file. It only stops the background cleanup goroutine. Writes go straight to the file with no in-memory buffer, so a missed close loses no pending data. For a clean close, drive the logger shutdown function during application shutdown.

Bootstrap

There is no separate bootstrap step. Call Enable during startup, before the application starts emitting logs. It registers the handler and returns no value to capture. The handler stays registered for the lifetime of the process.

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    logger_output_file.Enable(ctx, "app-file", logger_output_file.Config{
        Path:   "/var/log/app/piko.log",
        AsJSON: true,
    })

    // ...rest of startup
}