echo

README

relicora-echo

relicora-echo is a lightweight Go logging library with per-level file output, standard logger compatibility, and configurable log rotation.

Features

• Hierarchical log levels: FATAL, ERROR, WARN, INFO, DEBUG, TRACE
• Separate file targets for each log level
• Fallback to a shared output file for levels without their own path
• Compatible with Go's standard log.Logger
• Optional rotation by time, by size, or both
• Midnight rollover for size-based rotation using the previous day in the archive name
• Optional retention of rotated files for a configurable number of days
• Safe close semantics for file handles and rotation goroutines

Installation

go get github.com/Relicora/relicora-echo@v0.4.0

Import the package in your code:

import "github.com/Relicora/relicora-echo"

Usage

Create a logger with the desired configuration and call methods for the desired log level.

package main

import (
    "github.com/Relicora/relicora-echo"
)

func main() {
    cfg := echo.Config{
        LogLevel:        "INFO",
        OutputPath:      "logs/output.log",
        ErrorOutputPath: "logs/error.log",
        WarnOutputPath:  "logs/warn.log",
        InfoOutputPath:  "logs/info.log",
        DebugOutputPath: "logs/debug.log",
        TraceOutputPath: "logs/trace.log",
    }

    logger := echo.New(cfg)
    defer logger.Close()

    logger.Info("Application started")
    logger.Warn("This is a warning")
    logger.Error("Something went wrong")
}

Using rotation

You can choose how logs should rotate by setting RotationMode. Supported values are:

• none - disable rotation
• time - rotate by schedule
• size - rotate when the current file exceeds MaxSizeBytes
• time-and-size - rotate by either condition

cfg := echo.Config{
    LogLevel:      "INFO",
    OutputPath:    "logs/output.log",
    RotationMode:  echo.RotationModeTime,
    RotateDaily:   true,
    RotationTime:  "02:00", // rotate at 02:00 local time each day
}

logger := echo.New(cfg)
defer logger.Close()

For size-based rotation:

cfg := echo.Config{
    LogLevel:      "INFO",
    OutputPath:    "logs/output.log",
    RotationMode:  echo.RotationModeSize,
    MaxSizeBytes:  10 * 1024 * 1024,
    RetentionDays: 30,
}

When a rotation happens, the current log file is archived with a name like: output-2026-08-01-0001.log. For midnight rollover in size-based mode, the archive uses the previous day in the name, for example output-2026-07-31-0002.log.

Configuration

Config fields:

• LogLevel string - minimum log level to output. Allowed values: FATAL, ERROR, WARN, INFO, DEBUG, TRACE. Defaults to INFO if missing or unknown.
• OutputPath string - shared base log file path used when specific per-level path is not provided.
• FatalOutputPath string - optional path for fatal logs.
• ErrorOutputPath string - optional path for error logs.
• WarnOutputPath string - optional path for warning logs.
• InfoOutputPath string - optional path for info logs.
• DebugOutputPath string - optional path for debug logs.
• TraceOutputPath string - optional path for trace logs.
• RotateDaily bool - legacy switch for time-based rotation support.
• RotationTime string - local rotation time in HH:MM format, for example 23:30.
• RotationMode string - rotation strategy: none, time, size, or time-and-size.
• MaxSizeBytes int64 - maximum size of the active log file before a size-based rotation occurs.
• RetentionDays int - number of days to keep rotated files before they are removed.

Logger methods

The logger supports standard methods for each level:

• Fatal, Fatalf, Fatalln
• Error, Errorf, Errorln
• Warn, Warnf, Warnln
• Info, Infof, Infoln
• Print, Printf, Println
• Debug, Debugf, Debugln
• Trace, Tracef, Traceln

The Print* methods are treated as INFO-level output.

Standard logger compatibility

The embedded *log.Logger is available at logger.Logger, so existing code that expects a standard Go logger may use it directly.

stdLogger := logger.Logger
stdLogger.Print("standard log")

Shutdown

Always call logger.Close() before exiting your application to flush and close file handles cleanly.

defer logger.Close()

Testing

Run the package tests with:

go test ./...

The library includes tests for:

• log level parsing and behavior
• per-level file output
• standard logger compatibility
• time-based rotation scheduling
• size-based rotation behavior
• midnight rollover naming for size-based rotation
• retention cleanup of old rotated files

License

This project is licensed under the terms of the MIT License.

Documentation

Index

• Constants
• type Config
• type Logger
  • func New(cfg Config) *Logger
  • func (l *Logger) Close() error
  • func (l *Logger) Debug(v ...any)
  • func (l *Logger) Debugf(format string, v ...any)
  • func (l *Logger) Debugln(v ...any)
  • func (l *Logger) Error(v ...any)
  • func (l *Logger) Errorf(format string, v ...any)
  • func (l *Logger) Errorln(v ...any)
  • func (l *Logger) Fatal(v ...any)
  • func (l *Logger) Fatalf(format string, v ...any)
  • func (l *Logger) Fatalln(v ...any)
  • func (l *Logger) Info(v ...any)
  • func (l *Logger) Infof(format string, v ...any)
  • func (l *Logger) Infoln(v ...any)
  • func (l *Logger) Print(v ...any)
  • func (l *Logger) Printf(format string, v ...any)
  • func (l *Logger) Println(v ...any)
  • func (l *Logger) Trace(v ...any)
  • func (l *Logger) Tracef(format string, v ...any)
  • func (l *Logger) Traceln(v ...any)
  • func (l *Logger) Warn(v ...any)
  • func (l *Logger) Warnf(format string, v ...any)
  • func (l *Logger) Warnln(v ...any)

Constants

const (
	FATAL = "FATAL"
	ERROR = "ERROR"
	WARN  = "WARN"
	INFO  = "INFO"
	DEBUG = "DEBUG"
	TRACE = "TRACE"
)

const (
	RotationModeNone        = "none"
	RotationModeTime        = "time"
	RotationModeSize        = "size"
	RotationModeTimeAndSize = "time-and-size"
)

Types

type Config

type Config struct {
	LogLevel        string
	OutputPath      string
	FatalOutputPath string
	ErrorOutputPath string
	WarnOutputPath  string
	InfoOutputPath  string
	DebugOutputPath string
	TraceOutputPath string

	RotateDaily  bool
	RotationTime string // format "15:04", local system timezone

	RotationMode  string // "none", "time", "size", "time-and-size"
	MaxSizeBytes  int64
	RetentionDays int
}

type Logger

type Logger struct {
	*log.Logger
	// contains filtered or unexported fields
}

func New

func New(cfg Config) *Logger

New creates a Logger configured with the provided settings.

If cfg.RotateDaily is true and cfg.RotationTime is set, the logger starts a daily rotation goroutine that renames current log files at the configured local time.

func (*Logger) Close

func (l *Logger) Close() error

Close stops any active rotation goroutine and closes all open log files.

It returns the first error encountered while closing files, if any.

func (*Logger) Debug

func (l *Logger) Debug(v ...any)

Debug logs a message at DEBUG level if the current log level allows it.

func (*Logger) Debugf

func (l *Logger) Debugf(format string, v ...any)

Debugf formats and logs a DEBUG-level message when enabled.

func (*Logger) Debugln

func (l *Logger) Debugln(v ...any)

Debugln logs a DEBUG-level message with a newline when enabled.

func (*Logger) Error

func (l *Logger) Error(v ...any)

Error logs a message at ERROR level if the current log level allows it.

func (*Logger) Errorf

func (l *Logger) Errorf(format string, v ...any)

Errorf formats and logs an ERROR-level message when enabled.

func (*Logger) Errorln

func (l *Logger) Errorln(v ...any)

Errorln logs an ERROR-level message with a newline when enabled.

func (*Logger) Fatal

func (l *Logger) Fatal(v ...any)

Fatal logs a message at FATAL level and exits the application.

func (*Logger) Fatalf

func (l *Logger) Fatalf(format string, v ...any)

Fatalf formats and logs a message at FATAL level before exiting the application.

func (*Logger) Fatalln

func (l *Logger) Fatalln(v ...any)

Fatalln logs a message at FATAL level with a newline and exits the application.

func (*Logger) Info

func (l *Logger) Info(v ...any)

Info logs a message at INFO level if the current log level allows it.

func (*Logger) Infof

func (l *Logger) Infof(format string, v ...any)

Infof formats and logs an INFO-level message when enabled.

func (*Logger) Infoln

func (l *Logger) Infoln(v ...any)

Infoln logs an INFO-level message with a newline when enabled.

func (*Logger) Print

func (l *Logger) Print(v ...any)

Print writes a message through the embedded standard logger at INFO level.

func (*Logger) Printf

func (l *Logger) Printf(format string, v ...any)

Printf formats and writes a message through the embedded standard logger at INFO level.

func (*Logger) Println

func (l *Logger) Println(v ...any)

Println writes a message through the embedded standard logger with a newline at INFO level.

func (*Logger) Trace

func (l *Logger) Trace(v ...any)

Trace logs a message at TRACE level if the current log level allows it.

func (*Logger) Tracef

func (l *Logger) Tracef(format string, v ...any)

Tracef formats and logs a TRACE-level message when enabled.

func (*Logger) Traceln

func (l *Logger) Traceln(v ...any)

Traceln logs a TRACE-level message with a newline when enabled.

func (*Logger) Warn

func (l *Logger) Warn(v ...any)

Warn logs a message at WARN level if the current log level allows it.

func (*Logger) Warnf

func (l *Logger) Warnf(format string, v ...any)

Warnf formats and logs a WARN-level message when enabled.

func (*Logger) Warnln

func (l *Logger) Warnln(v ...any)

Warnln logs a WARN-level message with a newline when enabled.