README
¶
xlog
CLI and registry logging utilities with structured output and optional colorization.
This package provides a slog.Handler implementation aimed at command-line tools.
It supports CLI rendering with optional ANSI colors and an optional file-based
registry log destination for persisted application logs.
Purpose
xlog centralizes logging behavior for CLI applications.
It is built around a reusable LogHandler that can:
- emit formatted CLI logs,
- apply ANSI colors when the terminal supports them,
- write log records to a file registry,
- manage time format and timezone configuration,
- keep testable I/O boundaries via a small internal bridge.
The package is designed to provide predictable logger handling for command-line and service workflows.
Installation
Use go get to add the package:
go get github.com/AeonDigital/Go-Core/xlog@latest
Import it in your code:
import (
"log/slog"
"github.com/AeonDigital/Go-Core/xlog"
)
Basic usage
Create a handler and configure it for CLI and/or file registry logging:
handler := &xlog.LogHandler{
LogCLI: true,
LogCLILevel: xlog.LevelInfo,
LogCLIColors: true,
LogRegistry: true,
}
err := handler.CheckConfiguration("myapp", "app.log")
if err != nil {
panic(err)
}
logger := slog.New(handler)
logger.Info("starting application")
The handler supports:
- CLI output with time, level and message formatting,
- optional ANSI colors when terminal support is detected,
- optional log file registry writing,
- automatic fallback defaults for time format and file configuration.
Supported APIs
The package exposes the main logging interface and helpers:
xlog.LogHandler(*xlog.LogHandler).CheckConfiguration(appName, logFileName string) error(*xlog.LogHandler).Enabled(context.Context, slog.Level) bool(*xlog.LogHandler).Handle(context.Context, slog.Record) error(*xlog.LogHandler).WithAttrs([]slog.Attr) slog.Handler(*xlog.LogHandler).WithGroup(name string) slog.Handler
It also defines severity levels and a default CLI palette:
xlog.LevelAllxlog.LevelNonexlog.LevelInfoxlog.LevelWarnxlog.LevelError
External dependencies
xlog uses the Go standard library and one external Go module:
golang.org/x/term
It also depends on internal repository packages:
github.com/AeonDigital/Go-Core/xfsgithub.com/AeonDigital/Go-Core/xunitsgithub.com/AeonDigital/Go-Core/tools
No additional third-party logging libraries are required.
Documentation
¶
Index ¶
- Constants
- Variables
- type CLIColorPalette
- type LogHandler
- func (o *LogHandler) CheckConfiguration(logFileName string) error
- func (o *LogHandler) Enabled(_ context.Context, level slog.Level) bool
- func (o *LogHandler) Handle(_ context.Context, r slog.Record) error
- func (o *LogHandler) WithAttrs(attrs []slog.Attr) slog.Handler
- func (o *LogHandler) WithGroup(name string) slog.Handler
- type LogLevel
Constants ¶
const DefaultTimeFormat = "YYYY-MM-DD HH:mm:ss"
DefaultTimeFormat defines the layout string used for timestamp rendering.
const DefaultTimeZone = "UTC"
DefaultTimeZone defines the default fallback timezone configuration.
Variables ¶
var DefaultCLIPalette = &CLIColorPalette{
Debug: ansiCyan,
Info: ansiGreen,
Warn: ansiYellow,
Error: ansiRed,
DateTime: ansiGray,
}
DefaultCLIPalette provides the standard out-of-the-box color definitions for readable command line outputs.
Functions ¶
This section is empty.
Types ¶
type CLIColorPalette ¶
type CLIColorPalette struct {
Debug string `json:"debug"`
Info string `json:"info"`
Warn string `json:"warn"`
Error string `json:"error"`
DateTime string `json:"datetime"`
}
CLIColorPalette manages the specific ANSI string colors associated with each logging level and metadata element inside CLI environments.
type LogHandler ¶
type LogHandler struct {
TimeFormat string `json:"timeFormat"`
TimeZone string `json:"timeZone"`
UseTimeFormat string `json:"useTimeFormat"`
UseTimeZone *time.Location `json:"useTimeZone"`
LogCLI bool `json:"logCLI"`
LogCLILevel LogLevel `json:"logCLILevel"`
LogCLIColors bool `json:"logCLIColors"`
LogCLIColorPallete *CLIColorPalette `json:"logCLIColorPallete"`
LogRegistry bool `json:"logRegistry"`
LogRegistryLevel LogLevel `json:"logRegistryLevel"`
LogRegistryDirPath string `json:"logRegistryFilePath"`
LogRegistryFileName string `json:"logRegistryFileName"`
LogRegistryFileMaxSize xunits.Bytes `json:"logRegistryFileMaxSize"`
LogRegistryFileMaxAge xunits.TimeDuration `json:"logRegistryFileMaxAge"`
// contains filtered or unexported fields
}
LogHandler intercepts standard slog records to apply custom multi-destination routing, formatting layouts, and ANSI colorization.
func (*LogHandler) CheckConfiguration ¶
func (o *LogHandler) CheckConfiguration(logFileName string) error
CheckConfiguration processes structural validation across all target runtime parameters.
func (*LogHandler) Enabled ¶
Enabled decides whether the framework allows processing logs under the specified context conditions.
func (*LogHandler) Handle ¶
Handle processes incoming record fields routing them into standard channels or output logs.
type LogLevel ¶
type LogLevel string
LogLevel represents the custom severity thresholds supported by this logger.
const ( // LevelAll enables all available logging severities. LevelAll LogLevel = "all" // LevelNone completely silences the logger output. LevelNone LogLevel = "none" // LevelInfo filters logs to only show information, warning, and error messages. LevelInfo LogLevel = "info" // LevelWarn filters logs to only show warning and error messages. LevelWarn LogLevel = "warn" // LevelError restricts logs to error messages only. LevelError LogLevel = "error" )
Source Files