logs

Documentation

Overview

Package logs implements simple hierarchical logging functionality for debugging and logging. The package can write to any configured logger, but generally writes to stdout for use with system logging. The log level specifies the verbosity of the output. For example if the level is set to Info, then Debug and Trace messages will become no-ops and ignored by the logger.

This package also provides a Caution log level - caution messages are only printed if a specific threshold of messages has been reached. This helps to reduce the number of repeated messages (e.g. connection down) that occur in logging while still giving effective debugging and systems administration feedback to the user.

Index

• Constants
• func NoColor() bool
• func ParseLevel(level string) (uint8, error)
• func StatusLevel(status int) uint8
• type HTTPLogger
  • func NewHTTPLogger(prefix string, handler http.Handler) *HTTPLogger
  • func (l *HTTPLogger) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Logger
  • func New(prefix string) *Logger
  • func (l *Logger) Caution(msg string, a ...interface{})
  • func (l *Logger) Colorize() bool
  • func (l *Logger) Debug(msg string, a ...interface{})
  • func (l *Logger) DisableColors()
  • func (l *Logger) EnableColors()
  • func (l *Logger) Info(msg string, a ...interface{})
  • func (l *Logger) LogLevel() string
  • func (l *Logger) SetBackend(out io.Writer)
  • func (l *Logger) SetCautionThreshold(threshold uint)
  • func (l *Logger) SetLogLevel(level uint8)
  • func (l *Logger) SetTimestamp(layout string)
  • func (l *Logger) Status(msg string, a ...interface{})
  • func (l *Logger) Trace(msg string, a ...interface{})
  • func (l *Logger) Warn(msg string, a ...interface{})
  • func (l *Logger) Warne(err error)

Examples

• Logger

Constants

const (
	LevelTrace uint8 = iota
	LevelDebug
	LevelInfo
	LevelCaution
	LevelStatus
	LevelWarn
	LevelSilent
)

Logging levels for specify the verbosity of log output. The higher the level, the less verbose the output is, e.g. will log messages >= to the specified level.

const (
	DefaultLogLevel         = LevelInfo
	DefaultCautionThreshold = 80
	DefaultUseColor         = true
)

Default values for new loggers that are created by the package

Functions

func NoColor

func NoColor() bool

NoColor returns true if stdout is not a terminal.

func ParseLevel

func ParseLevel(level string) (uint8, error)

ParseLevel returns the log level from the level string.

func StatusLevel

func StatusLevel(status int) uint8

StatusLevel returns the log level for the specified http status code.

Types

type HTTPLogger

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

HTTPLogger is a specialized logging module that colorizes output based on the status code of the response and uses levels slightly differently. HTTP status 100 levels are LevelInfo, status 200 or 300 are LevelStatus, and 400 or 500 are LevelWarn. You can use the same levels to surpress output if only errors are desirable to track. The primary difference between this logger with the default logger is that the colorization is not based on level but rather by status code. It also implements http.Handler so that it can be used in middlware.

func NewHTTPLogger

func NewHTTPLogger(prefix string, handler http.Handler) *HTTPLogger

NewHTTPLogger returns a web server specific logger that colorizes output based on status code rather than log level. This logger also wraps a handler and serves as both the request and response handling middleware.

func (*HTTPLogger) ServeHTTP

func (l *HTTPLogger) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Logger

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

Logger wraps a log.Logger to provide advanced functionality such as logging levels, terminal colorization, and caution thresholding. Different loggers can be configured to have different output formats and layouts.

Example

package main

import (
	"errors"
	"os"

	"github.com/bbengfort/catena/logs"
)

func main() {
	logger := logs.New("[test] ")

	logger.SetBackend(os.Stdout)
	logger.SetLogLevel(logs.LevelInfo)
	logger.SetCautionThreshold(2)
	logger.SetTimestamp("")
	logger.DisableColors()

	logger.Trace("routine %s happening", "thing")
	logger.Debug("sending message #%d from %s to %s", 42, "me", "you")
	logger.Info("listening on %s", "127.0.0.1")
	logger.Caution("could not reach %s -- connection is down", "uptime.robot")
	logger.Status("completed %d out of %d tasks", 42, 121)
	logger.Warn("limit of %d queries reached", 21)
	logger.Warne(errors.New("something bad happened"))

	logger.Caution("could not reach %s -- connection is down", "uptime.robot")
	logger.Caution("could not reach %s -- connection is down", "uptime.robot")

}

Output:

[test] listening on 127.0.0.1
[test] could not reach uptime.robot -- connection is down
[test] completed 42 out of 121 tasks
[test] limit of 21 queries reached
[test] something bad happened
[test] could not reach uptime.robot -- connection is down

func New

func New(prefix string) *Logger

New returns a new logger that can be configured to write its output.

func (*Logger) Caution

func (l *Logger) Caution(msg string, a ...interface{})

Caution prints to the standard logger if the level is caution or greater and if the number of times caution has been called with the same message has reached the threshold. This reduces the number of repeated log output messages while still allowing the system to report valuable information.

func (*Logger) Colorize

func (l *Logger) Colorize() bool

Colorize returns whether or not the output is being colorized

func (*Logger) Debug

func (l *Logger) Debug(msg string, a ...interface{})

Debug prints to the standard logger if level is debug or greater; arguments are handled in the manner of log.Printf, but a newline is appended.

func (*Logger) DisableColors

func (l *Logger) DisableColors()

DisableColors turns terminal colorization off (overrides is terminal check).

func (*Logger) EnableColors

func (l *Logger) EnableColors()

EnableColors turns terminal colorization on (overrides is terminal check).

func (*Logger) Info

func (l *Logger) Info(msg string, a ...interface{})

Info prints to the standard logger if level is info or greater; arguments are handled in the manner of log.Printf, but a newline is appended.

func (*Logger) LogLevel

func (l *Logger) LogLevel() string

LogLevel returns a string representation of the current level.

func (*Logger) SetBackend

func (l *Logger) SetBackend(out io.Writer)

SetBackend updates the logger to use a different writer than os.Stdout

func (*Logger) SetCautionThreshold

func (l *Logger) SetCautionThreshold(threshold uint)

SetCautionThreshold to the specified number of messages before print.

func (*Logger) SetLogLevel

func (l *Logger) SetLogLevel(level uint8)

SetLogLevel modifies the log level for messages at runtime. Ensures that the highest level that can be set is the trace level. This function is often called from outside of the package in an init() function to define how logging is handled in the console.

func (*Logger) SetTimestamp

func (l *Logger) SetTimestamp(layout string)

SetTimestamp updates the logger to use a different timestamp layout function

func (*Logger) Status

func (l *Logger) Status(msg string, a ...interface{})

Status prints to the standard logger if level is status or greater; arguments are handled in the manner of log.Printf, but a newline is appended.

func (*Logger) Trace

func (l *Logger) Trace(msg string, a ...interface{})

Trace prints to the standard logger if level is trace or greater; arguments are handled in the manner of log.Printf, but a newline is appended.

func (*Logger) Warn

func (l *Logger) Warn(msg string, a ...interface{})

Warn prints to the standard logger if level is warn or greater; arguments are handled in the manner of log.Printf, but a newline is appended.

func (*Logger) Warne

func (l *Logger) Warne(err error)

Warne is a helper function to simply warn about an error received.