log

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 16, 2022 License: Apache-2.0 Imports: 2 Imported by: 53

README

Log Package

The log package provides a common interface for logging that can be used in applications and libraries along with reference implementations for logrus, zap, the Go standard library package, and for a CLI (console app).

Go Report Card GoDoc

Why A Log Interface

In many programming languages there is a logging interface. Libraries will use use the interface for logging and then the application will choose the logging library of their choice for the application as a whole. Since everything follows the interface it works.

Go does not have a detailed interface. The logging package included in the standard library has been insufficient so many logging libraries have been created.

Various libraries/packages use the a logging implementation of their choice. When those are pulled into a larger application is will end up having multiple different logging systems. The main application needs to wire them all up or it will miss some logs. If you take a look at applications like Kubernetes, Nomad, and many others you'll discover they import many different logging implementations.

Using interfaces provides a may to move away from multiple implementation, simplify codebases, reduce binary size, and reduce threat surface area.

What This Package Provides

This library includes several things including:

  • A Go interface for leveled logging. Those levels include - Fatal, Panic, Error, Warn, Info, Debug, Trace
  • When logging messages the interface can do a message, a message with formatting string and arguments, and a message with fields (key/value pairs)
  • Package level logging functions whose implementation can be changed/set
  • Reference implementations for logrus, zap, the standard library, and a CLI
  • A simple default implementation so it just works for library testing and simple situations

Usage

The usage documentation is broken down into 3 types of usage depending on your situation. These examples are for library/package authors, applications, and logger implementation developers.

Library / Package Authors

If you are a library or package author there are two ways you can use this log package.

First, you can import the package and use the package level logging options. For example:

import(
    "github.com/Masterminds/log-go"
)

log.Info("Send Some Info")

You can use this for logging within your package.

Second, if you want to pass a logger around your package you can use the interface provided by this package. For example:

import "github.com/Masterminds/log-go"

func NewConstructorExample(logger log.Logger) {
    return &Example{
        logger: logger,
    }
}

func (e *Example) Foo() {
    e.logger.Info("Send Some Info")
}

In your packages testing you can check log messages if you need to see that they are working and contain what you are looking for. A simple example of doing this is in the _examples directory.

For details on exactly which functions are on the package or on the Logger interface, please see the package docs.

Application Developers

If you are developing an application that will be writing logs you will want to setup and configure logging the way you want. This is where this interface based package empowers you. You can pick your logging implementation or write your own.

For example, if you want to use a standard logrus logger you can setup logging like so:

import(
    "github.com/Masterminds/log-go"
    "github.com/Masterminds/log-go/impl/logrus"
)

log.Current = logrus.NewStandard()

In this example a standard logrus logger is created, wrapped in a struct instance that conforms to the interface, and is set as the global logger to use.

The impl directory has several reference implementations and they have configurable setups.

Once you setup the global logger the way you want all the packages will use this same logger.

Logger Developers

There are many loggers and many ways to record logs. They can be written to a file, sent to stdout/stderr, sent to a logging service, and more. Each of these is possible with this package.

If you have logger you want to use you can write one that conforms to the Logger interface found in log.go. That logger can then be configured as documented in the previous section.

The impl directory has reference implementations you can look at for further examples.

Log Levels

The following log levels are currently implemented across the interface and all the reference implementations.

  • Fatal
  • Panic
  • Error
  • Warn
  • Info
  • Debug
  • Trace

Documentation

Overview

Example 
package main

import (
	"fmt"

	"github.com/Masterminds/log-go"
	"github.com/Masterminds/log-go/impl/logrus"
)

type Foo struct {
	Logger log.Logger
}

func (f *Foo) DoSomething() {
	f.Logger.Info("Hello Logging")
}

func main() {

	// Using the default Logger
	log.Info("Hello")
	log.Error("World")

	// Create a logrus logger with default configuration that uses the log
	// interface. Note, logrus can be setup with default settings or setup with
	// custom settings using a second constructor.
	lgrs := logrus.NewStandard()

	// Set logrus as the global logger
	log.Current = lgrs

	// Logrus is now used globally for logging
	log.Warn("Warning through logrus")

	f1 := Foo{
		Logger: lgrs,
	}

	// Logging in DoSomething will use the set logger which is logrus
	f1.DoSomething()

	f2 := Foo{
		// The log package uses the global logger from the standard library log
		// package. A custom standard library logger can be used with the
		// github.com/Masterminds/log-go/impl/std package.
		Logger: log.NewStandard(),
	}

	// Logging in DoSomething will the logger from the standard library
	f2.DoSomething()

	// Need to detect the logger being used? You can check for the type.
	switch log.Current.(type) {
	case *log.StdLogger:
		fmt.Println("The default logger")
	case *logrus.Logger:
		fmt.Printf("Logrus is used for logging")
	default:
		fmt.Printf("Something else that implements the interface")
	}
}

Output:

Index

Examples

Constants

View Source 
const (
	// TraceLevel is the constant to use when setting the Trace level for loggers
	// provided by this library.
	TraceLevel = iota

	// DebugLevel is the constant to use when setting the Debug level for loggers
	// provided by this library.
	DebugLevel

	// InfoLevel is the constant to use when setting the Info level for loggers
	// provided by this library.
	InfoLevel

	// WarnLevel is the constant to use when setting the Warn level for loggers
	// provided by this library.
	WarnLevel

	// ErrorLevel is the constant to use when setting the Error level for loggers
	// provided by this library.
	ErrorLevel

	// PanicLevel is the constant to use when setting the Panic level for loggers
	// provided by this library.
	PanicLevel

	// FatalLevel is the constant to use when setting the Fatal level for loggers
	// provided by this library.
	FatalLevel
)

Variables

This section is empty.

Functions

func Debug 

func Debug(msg ...interface{})

Debug logs a message at the Debug level

func Debugf 

func Debugf(template string, args ...interface{})

Debugf formats a message according to a format specifier and logs the message at the Debug level

func Debugw 

func Debugw(msg string, fields Fields)

Debugw logs a message at the Debug level along with some additional context (key-value pairs)

func Error 

func Error(msg ...interface{})

Error logs a message at the Error level

func Errorf 

func Errorf(template string, args ...interface{})

Errorf formats a message according to a format specifier and logs the message at the Error level

func Errorw 

func Errorw(msg string, fields Fields)

Errorw logs a message at the Error level along with some additional context (key-value pairs)

func Fatal 

func Fatal(msg ...interface{})

Fatal logs a message at the Fatal level and exists the application

func Fatalf 

func Fatalf(template string, args ...interface{})

Fatalf formats a message according to a format specifier and logs the message at the Fatal level and exits the application

func Fatalw 

func Fatalw(msg string, fields Fields)

Fatalw logs a message at the Fatal level along with some additional context (key-value pairs) and exits the application

func Info 

func Info(msg ...interface{})

Info logs a message at the Info level

func Infof 

func Infof(template string, args ...interface{})

Infof formats a message according to a format specifier and logs the message at the Info level

func Infow 

func Infow(msg string, fields Fields)

Infow logs a message at the Info level along with some additional context (key-value pairs)

func Panic 

func Panic(msg ...interface{})

Panic logs a message at the Panic level and panics

func Panicf 

func Panicf(template string, args ...interface{})

Panicf formats a message according to a format specifier and logs the message at the Panic level and then panics

func Panicw 

func Panicw(msg string, fields Fields)

Panicw logs a message at the Panic level along with some additional context (key-value pairs) and then panics

func Trace 

func Trace(msg ...interface{})

Trace logs a message at the Trace level

func Tracef 

func Tracef(template string, args ...interface{})

Tracef formats a message according to a format specifier and logs the message at the Trace level

func Tracew 

func Tracew(msg string, fields Fields)

Tracew logs a message at the Trace level along with some additional context (key-value pairs)

func Warn 

func Warn(msg ...interface{})

Warn logs a message at the Warn level

func Warnf 

func Warnf(template string, args ...interface{})

Warnf formats a message according to a format specifier and logs the message at the Warning level

func Warnw 

func Warnw(msg string, fields Fields)

Warnw logs a message at the Warning level along with some additional context (key-value pairs)

Types

type Fields 

type Fields map[string]interface{}

Fields represents a map of key-value pairs where the value can be any Go type. The value must be able to be converted to a string.

type Logger 

type Logger interface {
	// Trace logs a message at the Trace level
	Trace(msg ...interface{})

	// Tracef formats a message according to a format specifier and logs the
	// message at the Trace level
	Tracef(template string, args ...interface{})

	// Tracew logs a message at the Trace level along with some additional
	// context (key-value pairs)
	Tracew(msg string, fields Fields)

	// Debug logs a message at the Debug level
	Debug(msg ...interface{})

	// Debugf formats a message according to a format specifier and logs the
	// message at the Debug level
	Debugf(template string, args ...interface{})

	// Debugw logs a message at the Debug level along with some additional
	// context (key-value pairs)
	Debugw(msg string, fields Fields)

	// Info logs a message at the Info level
	Info(msg ...interface{})

	// Infof formats a message according to a format specifier and logs the
	// message at the Info level
	Infof(template string, args ...interface{})

	// Infow logs a message at the Info level along with some additional
	// context (key-value pairs)
	Infow(msg string, fields Fields)

	// Warn logs a message at the Warn level
	Warn(msg ...interface{})

	// Warnf formats a message according to a format specifier and logs the
	// message at the Warning level
	Warnf(template string, args ...interface{})

	// Warnw logs a message at the Warning level along with some additional
	// context (key-value pairs)
	Warnw(msg string, fields Fields)

	// Error logs a message at the Error level
	Error(msg ...interface{})

	// Errorf formats a message according to a format specifier and logs the
	// message at the Error level
	Errorf(template string, args ...interface{})

	// Errorw logs a message at the Error level along with some additional
	// context (key-value pairs)
	Errorw(msg string, fields Fields)

	// Panic logs a message at the Panic level and panics
	Panic(msg ...interface{})

	// Panicf formats a message according to a format specifier and logs the
	// message at the Panic level and then panics
	Panicf(template string, args ...interface{})

	// Panicw logs a message at the Panic level along with some additional
	// context (key-value pairs) and then panics
	Panicw(msg string, fields Fields)

	// Fatal logs a message at the Fatal level and exists the application
	Fatal(msg ...interface{})

	// Fatalf formats a message according to a format specifier and logs the
	// message at the Fatal level and exits the application
	Fatalf(template string, args ...interface{})

	// Fatalw logs a message at the Fatal level along with some additional
	// context (key-value pairs) and exits the application
	Fatalw(msg string, fields Fields)
}

Logger is an interface for Logging 

var Current Logger

Current contains the logger used for the package level logging functions

type StdLogger 

type StdLogger struct {
	Level int
}

StdLogger is a struct that wraps the general logger provided by the Go standard library and causes it to meet the log.Logger interface

func NewStandard 

func NewStandard() *StdLogger

NewStandard sets up a basic logger using the general one provided in the Go standard library

func (StdLogger) Debug 

func (l StdLogger) Debug(msg ...interface{})

Debug logs a message at the Debug level

func (StdLogger) Debugf 

func (l StdLogger) Debugf(template string, args ...interface{})

Debugf formats a message according to a format specifier and logs the message at the Debug level

func (StdLogger) Debugw 

func (l StdLogger) Debugw(msg string, fields Fields)

Debugw logs a message at the Debug level along with some additional context (key-value pairs)

func (StdLogger) Error 

func (l StdLogger) Error(msg ...interface{})

Error logs a message at the Error level

func (StdLogger) Errorf 

func (l StdLogger) Errorf(template string, args ...interface{})

Errorf formats a message according to a format specifier and logs the message at the Error level

func (StdLogger) Errorw 

func (l StdLogger) Errorw(msg string, fields Fields)

Errorw logs a message at the Error level along with some additional context (key-value pairs)

func (StdLogger) Fatal 

func (l StdLogger) Fatal(msg ...interface{})

Fatal logs a message at the Fatal level and exists the application

func (StdLogger) Fatalf 

func (l StdLogger) Fatalf(template string, args ...interface{})

Fatalf formats a message according to a format specifier and logs the message at the Fatal level and exits the application

func (StdLogger) Fatalw 

func (l StdLogger) Fatalw(msg string, fields Fields)

Fatalw logs a message at the Fatal level along with some additional context (key-value pairs) and exits the application

func (StdLogger) Info 

func (l StdLogger) Info(msg ...interface{})

Info logs a message at the Info level

func (StdLogger) Infof 

func (l StdLogger) Infof(template string, args ...interface{})

Infof formats a message according to a format specifier and logs the message at the Info level

func (StdLogger) Infow 

func (l StdLogger) Infow(msg string, fields Fields)

Infow logs a message at the Info level along with some additional context (key-value pairs)

func (StdLogger) Panic 

func (l StdLogger) Panic(msg ...interface{})

Panic logs a message at the Panic level and panics

func (StdLogger) Panicf 

func (l StdLogger) Panicf(template string, args ...interface{})

Panicf formats a message according to a format specifier and logs the message at the Panic level and then panics

func (StdLogger) Panicw 

func (l StdLogger) Panicw(msg string, fields Fields)

Panicw logs a message at the Panic level along with some additional context (key-value pairs) and then panics

func (StdLogger) Trace 

func (l StdLogger) Trace(msg ...interface{})

Trace logs a message at the Trace level

func (StdLogger) Tracef 

func (l StdLogger) Tracef(template string, args ...interface{})

Tracef formats a message according to a format specifier and logs the message at the Trace level

func (StdLogger) Tracew 

func (l StdLogger) Tracew(msg string, fields Fields)

Tracew logs a message at the Trace level along with some additional context (key-value pairs)

func (StdLogger) Warn 

func (l StdLogger) Warn(msg ...interface{})

Warn logs a message at the Warn level

func (StdLogger) Warnf 

func (l StdLogger) Warnf(template string, args ...interface{})

Warnf formats a message according to a format specifier and logs the message at the Warning level

func (StdLogger) Warnw 

func (l StdLogger) Warnw(msg string, fields Fields)

Warnw logs a message at the Warning level along with some additional context (key-value pairs)

Source Files

View all Source files

Directories

Path Synopsis
_examples
cli
default
iowriter
logrus
logrus_custom
impl
cli
logrus
std
zap
Package io provides a means of turning a log.Logger into an io.Writer for a chosen level.
 Package io provides a means of turning a log.Logger into an io.Writer for a chosen level.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.