log

README

log

Go logging library used at Mailgun.

Usage

The mailgun/log package supports chains of loggers where the same message can go to multiple logging channels simultaneously, for example, the standard output and syslog.

Currently, the following loggers are supported: console (stdout), syslog and updlog. The latter requires having udplog server (https://github.com/mochi/udplog) running locally. Custom loggers can implement the package's Logger interface and be intergated into the logger chain.

Before using the package it should be initialized at the start of a program. It can be done in two ways.

Initialize with loggers

import "github.com/mailgun/log"

func main() {
  // create a console logger
  console, _ := log.NewLogger(log.Config{"console", "info"})

  // create a syslogger
  syslog, _ := log.NewLogger(log.Config{"syslog", "error"})

  // init the logging package
  log.Init(console, syslog) // or any other logger implementing `log.Logger` can be provided
}

Initialize with a config

Mailgun's cfg package (https://github.com/mailgun/cfg) simplifies this method.

Define a logging configuration in a YAML config file.

logging:
  - name:     console
    severity: error
  - name:     syslog
    severity: info

Logging config can be built into your program's config struct:

import "github.com/mailgun/log"

type Config struct {
  // some program-specific configuration

  // logging configuration
  Logging []log.Config
}

After config parsing, initialize the logging library:

import (
  "github.com/mailgun/cfg"
  "github.com/mailgun/log"
)

func main() {
  conf := Config{}

  // parse config with logging configuration
  cfg.LoadConfig("path/to/config.yaml", &conf)

  // init the logging package
  log.InitWithConfig(conf.Logging...)
}

Documentation

Index

• Constants
• func Debugf(format string, args ...interface{})
• func Errorf(format string, args ...interface{})
• func Infof(format string, args ...interface{})
• func Init(l ...Logger)
• func InitWithConfig(configs ...Config) error
• func Logfmt(callDepth int, sev Severity, format string, args ...interface{})
• func SetSeverity(sev Severity)
• func Warningf(format string, args ...interface{})
• type CallerInfo
• type Config
• type LogWriter
  • func GetGlobalLogger() LogWriter
• type Logger
  • func NewConsoleLogger(conf Config) (Logger, error)
  • func NewLogger(config Config) (Logger, error)
  • func NewSysLogger(conf Config) (Logger, error)
  • func NewUDPLogger(conf Config) (Logger, error)
• type Severity
  • func SeverityFromString(s string) (Severity, error)
  • func (s Severity) String() string

Constants

const (
	Console = "console"
	Syslog  = "syslog"
	UDPLog  = "udplog"
)

Supported log types.

const (
	DefaultHost = "127.0.0.1"
	DefaultPort = 55647

	DefaultCategory = "go_logging"
)

Functions

func Debugf

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

Debugf logs to the DEBUG log.

func Errorf

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

Errorf logs to the ERROR, WARN, and INFO logs.

func Infof

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

Infof logs to the INFO log.

func Init

func Init(l ...Logger)

Init initializes the logging package with the provided loggers.

func InitWithConfig

func InitWithConfig(configs ...Config) error

InitWithConfig instantiates loggers based on the provided configs and initializes the package with them.

func Logfmt

func Logfmt(callDepth int, sev Severity, format string, args ...interface{})

Logfmt logs a formatted message of the specified severity, marking it attributed to a function at the specified depth on the current goroutine stack.

func SetSeverity

func SetSeverity(sev Severity)

func Warningf

func Warningf(format string, args ...interface{})

Warningf logs to the WARN and INFO logs.

Types

type CallerInfo

type CallerInfo struct {
	FileName string
	FilePath string
	FuncName string
	LineNo   int
}

CallerInfo encapsulates information about a piece of code that called a certain log function, such as file name, line number, etc.

type Config

type Config struct {
	// Name is a logger's identificator used to instantiate a proper logger type
	// from a config.
	Name string

	// Severity indicates the minimum severity a logger will be logging messages at.
	Severity string
}

Config represents a configuration of an individual logger.

type LogWriter

type LogWriter interface {
	Infof(format string, args ...interface{})
	Warningf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
}

func GetGlobalLogger

func GetGlobalLogger() LogWriter

type Logger

type Logger interface {
	// Writer returns logger's underlying io.Writer used to write log messages to.
	//
	// It may be, for example, the standard output for a console logger or a socket
	// connection for a UDP logger.
	//
	// Should return `nil` if the logger is not supposed to log at the specified severity.
	Writer(Severity) io.Writer

	// FormatMessage constructs and returns a final message that will go to the logger's
	// output channel.
	FormatMessage(Severity, *CallerInfo, string, ...interface{}) string

	// Sets a loggers current Severity level.
	SetSeverity(Severity)

	// Gets the current Severity level.
	GetSeverity() Severity
}

Logger is an interface that should be implemented by all loggers wishing to participate in the logger chain initialized by this package.

func NewConsoleLogger

func NewConsoleLogger(conf Config) (Logger, error)

func NewLogger

func NewLogger(config Config) (Logger, error)

NewLogger makes a proper logger from the given configuration.

func NewSysLogger

func NewSysLogger(conf Config) (Logger, error)

func NewUDPLogger

func NewUDPLogger(conf Config) (Logger, error)

type Severity

type Severity int32

const (
	SeverityDebug Severity = iota
	SeverityInfo
	SeverityWarning
	SeverityError
)

Supported severities.

func SeverityFromString

func SeverityFromString(s string) (Severity, error)

func (Severity) String

func (s Severity) String() string