loggertron

README

loggertron

A lightweight, structured logging library for Go. Outputs JSON log entries with timestamps, log levels, messages, and caller information (file name and line number).

Features

• Four log levels: Debug, Info, Warning, Error
• JSON-formatted output — machine-readable and cloud-native
• Automatic timestamps in RFC3339 format (UTC)
• Caller info — file name and line number included in every entry
• Configurable output via io.Writer (file, stdout, stderr, buffer, etc.)
• Threshold filtering — suppress low-level logs in production
• Functional options pattern for clean, extensible configuration

Installation

go get loggertron

Quick Start

package main

import (
    "loggertron/loggertron"
)

func main() {
    lgr := loggertron.New(loggertron.LevelDebug)

    lgr.Debugf("starting application")
    lgr.Infof("server listening on port %d", 8080)
    lgr.Warningf("disk usage at %d%%", 85)
    lgr.Errorf("database connection failed: %s", "timeout")
}

Output:

{"time":"2026-07-17T10:22:01Z","level":"[DEBUG]","message":"starting application","file":"/app/main.go","line":9}
{"time":"2026-07-17T10:22:01Z","level":"[INFO]","message":"server listening on port 8080","file":"/app/main.go","line":10}
{"time":"2026-07-17T10:22:01Z","level":"[WARNING]","message":"disk usage at 85%","file":"/app/main.go","line":11}
{"time":"2026-07-17T10:22:01Z","level":"[ERROR]","message":"database connection failed: timeout","file":"/app/main.go","line":12}

Log Levels

Level	Constant	Use when
Debug	loggertron.LevelDebug	Detailed developer info during development
Info	loggertron.LevelInfo	Normal operation events
Warning	loggertron.LevelWarning	Something unusual but not yet broken
Error	loggertron.LevelError	Something went wrong

Threshold Filtering

Set a threshold at creation — any level below it is silently ignored:

// In production: suppress Debug and Info, only show Warning and above
lgr := loggertron.New(loggertron.LevelWarning)

lgr.Debugf("this will NOT be logged")
lgr.Infof("this will NOT be logged")
lgr.Warningf("this WILL be logged")
lgr.Errorf("this WILL be logged")

Custom Output

By default, logs are written to os.Stdout. Use WithOutput to redirect:

import (
    "os"
    "loggertron/loggertron"
)

// Write to stderr
lgr := loggertron.New(loggertron.LevelInfo, loggertron.WithOutput(os.Stderr))

// Write to a file
f, _ := os.Create("app.log")
lgr := loggertron.New(loggertron.LevelInfo, loggertron.WithOutput(f))

Running Tests

cd loggertron
go test -v ./loggertron/...

Project Structure

loggertron/
├── go.mod
├── main.go
└── loggertron/
    ├── level.go       — log level type and constants
    ├── logger.go      — Logger struct and logging methods
    ├── options.go     — functional options (WithOutput)
    └── logger_test.go — tests

License

MIT

Documentation

Index

• Variables
• func Debugf(format string, args ...any)
• func Errorf(format string, args ...any)
• func Infof(format string, args ...any)
• func Warningf(format string, args ...any)
• type Formatter
• type JSONFormatter
  • func (j JSONFormatter) Format(entry LogEntry) ([]byte, error)
• type Level
  • func (l Level) String() string
• type LogEntry
• type Logger
  • func New(threshold Level, opts ...Option) *Logger
  • func (lgr *Logger) Debugf(format string, args ...any)
  • func (lgr *Logger) Errorf(format string, args ...any)
  • func (lgr *Logger) Infof(format string, args ...any)
  • func (lgr *Logger) SetLevel(level Level)
  • func (lgr *Logger) Warningf(format string, args ...any)
• type Option
  • func WithFormatter(f Formatter) Option
  • func WithOutput(output io.Writer) Option
• type TextFormatter
  • func (t TextFormatter) Format(entry LogEntry) ([]byte, error)

Variables

var Std = New(LevelInfo)

Default Logger variable named "Std" creates a shared logger at "Info" threshold writing to os.Stdout — sensible defaults for most use cases. API design — two layers	instance API + convenience API.

Can be replaced for testing or custom configuration.

Functions

func Debugf

func Debugf(format string, args ...any)

Package-level convenience functions that delegate to the default logger.

func Errorf

func Errorf(format string, args ...any)

func Infof

func Infof(format string, args ...any)

func Warningf

func Warningf(format string, args ...any)

Types

type Formatter

type Formatter interface {
	Format(entry LogEntry) ([]byte, error)
}

"Formatter" interface defines the contract for formatting log entries.

type JSONFormatter

type JSONFormatter struct{}

type JSON Formatter formats log entries as JSON objects

func (JSONFormatter) Format

func (j JSONFormatter) Format(entry LogEntry) ([]byte, error)

Function "Format" implements the Formatter interface for JSON output from the JSON formatter type

type Level

type Level byte

Level represents an available logging level

const (
	/* LevelDebug represents the lowest level of log, mostly used for debugging purposes
	 */
	LevelDebug Level = iota
	/* LevelInfo represents the logging level for valuable insights.
	 */
	LevelInfo
	/* LevelError represents the highest logging level for tracing errors.
	 */
	LevelWarning
	/* LevelWarning represents the logging level for tracing warnings.*/
	LevelError
)

func (Level) String

func (l Level) String() string

String() method returns the string representation of the logging level.

type LogEntry

type LogEntry struct {
	Time time.Time `json:"time"`
	/* Raw time, formatters decide format */
	Level   Level  `json:"level"`
	Message string `json:"message"`
	File    string `json:"file"`
	Line    int    `json:"line"`
}

Fields like threshold and output start with lowercase letters so they remain unexported (private). Users will interact with them only through the "New" function and methods like "Debugf", "Infof",etc.

"LogEntry" is the exported structure of the log entry to represent the log message in JSON format. It's fields are still controlled by the logger. LogEntry contains all information about a log event. It is passed by value to formatters; fields are exported for marshalling.

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger is used to log information about the program's execution. It is thread-safe and can be used concurrently. It is also configurable and can be used to log to different outputs and with different formats. It is also used to log at different levels of severity. Users can create multiple loggers with different configurations.

func New

func New(threshold Level, opts ...Option) *Logger

"New" function returns a logger
ready to log at the required threshold.

"New" accepts optional configuration functions.

func (*Logger) Debugf

func (lgr *Logger) Debugf(format string, args ...any)

"Debugf" method formats and prints a message if the log level is "Debug" or higher.

func (*Logger) Errorf

func (lgr *Logger) Errorf(format string, args ...any)

"Errorf" method formats and prints a message if the log level is "Error".

func (*Logger) Infof

func (lgr *Logger) Infof(format string, args ...any)

"Infof" method formats and prints a message if the lig level is "Info" or higher.

func (*Logger) SetLevel

func (lgr *Logger) SetLevel(level Level)

"SetLevel" function allows the user to change the log level dynamically.

func (*Logger) Warningf

func (lgr *Logger) Warningf(format string, args ...any)

"Warningf" method formats and prints a message if the log level is "Warning" or higher.

type Option

type Option func(*Logger)

Option defines a functional option for the logger

func WithFormatter

func WithFormatter(f Formatter) Option

func WithOutput

func WithOutput(output io.Writer) Option

WithOutPut return a confirmation function that sets the output of logs.

type TextFormatter

type TextFormatter struct{}

TextFormatter formats log entries as human readable plain text

func (TextFormatter) Format

func (t TextFormatter) Format(entry LogEntry) ([]byte, error)

Function "Format" implements the "Format" interface

for human readable text output from the "TextFormatter" type