Documentation
¶
Overview ¶
Package file provides a file-based audit.Output implementation with automatic size-based rotation, backup retention, age-based cleanup, and optional gzip compression.
Construction ¶
Create a file output with New:
out, err := file.New(file.Config{
Path: "/var/log/audit/events.log",
MaxSizeMB: 100,
MaxBackups: 5,
MaxAgeDays: 30,
}, nil) // optional file.Metrics
The parent directory of [Config.Path] must exist before calling New; the file itself is created if it does not exist. Default permissions are 0600.
Rotation ¶
When the active log file exceeds [Config.MaxSizeMB], it is renamed with a timestamp suffix and a new file is opened. Old backups are pruned by count ([Config.MaxBackups]) and age ([Config.MaxAgeDays]). Compressed backups use gzip (enabled by default).
Recommended import alias:
import auditfile "github.com/axonops/go-audit/file"
Index ¶
Examples ¶
Constants ¶
const ( // MaxSizeMB is the maximum allowed value for [Config.MaxSizeMB]. // Values above this limit cause [New] to return an error // wrapping [audit.ErrConfigInvalid]. MaxSizeMB = 10_240 // 10 GB // MaxBackups is the maximum allowed value for [Config.MaxBackups]. // Values above this limit cause [New] to return an error // wrapping [audit.ErrConfigInvalid]. MaxBackups = 100 // MaxAgeDays is the maximum allowed value for [Config.MaxAgeDays]. // Values above this limit cause [New] to return an error // wrapping [audit.ErrConfigInvalid]. MaxAgeDays = 365 )
Variables ¶
This section is empty.
Functions ¶
func NewFactory ¶ added in v0.3.0
func NewFactory(fileMetrics Metrics) audit.OutputFactory
NewFactory returns an audit.OutputFactory that creates file outputs from YAML configuration with the provided file-specific metrics captured in the closure. Pass nil to disable file metrics.
Types ¶
type Config ¶
type Config struct {
// Path is the filesystem path for the audit log file. REQUIRED.
// Relative paths are resolved to absolute at construction time.
// The parent directory must exist when [New] is called.
Path string
// Permissions is the octal file mode string (e.g. "0600") applied
// to created files. Empty defaults to "0600" (owner read/write).
// Values granting group or world write access produce a slog
// warning. Values above 0o777 cause [New] to return an error;
// this error does not wrap [audit.ErrConfigInvalid].
Permissions string
// MaxSizeMB is the maximum size in megabytes of a single log file
// before rotation. Zero defaults to 100. Values above [MaxSizeMB]
// (10,240 = 10 GB) cause [New] to return an error wrapping
// [audit.ErrConfigInvalid].
MaxSizeMB int
// MaxBackups is the maximum number of rotated backup files to
// retain. Zero defaults to 5. Values above [MaxBackups] (100)
// cause [New] to return an error wrapping [audit.ErrConfigInvalid].
MaxBackups int
// MaxAgeDays is the maximum age in days of rotated backup files
// before deletion. Zero defaults to 30. Values above [MaxAgeDays]
// (365) cause [New] to return an error wrapping
// [audit.ErrConfigInvalid].
MaxAgeDays int
// Compress enables gzip compression of rotated backup files.
// When nil, defaults to true.
Compress *bool
}
Config holds configuration for Output.
type Metrics ¶
type Metrics interface {
// RecordFileRotation records that the file output rotated its
// active log file. The path argument is the absolute filesystem
// path of the file that was rotated. Implementations SHOULD NOT
// use this value as an unbounded metric label — it may expose
// infrastructure topology and cause cardinality explosion.
RecordFileRotation(path string)
}
Metrics is an optional interface for file-output-specific instrumentation. Pass an implementation to New to collect rotation telemetry. Pass nil to disable.
type Output ¶
type Output struct {
// contains filtered or unexported fields
}
Output writes serialised audit events to a file with automatic size-based rotation. It supports backup retention, age-based cleanup, and optional gzip compression.
Output is safe for concurrent use, including concurrent calls to Output.Write and Output.Close.
func New ¶
New creates a new Output from the given config. It validates the path, permissions, and parent directory existence. The fileMetrics parameter is optional (may be nil).
Unlike other output constructors (syslog, webhook, loki) which take *Config, New takes Config by value. This is intentional: file Config has no pointer fields, so the value copy prevents caller mutation without requiring an explicit defensive copy inside New.
Example ¶
package main
import (
"fmt"
"log"
"os"
"path/filepath"
"github.com/axonops/go-audit/file"
)
func main() {
// Create a file output with rotation for production use.
dir, err := os.MkdirTemp("", "audit-example-*")
if err != nil {
log.Fatal(err)
}
defer func() { _ = os.RemoveAll(dir) }()
out, err := file.New(file.Config{
Path: filepath.Join(dir, "audit.log"),
MaxSizeMB: 100,
MaxBackups: 5,
MaxAgeDays: 30,
Permissions: "0600",
}, nil)
if err != nil {
fmt.Println("create error:", err)
return
}
defer func() { _ = out.Close() }()
fmt.Println("file output created")
}
Output: file output created
func (*Output) Close ¶
Close closes the underlying file writer and marks the output as closed. Close is idempotent and safe for concurrent use with Output.Write.
func (*Output) DestinationKey ¶ added in v0.3.0
DestinationKey returns the absolute filesystem path, enabling duplicate destination detection via audit.DestinationKeyer.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
rotate
Package rotate provides a symlink-safe, permission-enforcing file writer with size-based rotation, backup retention, age-based cleanup, and optional gzip compression.
|
Package rotate provides a symlink-safe, permission-enforcing file writer with size-based rotation, backup retention, age-based cleanup, and optional gzip compression. |