cloudlogging

README

Cloud Logging for Go

This module provides a log wrapper that is intended to handle logging in cloud-based backend environment.

Changelog

• 1.1.0: Renamed Stackdriver -> Google Cloud Logging; this is API-breaking change.
• 1.0.0: Bumped version to 1.0.0. Fixed zap logger accumulating structured logging fields.
• 0.0.16: Added JSON formatting output hints
• 0.0.15: Added default parameters for structured logging
• 0.0.13: Argument handling bugfix, added GoDoc reference to README
• 0.0.11: Improved documentation.

Usage

Install the dependency:

go get -u github.com/qvik/go-cloudlogging

Convenience constructors & examples

For convenience, several constructor methods are provided; see below.

Google Compute Engine (GCE) example:

func init() {
	log = cloudlog.MustNewComputeEngineLogger("project-id", "MyAppLog")
}

This could also used for Kuhernetes.

Google App Engine (GAE) ecample:

func init() {
	log = cloudlog.MustNewAppEngineLogger() // Optionally define log ID as arg
}

Google Cloud Functions (GCF) example:

func init() {
	log = cloudlog.MustNewCloudFunctionLogger() // Optionally define log ID as arg
}

AWS Elastic Beanstalk / EC2 example:

	logfile := "/var/log/example-app.log"
	log = cloudlogging.MustNewLogger(cloudlogging.WithZap(),
		cloudlogging.WithOutputHints(cloudlogging.JSONFormat),
		cloudlogging.WithOutputPaths(logfile),
		cloudlogging.WithErrorOutputPaths(logfile))
}

License

The library is distributed with the MIT License.

Documentation

Overview

Package cloudlogging provides logging wrapper for Google Cloud Platform environments.

Index

• type Level
• type LogOption
  • func WithCommonKeysAndValues(commonKeysAndValues ...interface{}) LogOption
  • func WithErrorOutputPaths(paths ...string) LogOption
  • func WithGoogleCloudLogging(gcpProjectID, credentialsFilePath, googleCloudLoggingLogID string, ...) LogOption
  • func WithLevel(logLevel Level) LogOption
  • func WithOutputHints(hints ...OutputHint) LogOption
  • func WithOutputPaths(paths ...string) LogOption
  • func WithZap(config ...*zap.Config) LogOption
• type Logger
  • func MustNewAppEngineLogger(args ...string) *Logger
  • func MustNewCloudFunctionLogger(args ...string) *Logger
  • func MustNewCloudRunLogger(location, projectID string, args ...string) *Logger
  • func MustNewComputeEngineLogger(projectID, logID string) *Logger
  • func MustNewLogger(opt ...LogOption) *Logger
  • func MustNewZapLogger(config ...*zap.Config) *Logger
  • func NewAppEngineLogger(args ...string) (*Logger, error)
  • func NewCloudFunctionLogger(args ...string) (*Logger, error)
  • func NewCloudRunLogger(location, projectID string, args ...string) (*Logger, error)
  • func NewComputeEngineLogger(projectID, logID string) (*Logger, error)
  • func NewLogger(opt ...LogOption) (*Logger, error)
  • func NewZapLogger(config ...*zap.Config) (*Logger, error)
  • func (l *Logger) Close() error
  • func (l *Logger) Debug(payload interface{}, keysAndValues ...interface{})
  • func (l *Logger) Debugf(format string, args ...interface{})
  • func (l *Logger) Error(payload interface{}, keysAndValues ...interface{})
  • func (l *Logger) Errorf(format string, args ...interface{})
  • func (l *Logger) Fatal(payload interface{}, keysAndValues ...interface{})
  • func (l *Logger) Fatalf(format string, args ...interface{})
  • func (l *Logger) Flush() error
  • func (l *Logger) Info(payload interface{}, keysAndValues ...interface{})
  • func (l *Logger) Infof(format string, args ...interface{})
  • func (l *Logger) Panic(payload interface{}, keysAndValues ...interface{})
  • func (l *Logger) Panicf(format string, args ...interface{})
  • func (l *Logger) Print(payload interface{}, keysAndValues ...interface{})
  • func (l *Logger) Printf(format string, args ...interface{})
  • func (l *Logger) SetLogLevel(logLevel Level) *Logger
  • func (l *Logger) Trace(payload interface{}, keysAndValues ...interface{})
  • func (l *Logger) Tracef(format string, args ...interface{})
  • func (l *Logger) Warning(payload interface{}, keysAndValues ...interface{})
  • func (l *Logger) Warningf(format string, args ...interface{})
  • func (l *Logger) WithAdditionalKeysAndValues(keysAndValues ...interface{}) *Logger
• type OutputHint

Examples

• Logger.Debug
• Logger.Debugf
• Logger.WithAdditionalKeysAndValues

Types

type Level

type Level int8

Level is our log level type

const (
	Debug Level = iota
	Info
	Warning
	Error
	Fatal
)

Log levels

type LogOption

type LogOption interface {
	// contains filtered or unexported methods
}

LogOption is an option for the cloudlogging API.

func WithCommonKeysAndValues

func WithCommonKeysAndValues(commonKeysAndValues ...interface{}) LogOption

WithCommonKeysAndValues returns a LogOption that adds a set of common keys and values (labels / fields) to all structured log messages. For parameters should be: key1, value1, key2, value2, ..

func WithErrorOutputPaths

func WithErrorOutputPaths(paths ...string) LogOption

WithErrorOutputPaths log output paths, eg. URLs or file paths. Different loggers use these in different ways. For example Zap uses them as log output file paths.

func WithGoogleCloudLogging

func WithGoogleCloudLogging(gcpProjectID, credentialsFilePath,
	googleCloudLoggingLogID string,
	monitoredResource *monitoredres.MonitoredResource) LogOption

WithGoogleCloudLogging returns a LogOption that enables Google Cloud Logging Logger and configures it to use the given project id. If you supply empty string for credentialsFilePath, the default service account is used. Google cloud logging log backend does not react to OutputHints.

func WithLevel

func WithLevel(logLevel Level) LogOption

WithLevel returns a LogOption that defines our log level.

func WithOutputHints

func WithOutputHints(hints ...OutputHint) LogOption

WithOutputHints adds output hints to the log backend.

func WithOutputPaths

func WithOutputPaths(paths ...string) LogOption

WithOutputPaths log output paths, eg. URLs or file paths. Different loggers use these in different ways. For example Zap uses them as log output file paths.

func WithZap

func WithZap(config ...*zap.Config) LogOption

WithZap returns a LogOption that enables the local Zap logger, optionally with a Zap configuration.

type Logger

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

Logger writes logs to the local logger as well as the Google Cloud Logging cloud logs. Logger is mostly immutable - the only thing that can be modified is the log level.

Logger is thread-safe to use for any of the logging calls. Some methods such as SetLogLevel(), Close(), Flush() however are not and you should either call them at the start / end of your program or synchronize your access to the Logger instance if setting on them on the fly. The reasoning here being that standard Logger calls should not suffer a performance hit from locking.

Logger uses the Zap (https://github.com/uber-go/zap) library for local logging.

Logger uses Google Cloud Logging Go library for cloud logging.

The API is compatible (and thus a drop-in replacement) for popular logging libraries such as: - Go's standard "log" interface - https://github.com/op/go-logging - https://github.com/sirupsen/logrus - https://github.com/uber-go/zap

func MustNewAppEngineLogger

func MustNewAppEngineLogger(args ...string) *Logger

MustNewAppEngineLogger returns a Logger suitable for use in AppEngine. On local dev server it uses the local stdout -logger and in the cloud it uses the Google Cloud Logging logger. The first value of args is the logID. If omitted or empty string is given, the default value of "appengine.googleapis.com/request_log" is used. Panics on errors.

func MustNewCloudFunctionLogger

func MustNewCloudFunctionLogger(args ...string) *Logger

MustNewCloudFunctionLogger returns a Logger suitable for use in Google Cloud Functions. It will emit the logs using the Google Cloud Logging API. The first value of args is the logID. If omitted or empty string is given, the default value of "cloudfunctions.googleapis.com/cloud-functions" is used. Panics on errors.

func MustNewCloudRunLogger

func MustNewCloudRunLogger(location, projectID string, args ...string) *Logger

MustNewCloudRunLogger returns a Logger suitable for use in Cloud Run. On local dev server it uses the local stdout -logger and in the cloud it uses the Google Cloud Logging logger. The first value of args is the logID. If omitted or empty string is given, the default value of "run.googleapis.com/request_log" is used. Panics on errors.

func MustNewComputeEngineLogger

func MustNewComputeEngineLogger(projectID, logID string) *Logger

MustNewComputeEngineLogger returns a Logger suitable for use in Google Compute Engine instance as well as Google Kubernetes Engine. The returned logger only logs via Google Cloud Logging. Panics on errors.

func MustNewLogger

func MustNewLogger(opt ...LogOption) *Logger

MustNewLogger creates a new Logger instance using the given options. The default log level is Debug. Panics if logger creation fails.

func MustNewZapLogger

func MustNewZapLogger(config ...*zap.Config) *Logger

MustNewZapLogger returns a logger that only logs to a local stdout/stderr Zap logger, optionally with a Zap configuration. Panics on error(s).

func NewAppEngineLogger

func NewAppEngineLogger(args ...string) (*Logger, error)

NewAppEngineLogger returns a Logger suitable for use in AppEngine. On local dev server it uses the local Zap logger and in the cloud it uses the Google Cloud Logging logger. The first value of args is the logID. If omitted or empty string is given, the default value of "appengine.googleapis.com/request_log" is used.

func NewCloudFunctionLogger

func NewCloudFunctionLogger(args ...string) (*Logger, error)

NewCloudFunctionLogger returns a Logger suitable for use in Google Cloud Functions. It will emit the logs using the Google Cloud Logging API. The first value of args is the logID. If omitted or empty string is given, the default value of "cloudfunctions.googleapis.com/cloud-functions" is used.

func NewCloudRunLogger

func NewCloudRunLogger(location, projectID string, args ...string) (*Logger, error)

NewCloudRunLogger returns a Logger suitable for use in Cloud Run. On local dev server it uses the local Zap logger and in the cloud it uses the Google Cloud Logging logger. The first value of args is the logID. If omitted or empty string is given, the default value of "run.googleapis.com/request_log" is used.

func NewComputeEngineLogger

func NewComputeEngineLogger(projectID, logID string) (*Logger, error)

NewComputeEngineLogger returns a Logger suitable for use in Google Compute Engine instance as well as Google Kubernetes Engine. The returned logger only logs via Google Cloud Logging.

func NewLogger

func NewLogger(opt ...LogOption) (*Logger, error)

NewLogger creates a new Logger instance using the given options. The default log level is Debug.

func NewZapLogger

func NewZapLogger(config ...*zap.Config) (*Logger, error)

NewZapLogger returns a logger that only logs to a local stdout/stderr Zap logger, optionally with a Zap configuration.

func (*Logger) Close

func (l *Logger) Close() error

Close closes the logger and flushes the underlying loggers' buffers. Returns error if there are errors.

func (*Logger) Debug

func (l *Logger) Debug(payload interface{}, keysAndValues ...interface{})

Debug writes a structured log entry using the debug level. Compatibility alias for Debug().

Example

log, _ := NewLogger() // Allocates a null logger
log.Debug("Debug log message", "label1", 1, "label2", 2)

func (*Logger) Debugf

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

Debugf writes debug level logs

Example

log, _ := NewLogger() // Allocates a null logger
myMsg := "message"
log.Debugf("Debug with msg: %v", myMsg)

func (*Logger) Error

func (l *Logger) Error(payload interface{}, keysAndValues ...interface{})

Error writes a structured log entry using the error level.

func (*Logger) Errorf

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

Errorf writes error level logs

func (*Logger) Fatal

func (l *Logger) Fatal(payload interface{}, keysAndValues ...interface{})

Fatal writes a structured log entry using the fatal level.

func (*Logger) Fatalf

func (l *Logger) Fatalf(format string, args ...interface{})

Fatalf writes fatal level logs and calls os.Exit(1)

func (*Logger) Flush

func (l *Logger) Flush() error

Flush flushes the underlying loggers' buffers. Returns error if there are errors.

func (*Logger) Info

func (l *Logger) Info(payload interface{}, keysAndValues ...interface{})

Info writes a structured log entry using the info level.

func (*Logger) Infof

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

Infof writes info level logs

func (*Logger) Panic

func (l *Logger) Panic(payload interface{}, keysAndValues ...interface{})

Panic writes a structured log entry using the fatal level. Compatibility alias for Fatal().

func (*Logger) Panicf

func (l *Logger) Panicf(format string, args ...interface{})

Panicf writes fatal level logs and exits. Compatibility alias for Fatalf().

func (*Logger) Print

func (l *Logger) Print(payload interface{}, keysAndValues ...interface{})

Print writes a structured log entry using the debug level. Compatibility alias for Debug().

func (*Logger) Printf

func (l *Logger) Printf(format string, args ...interface{})

Printf writes debug level logs. Compatibility alias for Debugf().

func (*Logger) SetLogLevel

func (l *Logger) SetLogLevel(logLevel Level) *Logger

SetLogLevel sets the log levels of the underlying logger interfaces. Note that this operation is not mutexed and thus not inherently thread-safe.

func (*Logger) Trace

func (l *Logger) Trace(payload interface{}, keysAndValues ...interface{})

Trace writes a structured log entry using the debug level.

func (*Logger) Tracef

func (l *Logger) Tracef(format string, args ...interface{})

Tracef writes debug level logs. Compatibility alias for Debugf().

func (*Logger) Warning

func (l *Logger) Warning(payload interface{}, keysAndValues ...interface{})

Warning writes a structured log entry using the warning level.

func (*Logger) Warningf

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

Warningf writes warning level logs

func (*Logger) WithAdditionalKeysAndValues

func (l *Logger) WithAdditionalKeysAndValues(
	keysAndValues ...interface{}) *Logger

WithAdditionalKeysAndValues creates a new logger that uses the current logger as its base logger (all logging calls will be forwarded to the base logger). Making changes to the base logger will be reflected in any calls to the new logger. Additional keys and values may be added for structured logging purposes. This is a light operation. Panics if number of elements in keysAndValues is not even. Panics on internal errors.

Example

// Allocates a null logger with no actual backends
baseLog, _ := NewLogger(WithCommonKeysAndValues("key1", "value1"))

// Create a "sub" logger that inherits the default keys and values from
// its defined baselogger (baseLog)
subLog := baseLog.WithAdditionalKeysAndValues("key2", "value2")
subLog.Debug("Sublog debug message", "label", "value")

type OutputHint

type OutputHint int32

OutputHint provides a mechanism to instruct log backends to adjust their output / formatting. Not all log backends react to any / all of the hints.

const (
	// JSONFormat output hint requests the log backend to output JSON(NL).
	JSONFormat OutputHint = iota
)