uzap

README

⚡ uzap

This repo contains basic configuration for go.uber.org/zap, for easy use with 12-factor apps.

Usage

defer uzap.MustZap()()

Example:

import (
	"go.uber.org/zap"
	"github.com/Unity-Technologies/uzap"
)

// For ease of use, call this in main(), as the first statement
defer uzap.MustZap()()

// Example
zap.L().Info("failed to fetch URL",
	// Structured context as strongly typed Field values.
	zap.String("url", url),
	zap.Int("attempt", 3),
	zap.Duration("backoff", time.Second),
)
log.Println("std log example")

Customizable examble

logger, level := uzap.NewZapLogger(&uzap.Options{})
zap.ReplaceGlobals(logger)
zap.RedirectStdLog(logger)
defer logger.Sync() // nolint:errcheck

Features

On it's own this does mostly nothing, go.uber.org/zap is the logger, this just makes a few assumptions about how you'd use zap to make it even easier.

• It uses a global variable to reference the logger, which allows it to be used from anywhere without prior knowledge, ie. just call zap.L() without worrying about the details.
• It has a one-liner for ease of use.
• It sends informational logs to stdout and higher priority logs to stderr, which is needed for production-ready kubernetes logging.
• It encodes the output in a stackdriver friendly (but not overly specific) (json) format.
• It has an atomic log level, so it can be safely modified from anywhere.
• It optionally supports a human friendly debug output.
• It reads config from environment variables (can be changed/overridden afterwards).

Documentation

Overview

Package uzap contains basic configuration for go.uber.org/zap, for easy use with 12-factor apps.

Index

• func MustZap() func()
• func MustZapWithLevel(lvl zapcore.Level) func()
• func NewZapLogger(opts *Options) (*zap.Logger, zap.AtomicLevel)
• type Options

Functions

func MustZap

func MustZap() func()

MustZap is an ease of use function that replaces zap globals and redirects standard `package log` output to a new zap logger. It returns a deferrable function, for calling zap.Logger.Sync at program termination.

func MustZapWithLevel

func MustZapWithLevel(lvl zapcore.Level) func()

MustZapWithLevel is an ease of use function that replaces zap globals and redirects standard `package log` output to a new zap logger. It returns a deferrable function, for calling zap.Logger.Sync at program termination.

func NewZapLogger

func NewZapLogger(opts *Options) (*zap.Logger, zap.AtomicLevel)

NewZapLogger configures a zap.Logger for use in container based environments ERROR level logs are written to stderr and all other levels are written to stdout Useful in Kubernetes where stderr & stdout are interpreted as ERROR & INFO level logs respectively opts.Debug controls the loggers output. Human readable when true; JSON when false.

Types

type Options

type Options struct {
	Level              zapcore.Level                                 // zap defaults to INFO
	Debug              bool                                          // defaults to false, displays human readable output instead of json
	SamplingInitial    int                                           `default:"100" split_words:"true"`
	SamplingThereafter int                                           `default:"100" split_words:"true"`
	SamplingHook       func(zapcore.Entry, zapcore.SamplingDecision) `ignored:"true"`
}

Options is used to parse environment vars with the log level and optional debug flag.