bark

README

Synopsis

Defines an interface for loggers and stats reporters that can be passed to Uber Go libraries.
Provides implementations which wrap a common logging module, logrus, and a common stats reporting module go-statsd-client.
Clients may also choose to implement these interfaces themselves.

Key Interfaces

Logging

// Logger is an interface for loggers accepted by Uber's libraries.
type Logger interface {
	// Log at debug level
	Debug(args ...interface{})

	// Log at debug level with fmt.Printf-like formatting
	Debugf(format string, args ...interface{})

	// Log at info level
	Info(args ...interface{})

	// Log at info level with fmt.Printf-like formatting
	Infof(format string, args ...interface{})

	// Log at warning level
	Warn(args ...interface{})

	// Log at warning level with fmt.Printf-like formatting
	Warnf(format string, args ...interface{})

	// Log at error level
	Error(args ...interface{})

	// Log at error level with fmt.Printf-like formatting
	Errorf(format string, args ...interface{})

	// Log at fatal level, then terminate process (irrecoverable)
	Fatal(args ...interface{})

	// Log at fatal level with fmt.Printf-like formatting, then terminate process (irrecoverable)
	Fatalf(format string, args ...interface{})

	// Log at panic level, then panic (recoverable)
	Panic(args ...interface{})

	// Log at panic level with fmt.Printf-like formatting, then panic (recoverable)
	Panicf(format string, args ...interface{})

	// Return a logger with the specified key-value pair set, to be logged in a subsequent normal logging call
	WithField(key string, value interface{}) Logger

	// Return a logger with the specified key-value pairs set, to be  included in a subsequent normal logging call
	WithFields(keyValues LogFields) Logger

	// Return map fields associated with this logger, if any (i.e. if this logger was returned from WithField[s])
	// If no fields are set, returns nil
	Fields() Fields
}

Stats Reporting

// StatsReporter is an interface for statsd-like stats reporters accepted by Uber's libraries.
// Its methods take optional tag dictionaries which may be ignored by concrete implementations.
type StatsReporter interface {
	// Increment a statsd-like counter with optional tags
	IncCounter(name string, tags Tags, value int64)

	// Increment a statsd-like gauge ("set" of the value) with optional tags
	UpdateGauge(name string, tags Tags, value int64)

	// Record a statsd-like timer with optional tags
	RecordTimer(name string, tags Tags, d time.Duration)
}

Basic Usage

logger := logrus.New()
barkLogger := bark.NewLoggerFromLogrus(logger)
barkLogger.WithFields(bark.Fields{"someField":"someValue"}).Info("Message")

statsd, err := statsd.New("127.0.0.1:8125", "barktest")
if err != nil {
    logger.Fatal("Example code failed")
}

barkStatsReporter := bark.NewStatsReporterFromCactus(statsd)  
barkStatsReporter.IncCounter("foo", map[string]string{"tag":"val"}, 1)
 
ubermodule.New(ubermodule.Config{
    logger: barkLogger
    statsd: barkStatsReporter
})

Contributors

dh

License

bark is available under the MIT license. See the LICENSE file for more info.

Documentation

Overview

Package bark provides an abstraction for loggers and stats reporters used in Uber's Go libraries. It decouples these libraries slightly from specific logger implementations; for example, the popular open source library logrus, which offers no interfaces (and thus cannot be, for instance, easily mocked).

Users may choose to implement the interfaces themselves or to use the provided wrappers for logrus loggers and cactus/go-statsd-client stats reporters.

Index

• type Fields
  • func (f Fields) Fields() map[string]interface{}
• type LogFields
• type Logger
  • func NewLoggerFromLogrus(logger *logrus.Logger) Logger
  • func NewNopLogger() Logger
• type StatsReporter
  • func NewStatsReporterFromCactus(statter statsd.Statter) StatsReporter
• type Tags

Types

type Fields

type Fields map[string]interface{}

Fields is the concrete LogFields type, as in myLogger.WithFields(bark.Fields{"foo": "bar"}).Info("Fields!")

func (Fields) Fields

func (f Fields) Fields() map[string]interface{}

Fields provides indirection for broader compatibility for the LogFields interface type.

type LogFields

type LogFields interface {
	Fields() map[string]interface{}
}

LogFields is an interface for dictionaries passed to Logger's WithFields logging method. It exists to provide a layer of indirection so code already using other "Fields" types can be changed to use bark.Logger instances without any refactoring (sidestepping the fact that if we used a concrete type, then yourloggingmodule.Fields would not assignable to bark.Fields).

type Logger

type Logger interface {
	// Log at debug level
	Debug(args ...interface{})

	// Log at debug level with fmt.Printf-like formatting
	Debugf(format string, args ...interface{})

	// Log at info level
	Info(args ...interface{})

	// Log at info level with fmt.Printf-like formatting
	Infof(format string, args ...interface{})

	// Log at warning level
	Warn(args ...interface{})

	// Log at warning level with fmt.Printf-like formatting
	Warnf(format string, args ...interface{})

	// Log at error level
	Error(args ...interface{})

	// Log at error level with fmt.Printf-like formatting
	Errorf(format string, args ...interface{})

	// Log at fatal level, then terminate process (irrecoverable)
	Fatal(args ...interface{})

	// Log at fatal level with fmt.Printf-like formatting, then terminate process (irrecoverable)
	Fatalf(format string, args ...interface{})

	// Log at panic level, then panic (recoverable)
	Panic(args ...interface{})

	// Log at panic level with fmt.Printf-like formatting, then panic (recoverable)
	Panicf(format string, args ...interface{})

	// Return a logger with the specified key-value pair set, to be logged in a subsequent normal logging call
	WithField(key string, value interface{}) Logger

	// Return a logger with the specified key-value pairs set, to be included in a subsequent normal logging call
	WithFields(keyValues LogFields) Logger

	// Return a logger with the specified error set, to be included in a subsequent normal logging call
	WithError(err error) Logger

	// Return map fields associated with this logger, if any (i.e. if this logger was returned from WithField[s])
	// If no fields are set, returns nil
	Fields() Fields
}

Logger is an interface for loggers accepted by Uber's libraries.

func NewLoggerFromLogrus

func NewLoggerFromLogrus(logger *logrus.Logger) Logger

NewLoggerFromLogrus creates a bark-compliant wrapper for a logrus-brand logger.

func NewNopLogger

func NewNopLogger() Logger

NewNopLogger creates a no-op logger.

type StatsReporter

type StatsReporter interface {
	// Increment a statsd-like counter with optional tags
	IncCounter(name string, tags Tags, value int64)

	// Increment a statsd-like gauge ("set" of the value) with optional tags
	UpdateGauge(name string, tags Tags, value int64)

	// Record a statsd-like timer with optional tags
	RecordTimer(name string, tags Tags, d time.Duration)
}

StatsReporter is an interface for statsd-like stats reporters accepted by Uber's libraries. Its methods take optional tag dictionaries which may be ignored by concrete implementations.

func NewStatsReporterFromCactus

func NewStatsReporterFromCactus(statter statsd.Statter) StatsReporter

NewStatsReporterFromCactus creates a bark-compliant wrapper for a cactus-brand statsd Statter.

type Tags

type Tags map[string]string

Tags is an alias of map[string]string, a type for tags associated with a statistic