Documentation
¶
Overview ¶
Package rlog offers a small, production-ready log writer that embraces stdlib ideals: simple, focused, and composable.
Current extension:
- Writer implements buffered, size-based log rotation with optional age-based flushing—ideal for long-running services that want durable logs without pulling in a full logging framework.
Writer usage:
w, err := rlog.NewWriter(rlog.Config{
DirPath: "./logs", // required - will be created if missing
MaxFileSize: 512 << 20, // 512 MB before rotation (optional)
MaxBufSize: 8 * 1024, // 8 KB in-memory buffer (optional)
MaxBufAge: 5 * time.Second, // flush after 5 s (optional)
})
if err != nil {
log.Fatalf("rlog: %v", err)
}
defer w.Close()
// plain io.Writer usage
log.SetOutput(w)
log.Println("hello, rotating world")
Manual flush / error check:
if err := w.Flush(); err != nil {
log.Printf("flush failed: %v", err)
}
if err := w.Error(); err != nil {
log.Printf("writer is unhealthy: %v", err)
}
Internals & caveats:
- Rotation renames the active file to a timestamped `<ts>.log` and re-creates `latest.log` atomically. A lightweight file-lock prevents concurrent rotations across processes.
- A single Writer should be used per directory per process; multiple processes may safely share the same directory.
Index ¶
Constants ¶
const ( DefaultMaxFileSize = 256 * 1024 * 1024 // 256 MB DefaultMaxBufSize = 4096 // 4 KB DefaultMaxBufAge = 15 * time.Second // 15 seconds )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶ added in v0.0.4
type Config struct {
DirPath string // Directory path where log files are stored. Created if it does not exist.
MaxFileSize int64 // Soft max size of a log file before rotation occurs. Default is 256 MB.
MaxBufSize int // Soft max size of the buffer before flushing to disk. Default is 4 KB.
MaxBufAge time.Duration // Max age of the buffer before flushing to disk. Default is 15 seconds. Negative to disable.
}
Config holds configuration options for Writer.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer implements io.Writer for buffered log writing with automatic file rotation. If a write operation returns an error, no further data is accepted and subsequent function calls will return the error. Same as seen in various standard library packages.
WARNING: Only a single Writer should be used per directory per process. Multiple process instances writing to the same directory is fine, Multiple Writer instances within the same process doing so is not.
func NewWriter ¶ added in v0.0.4
NewWriter creates and initializes a new Writer for the specified directory. Creating the directory if it does not already exist. Additional options can be provided to customize the Writer's behavior.
func (*Writer) Close ¶
Close flushes the Writer, age trigger goroutine, and open file. It should be called when the Writer is no longer needed.
func (*Writer) Error ¶ added in v0.0.4
Error returns the last error encountered by the Writer. If no error has occurred, it returns nil.
func (*Writer) Flush ¶
Flush appends [Writer.buf] to 'DirPath/latest.log', rotates first if appending would result in latest.log exceeding MaxFileSize, then clears [Writer.buf]. Returns an error if the write, file sync, or rotation fails.
Flushing happens automatically during Writer.Write when [Writer.buf] exceeds MaxBufSize.
Source Files