log

package module
Version: v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Feb 12, 2021 License: Apache-2.0 Imports: 2 Imported by: 11

README

Log Package

The log package provides a common interface that can be used in applications and libraries along with reference implementation wrappers for logrus, zap, the Go standard library package, and for a CLI.

Note: this codebase is under active development. Consider it beta code.

Go Report Card GoDoc

The Problem

The problem is that there are many logging packages where each has its own interface. This makes it difficult to mix and match libraries and code that depend on different interfaces. It also makes it difficult to change logging libraries if the one you are using becomes deprecated or you would like to switch to a different one (e.g., you want to tie into a logging service).

The log package aims to provide a solution to this problem.

Use Cases

This library was born out of a specific problem that also presents itself as a solution for a second use case.

Use Case 1: Console and Logging

I was working on an application that needs to write output to the console (sometimes with color) and to logrus. logrus is in the maintenance stage of development (it's even recommending other logging packages) so I can see it someday being replaced in the system I'll have to deal with.

I needed a solution that let me write messages that in some situations are sent to console output and in other situations are sent to logs. In the first situation it is as part of a CLI application. In the second case the code is imported as a library in a service.

The solution is to use an interface with varying implementations.

Use Case 2: Logging In Go Is Diverse Which Makes It Hard

Rust, PHP, and many other languages have APIs for logging that different implementations can implement. This makes logging pluggable and improves library interoperability.

This is a secondary use case and benefit from having an interface.

Usage

The usage documentation is broken down into 3 types of usage depending on your situation.

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.

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

Directories

Path Synopsis
_examples
cli
impl
cli
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