log

README

Go Log

This is Yet Another Logger for Go programs.

This is a logging package designed for local interactive shells running text based Go programs. To that end, this prints colorful log lines with customizable themes.

The color options for the log lines are NoColor (default), ANSIColor which limits the color codes to the standard 16 ANSI colors, and ExtendedColor which supports the 256-color palette of xterm and other modern terminal emulators. The theming engine supports defining colors using hex codes, supported by tomnomnom/xtermcolor.

This module is still a work in progress and will be extended and improved as I use it for other personal Go projects.

Usage

package main

import golog "git.kirsle.net/go/log"

var log golog.Logger

func init() {
    // Get a named logger and configure it. Note: you can call GetLogger any
    // number of times from any place in your codebase. It implements the
    // singleton pattern.
    log = golog.GetLogger("main")
    log.Configure(&golog.Config{
        Colors: golog.ExtendedColor,
        Theme: golog.DarkTheme,
    })
}

func main() {
    // The log functions work like `fmt.Printf`
    log.Debug("Running on %s", runtime.GOOS)
    log.Info("Hello, world!")
}

License

The MIT License (MIT)

Copyright (c) 2017-24 Noah Petherbridge

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Documentation

Index

• Constants
• Variables
• func HexColor(hex string) string
• type Config
  • func DefaultConfig() *Config
• type FileTee
  • func NewFileTee(filename string) (*FileTee, error)
  • func (ft *FileTee) Write(p []byte) (n int, err error)
• type Logger
  • func GetLogger(name string) *Logger
  • func (l *Logger) Configure(cfg *Config)
  • func (l *Logger) Debug(tmpl string, args ...interface{})
  • func (l *Logger) Error(tmpl string, args ...interface{})
  • func (l *Logger) Fatal(tmpl string, args ...interface{})
  • func (l *Logger) Format(level logLevel, tmpl string, args ...interface{}) string
  • func (l *Logger) Info(tmpl string, args ...interface{})
  • func (l *Logger) Warn(tmpl string, args ...interface{})
• type Theme
• type ThemeColor

Constants

const (
	// NoColor doesn't use any color codes at all (plain text).
	NoColor colorLevel = iota

	// ANSIColor uses the standard 16 colors supported by most terminals. This
	// option is the most portable across platforms.
	ANSIColor

	// ExtendedColor allows the use of 256 colors supported by most modern
	// terminals (24-bit color codes).
	ExtendedColor
)

Options for color support in your logger.

const (
	// DefaultFormat: shows the date in the secondary (dark) color, the label
	// in the bright color, and the message text in the normal color.
	DefaultFormat = `{{.Secondary}}{{.Time}}{{.Reset}} {{.Primary}}[{{.Level}}]{{.Reset}} {{.Message}}`

	// ColorfulFormat: like the DefaultFormat, but the message itself is also
	// colored using the secondary color.
	ColorfulFormat = `{{.Secondary}}{{.Time}}{{.Reset}} {{.Primary}}[{{.Level}}]{{.Reset}} {{.Secondary}}{{.Message}}{{.Reset}}`
)

Convenient log formats to use in your logger.

const (
	// DefaultTime is the default, in `yyyy-mm-dd hh:mm:ss` format.
	DefaultTime = `2006-01-02 15:04:05`

	// FriendlyTime is a human readable `Jan 2 15:04:05 2006` format.
	FriendlyTime = `Jan 2 15:04:05 2006`
)

Convenient time formats to use in your logger.

const (
	DebugLevel logLevel = iota
	InfoLevel
	WarnLevel
	ErrorLevel
	FatalLevel
)

Log levels for controlling whether or not logs of certain types will be emitted by your logger.

Variables

var DarkTheme = Theme{
	Debug:          ThemeColor{ansi.BrightCyan, HexColor("#FF99FF")},
	DebugSecondary: ThemeColor{ansi.Cyan, HexColor("#996699")},
	Info:           ThemeColor{ansi.BrightGreen, HexColor("#0099FF")},
	InfoSecondary:  ThemeColor{ansi.Green, HexColor("#006699")},
	Warn:           ThemeColor{ansi.BrightYellow, HexColor("#FF9900")},
	WarnSecondary:  ThemeColor{ansi.Yellow, HexColor("#996600")},
	Error:          ThemeColor{ansi.BrightRed, HexColor("#FF0000")},
	ErrorSecondary: ThemeColor{ansi.Red, HexColor("#CC0000")},
}

DarkTheme is a suitable default theme for dark terminal backgrounds.

var RegexpANSIColorCode = regexp.MustCompile(`\x1B\[[0-9;]+m`)

Functions

func HexColor

func HexColor(hex string) string

HexColor is a convenient wrapper around `xtermcolor.FromHexStr` to define colors for themes for xterm-256color codes.

Types

type Config

type Config struct {
	// Level is one of DebugLevel, InfoLevel, WarnLevel, ErrorLevel or FatalLevel.
	// Messages emitted by the logger must be 'at least' this level to be logged.
	Level logLevel

	// What colors are supported? Default is NoColor. Use ANSIColor to support
	// legacy terminal emulators, or ExtendedColor for modern 256-color support.
	Colors colorLevel

	// Which color theme are you using? The default is DarkTheme.
	Theme Theme

	// Where to write the log messages to? If not defined with a custom io.Writer,
	// the default goes to standard output for Debug and Info messages and
	// standard error for warnings, errors, and fatal messages.
	Writer io.Writer

	// How do you want to format your log lines? This should be a Go text format
	// string, with the following variable placeholders:
	//
	//    {{.Time}} inserts the date/time stamp for the log message.
	//    {{.Level}} inserts a label for the log level, e.g. "INFO" or "WARN"
	//    {{.Message}} inserts the text of the log message itself.
	//    {{.Primary}} inserts the color sequence for the primary color based
	//        on the log level for the message.
	//    {{.Secondary}} inserts the color sequence for the secondary color.
	//    {{.Reset}} inserts the 'reset' color sequence to stop coloring
	//        the rest of the text that follows.
	//
	// The default log format is as follows:
	//
	//    {{.Secondary}}{{.Time}}{{.Reset}} {{.Primary}}[{{.Level}}]{{.Reset}} {{.Message}}
	Format string

	// How do you want to format your time stamps? (The `{{.Time}}`). This uses
	// the Go `time` module, so the TimeFormat should use their reference date/time.
	// The default TimeFormat is: `2006-01-02 15:04:05`
	TimeFormat string
}

Config stores settings that control the logger's behavior.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a Config with the default values filled in.

type FileTee

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

FileTee can write logs to a file on disk as well as standard output.

func NewFileTee

func NewFileTee(filename string) (*FileTee, error)

func (*FileTee) Write

func (ft *FileTee) Write(p []byte) (n int, err error)

type Logger

type Logger struct {
	Name   string
	Config *Config
	// contains filtered or unexported fields
}

Logger stores the configuration for a named logger instance.

func GetLogger

func GetLogger(name string) *Logger

GetLogger initializes and returns a new Logger.

func (*Logger) Configure

func (l *Logger) Configure(cfg *Config)

Configure applies the configuration to the logger. If any of the following keys are not defined (or have zero-values), the default value for the key will be used instead:

Format
TimeFormat

func (*Logger) Debug

func (l *Logger) Debug(tmpl string, args ...interface{})

Debug emits a debug-level message from the logger.

func (*Logger) Error

func (l *Logger) Error(tmpl string, args ...interface{})

Error emits an error message.

func (*Logger) Fatal

func (l *Logger) Fatal(tmpl string, args ...interface{})

Fatal logs a fatal message and quits.

func (*Logger) Format

func (l *Logger) Format(level logLevel, tmpl string, args ...interface{}) string

Format and return a log message.

func (*Logger) Info

func (l *Logger) Info(tmpl string, args ...interface{})

Info emits an informational message.

func (*Logger) Warn

func (l *Logger) Warn(tmpl string, args ...interface{})

Warn emits a warning message.

type Theme

type Theme struct {
	Debug          ThemeColor
	DebugSecondary ThemeColor
	Info           ThemeColor
	InfoSecondary  ThemeColor
	Warn           ThemeColor
	WarnSecondary  ThemeColor
	Error          ThemeColor
	ErrorSecondary ThemeColor
}

Theme defines the color scheme for a logger. Each log level has two colors: a primary (for the label itself) and a secondary color. For example, if your log lines include a date/time this could be colored using the secondary color.

type ThemeColor

type ThemeColor struct {
	ANSI     string
	Extended string
}

ThemeColor defines a color tuple for ANSI (legacy) support and modern 256-color support.