gcloudzap

README

⚡ gcloudzap

(pre-release)

This package provides a zap logger that forwards entries to the Google Stackdriver Logging service as structured payloads.

Quickstart

Outside of Google Compute Engine, just add the environment variable GOOGLE_APPLICATION_CREDENTIALS with a path to a JSON credential file. For more info on this approach, see the docs.

Option 1: Less configuration

import "github.com/jonstaryuk/gcloudzap"

log, err := gcloudzap.NewDevelopment("your-project-id", "your-log-id")
if err != nil {
    panic(err)
}

log.Sugar().
    With("simple", true).
    With("foo", "bar").
    Info("This will get written to both stderr and Stackdriver Logging.")

Option 2: More flexibility

import (
    "go.uber.org/zap"
    "cloud.google.com/go/logging"
    "github.com/jonstaryuk/gcloudzap"
)

// Configure the pieces
client, err := logging.NewClient(...)
cfg := zap.Config{...}

// Create a logger
log, err := gcloudzap.New(cfg, client, "your-log-id", zap.Option(), ...)

Option 3: Most flexibility

import (
    "go.uber.org/zap/zapcore"
    "cloud.google.com/go/logging"
    "github.com/jonstaryuk/gcloudzap"
)

// Configure the pieces
client, err := logging.NewClient(...)
baseCore := zapcore.NewCore(...)

// Create a core
core := gcloudzap.Tee(baseCore, client, "your-log-id")

Documentation

Overview

Package gcloudzap provides a zap logger that forwards entries to the Google Stackdriver Logging service as structured payloads.

All zap.Logger instances created with this package are safe for concurrent use.

Network calls (which are delegated to the Google Cloud Platform package) are asynchronous and payloads are buffered. These benchmarks, on a MacBook Pro 2.4 GHz Core i5, are a loose approximation of latencies on the critical path for the zapcore.Core implementation provided by this package.

$ go test -bench . github.com/jonstaryuk/gcloudzap
goos: darwin
goarch: amd64
pkg: github.com/jonstaryuk/gcloudzap
BenchmarkCoreClone-4   	 2000000	       607 ns/op
BenchmarkCoreWrite-4   	 1000000	      2811 ns/op

Zap docs: https://godoc.org/go.uber.org/zap

Stackdriver Logging docs: https://cloud.google.com/logging/docs/

Index

• Variables
• func New(cfg zap.Config, client *gcl.Client, logID string, opts ...zap.Option) (*zap.Logger, error)
• func NewDevelopment(projectID string, logID string) (*zap.Logger, error)
• func NewProduction(projectID string, logID string) (*zap.Logger, error)
• func Tee(zc zapcore.Core, client *gcl.Client, gclLogID string) zapcore.Core
• type Core
  • func (c *Core) Check(e zapcore.Entry, ce *zapcore.CheckedEntry) *zapcore.CheckedEntry
  • func (c *Core) Enabled(l zapcore.Level) bool
  • func (c *Core) Sync() error
  • func (c *Core) With(newFields []zapcore.Field) zapcore.Core
  • func (c *Core) Write(ze zapcore.Entry, newFields []zapcore.Field) error
• type GoogleCloudLogger

Variables

var DefaultSeverityMapping = map[zapcore.Level]gcl.Severity{
	zapcore.DebugLevel:  gcl.Debug,
	zapcore.InfoLevel:   gcl.Info,
	zapcore.WarnLevel:   gcl.Warning,
	zapcore.ErrorLevel:  gcl.Error,
	zapcore.DPanicLevel: gcl.Critical,
	zapcore.PanicLevel:  gcl.Critical,
	zapcore.FatalLevel:  gcl.Critical,
}

DefaultSeverityMapping is the default mapping of zap's Levels to Google's Severities.

Functions

func New

func New(cfg zap.Config, client *gcl.Client, logID string, opts ...zap.Option) (*zap.Logger, error)

New creates a new zap.Logger which will write entries to Stackdriver in addition to the destination specified by the provided zap configuration.

func NewDevelopment

func NewDevelopment(projectID string, logID string) (*zap.Logger, error)

NewDevelopment builds a development Logger that writes DebugLevel and above logs to standard error in a human-friendly format, as well as to Stackdriver using Application Default Credentials.

func NewProduction

func NewProduction(projectID string, logID string) (*zap.Logger, error)

NewProduction builds a production Logger that writes InfoLevel and above logs to standard error as JSON, as well as to Stackdriver using Application Default Credentials.

func Tee

func Tee(zc zapcore.Core, client *gcl.Client, gclLogID string) zapcore.Core

Tee returns a zapcore.Core that writes entries to both the provided core and to Stackdriver using the provided client and log ID.

For fields to be written to Stackdriver, you must use the With() method on the returned Core rather than just on zc. (This function has no way of knowing about fields that already exist on zc. They will be preserved when writing to zc's existing destination, but not to Stackdriver.)

Types

type Core

type Core struct {
	// Logger is a logging.Logger instance from the Google Cloud Platform Go
	// library.
	Logger GoogleCloudLogger

	// Provide your own mapping of zapcore's Levels to Google's Severities, or
	// use DefaultSeverityMapping. All of the Core's children will default to
	// using this map.
	//
	// This must not be mutated after the Core's first use.
	SeverityMapping map[zapcore.Level]gcl.Severity

	// MinLevel is the minimum level for a log entry to be written.
	MinLevel zapcore.Level
	// contains filtered or unexported fields
}

A Core implements zapcore.Core and writes entries to a Logger from the Google Cloud package.

It's safe for concurrent use by multiple goroutines as long as it's not mutated after first use.

func (*Core) Check

func (c *Core) Check(e zapcore.Entry, ce *zapcore.CheckedEntry) *zapcore.CheckedEntry

Check implements zapcore.Core.

func (*Core) Enabled

func (c *Core) Enabled(l zapcore.Level) bool

Enabled implements zapcore.Core.

func (*Core) Sync

func (c *Core) Sync() error

Sync implements zapcore.Core. It flushes the Core's Logger instance.

func (*Core) With

func (c *Core) With(newFields []zapcore.Field) zapcore.Core

With implements zapcore.Core.

func (*Core) Write

func (c *Core) Write(ze zapcore.Entry, newFields []zapcore.Field) error

Write implements zapcore.Core. It writes a log entry to Stackdriver.

The "logger", "msg", "caller", and "stack" fields on the payload are populated from their respective values on the zapcore.Entry.

type GoogleCloudLogger

type GoogleCloudLogger interface {
	Flush() error
	Log(e gcl.Entry)
}

GoogleCloudLogger encapsulates the important methods of gcl.Logger