zlg

README

zlg (zerolog-gcp)

zlg is a (hopefully) straightforward LevelWriter for using zerolog with Google Cloud Operations Logging, which used to be named Stackdriver.

Some notable features:

• The first log written to Cloud Logging is a slow, blocking write to confirm connectivity + permissions, but all subsequent writes are non-blocking.
• Handles converting zerolog.WarnLevel to logging.Warning.
• Zerolog's trace level maps to Cloud Logging's Default level.
• Cloud Logging's Alert and Emergency levels are not used.
• Ensure that all zlg-created loggers are flushed before program exit with defer zlg.Flush()

Getting Started

The usual cases

Logging only to Stackdriver:

import zlg "github.com/mark-ignacio/zerolog-gcp"

// [...]

gcpWriter, err := zlg.NewCloudLoggingWriter(ctx, projectID, logID, zlg.CloudLoggingOptions{})
if err != nil {
    log.Panic().Err(err).Msg("could not create a CloudLoggingWriter")
}
log.Logger = log.Output(gcpWriter)

For non-GCP-hosted situations, you can log to both the console and GCP without much additional fuss.

gcpWriter, err := zlg.NewCloudLoggingWriter(ctx, projectID, logID, zlg.CloudLoggingOptions{})
if err != nil {
    log.Panic().Err(err).Msg("could not create a CloudLoggingWriter")
}
log.Logger = log.Output(zerolog.MultiLevelWriter(
    zerolog.NewConsoleWriter(), 
    gcpWriter,
))

To ensure that the last asynchronous logs are delivered to Cloud Logging, zlg keeps a reference to all logging.Logger structs that zlg itself creates. If memory leaks of loggers are a concern, consider specifying providing a logger client via zlg.CloudLoggingOptions instead.

gcpWriter, err := zlg.NewCloudLoggingWriter(ctx, projectID, logID, zlg.CloudLoggingOptions{})
if err != nil {
    log.Panic().Err(err).Msg("could not create a CloudLoggingWriter")
}
defer zlg.Flush()
doEverythingElse()

More advanced usage involves a non-empty zlg.CloudLoggingOptions.

Documentation

Index

• Variables
• func Flush()
• func NewCloudLoggingWriter(ctx context.Context, projectID, logID string, opts CloudLoggingOptions) (writer zerolog.LevelWriter, err error)
• type CloudLoggingOptions

Variables

var DefaultSeverityMap = map[zerolog.Level]logging.Severity{
	zerolog.DebugLevel: logging.Debug,
	zerolog.InfoLevel:  logging.Info,
	zerolog.WarnLevel:  logging.Warning,
	zerolog.ErrorLevel: logging.Error,
	zerolog.PanicLevel: logging.Critical,
	zerolog.FatalLevel: logging.Critical,
}

DefaultSeverityMap contains the default zerolog.Level -> logging.Severity mappings.

Functions

func Flush

func Flush()

Flush blocks while flushing all loggers this module created.

func NewCloudLoggingWriter

func NewCloudLoggingWriter(ctx context.Context, projectID, logID string, opts CloudLoggingOptions) (writer zerolog.LevelWriter, err error)

NewCloudLoggingWriter creates a LevelWriter that logs only to GCP Cloud Logging using non-blocking calls.

Types

type CloudLoggingOptions

type CloudLoggingOptions struct {
	// SeverityMap can be optionally specified to use instead of DefaultSeverityMap.
	SeverityMap map[zerolog.Level]logging.Severity

	// Logger can be optionally provided in lieu of constructing a logger on the caller's behalf.
	Logger *logging.Logger

	// LoggerOptions is optionally used to construct a Logger.
	LoggerOptions []logging.LoggerOption
}

CloudLoggingOptions specifies some optional configuration.