zapr

README

Zapr

Zapr provides a logr.LogSink implementation using zap. It includes optional flag registration, Prometheus metrics, and a standard library *log.Logger adapter.

Example

addr := flag.String("http-address", ":8080", "HTTP server listen address.")
zaprObserver := zaprprom.NewObserver()
zaprOptions := zapr.RegisterFlags(flag.CommandLine, zapr.AllOptions(
    zapr.WithObserver(zaprObserver),
    zapr.WithLevel(2), // Override default logging level.
)...)
flag.Parse()

log, sink := zapr.NewLogger(zaprOptions...)
defer sink.Flush() // For most GOOS (linux and darwin), flushing to stderr is a no-op.
log.Info("Hello, zap logr with option flags!")

reg := prometheus.NewRegistry()
reg.MustRegister(
    collectors.NewGoCollector(),
    collectors.NewBuildInfoCollector(),
    collectors.NewProcessCollector(collectors.ProcessCollectorOpts{}),
    zaprObserver, // Register Observer with Prometheus.
)
log.Info("Hello, zap logr Prometheus metrics!")

mux := http.NewServeMux()
mux.Handle("/metrics", promhttp.HandlerFor(reg, promhttp.HandlerOpts{}))

srv := http.Server{
    Addr:     *addr,
    Handler:  mux,
    ErrorLog: zapr.NewStdErrorLogger(sink), // Adapt LogSink to stdlib *log.Logger.
}
if err := srv.ListenAndServe(); err != nil {
    log.Error(err, "Failed to serve HTTP")
}

Documentation

Overview

Package zapr provides a logr.Logger interface around a zap implementation, including metrics and a standard library log.Logger adapter.

Index

• func NewStdErrorLogger(s logr.CallDepthLogSink) *log.Logger
• func NewStdInfoLogger(s logr.CallDepthLogSink) *log.Logger
• type LazyLogSink
  • func NewLazyLogSink() LazyLogSink
• type LogSink
  • func NewLogSink(options ...Option) LogSink
  • func NewLogger(options ...Option) (logr.Logger, LogSink)
• type Observer
• type Option
  • func AllOptions(overrides ...Option) []Option
  • func RegisterFlags(fs *flag.FlagSet, options ...Option) []Option
  • func WithCallerEnabled(enabled bool) Option
  • func WithCallerEncoder(encoder encoding.CallerEncoder) Option
  • func WithCallerKey(key string) Option
  • func WithDevelopmentOptions(enabled bool) Option
  • func WithDurationEncoder(encoder encoding.DurationEncoder) Option
  • func WithEncoder(encoder encoding.Encoder) Option
  • func WithErrorKey(key string) Option
  • func WithFunctionKey(key string) Option
  • func WithLevel(level int) Option
  • func WithLevelEncoder(encoder encoding.LevelEncoder) Option
  • func WithLevelKey(key string) Option
  • func WithLineEnding(ending string) Option
  • func WithMessageKey(key string) Option
  • func WithName(name string) Option
  • func WithNameKey(key string) Option
  • func WithObserver(observer Observer) Option
  • func WithSampler(tick time.Duration, first, thereafter int, opts ...zapcore.SamplerOption) Option
  • func WithStacktraceEnabled(enabled bool) Option
  • func WithStacktraceKey(key string) Option
  • func WithTimeEncoder(encoder encoding.TimeEncoder) Option
  • func WithTimeKey(key string) Option
  • func WithWriteSyncer(ws zapcore.WriteSyncer) Option

Examples

• NewLogger

Functions

func NewStdErrorLogger

func NewStdErrorLogger(s logr.CallDepthLogSink) *log.Logger

NewStdErrorLogger returns a *log.Logger which writes to the supplied Logger's Error method.

func NewStdInfoLogger

func NewStdInfoLogger(s logr.CallDepthLogSink) *log.Logger

NewStdInfoLogger returns a *log.Logger which writes to the supplied Logger's Info method.

Types

type LazyLogSink

type LazyLogSink interface {
	LogSink

	// SetSink sets the underlying LogSink for the LazyLogSink and all of
	// its descendants created by WithDepth, WithName, or WithValues.
	SetSink(LogSink)
}

LazyLogSink is a LogSink whose underlying implementation can be updated after it's been used to create log.Loggers.

func NewLazyLogSink

func NewLazyLogSink() LazyLogSink

NewLazyLogSink returns a new Sink that discards logs until SetSink is called.

type LogSink

type LogSink interface {
	logr.LogSink
	logr.CallDepthLogSink

	// Underlying returns the underlying *zap.Logger with no caller skips.
	// Any names or added keys and values remain.
	Underlying() *zap.Logger

	// Flush writes any buffered data to the underlying io.Writer.
	Flush() error
}

LogSink represents the ability to log messages, both errors and not.

func NewLogSink

func NewLogSink(options ...Option) LogSink

NewLogSink returns a new LogSink with the given options.

func NewLogger

func NewLogger(options ...Option) (logr.Logger, LogSink)

NewLogger returns a new Logger with the given options and a flush function.

Example

package main

import (
	"flag"
	"net/http"

	"bursavich.dev/zapr"
	"bursavich.dev/zapr/zaprprom"
	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/client_golang/prometheus/collectors"
	"github.com/prometheus/client_golang/prometheus/promhttp"
)

func main() {
	addr := flag.String("http-address", ":8080", "HTTP server listen address.")
	zaprObserver := zaprprom.NewObserver()
	zaprOptions := zapr.RegisterFlags(flag.CommandLine, zapr.AllOptions(
		zapr.WithObserver(zaprObserver),
		zapr.WithLevel(2), // Override default logging level.
	)...)
	flag.Parse()

	log, sink := zapr.NewLogger(zaprOptions...)
	defer sink.Flush() // For most GOOS (linux and darwin), flushing to stderr is a no-op.
	log.Info("Hello, zap logr with option flags!")

	reg := prometheus.NewRegistry()
	reg.MustRegister(
		collectors.NewGoCollector(),
		collectors.NewBuildInfoCollector(),
		collectors.NewProcessCollector(collectors.ProcessCollectorOpts{}),
		zaprObserver, // Register Observer with Prometheus.
	)
	log.Info("Hello, zap logr Prometheus metrics!")

	mux := http.NewServeMux()
	mux.Handle("/metrics", promhttp.HandlerFor(reg, promhttp.HandlerOpts{}))

	srv := http.Server{
		Addr:     *addr,
		Handler:  mux,
		ErrorLog: zapr.NewStdErrorLogger(sink), // Adapt LogSink to stdlib *log.Logger.
	}
	if err := srv.ListenAndServe(); err != nil {
		log.Error(err, "Failed to serve HTTP")
	}
}

type Observer

type Observer interface {
	// Init initializes metrics for the named logger when it's created.
	// Logger names are not required to be unique and it may be called
	// with a duplicate name at any time.
	Init(logger string)

	// ObserveEntryLogged observes logged entry metrics for the named logger, at
	// the given level, and with the given bytes.
	ObserveEntryLogged(logger string, level string, bytes int)

	// ObserveEncoderError observes an error encoding an entry for the named logger.
	ObserveEncoderError(logger string)
}

Observer represent the ability to observe log metrics.

type Option

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

An Option applies optional configuration.

func AllOptions

func AllOptions(overrides ...Option) []Option

AllOptions returns all Options with the given overrides.

func RegisterFlags

func RegisterFlags(fs *flag.FlagSet, options ...Option) []Option

RegisterFlags registers the given Options with the FlagSet.

func WithCallerEnabled

func WithCallerEnabled(enabled bool) Option

WithCallerEnabled returns an Option that sets whether the caller field is enabled. It's enabled by default.

func WithCallerEncoder

func WithCallerEncoder(encoder encoding.CallerEncoder) Option

WithCallerEncoder returns an Option that sets the caller encoder. The default encoding is short.

func WithCallerKey

func WithCallerKey(key string) Option

WithCallerKey returns an Option that sets the caller key. The default value is "caller".

func WithDevelopmentOptions

func WithDevelopmentOptions(enabled bool) Option

WithDevelopmentOptions returns an Option that enables a set of development-friendly options.

func WithDurationEncoder

func WithDurationEncoder(encoder encoding.DurationEncoder) Option

WithDurationEncoder returns an Option that sets the duration encoder. The default encoding is seconds.

func WithEncoder

func WithEncoder(encoder encoding.Encoder) Option

WithEncoder returns an Option that sets the encoder. The default value is a JSONEncoder.

func WithErrorKey

func WithErrorKey(key string) Option

WithErrorKey returns an Option that sets the error key. The default value is "error".

func WithFunctionKey

func WithFunctionKey(key string) Option

WithFunctionKey returns an Option that sets the function key. The default value is empty.

func WithLevel

func WithLevel(level int) Option

WithLevel returns an Option that sets the level. The default value is 0.

func WithLevelEncoder

func WithLevelEncoder(encoder encoding.LevelEncoder) Option

WithLevelEncoder returns an Option that sets the level encoder. The default encoding is uppercase.

func WithLevelKey

func WithLevelKey(key string) Option

WithLevelKey returns an Option that sets the level key. The default value is "level".

func WithLineEnding

func WithLineEnding(ending string) Option

WithLineEnding returns an Option that sets the line-ending. The default value is "\n".

func WithMessageKey

func WithMessageKey(key string) Option

WithMessageKey returns an Option that sets the message key. The default value is "message".

func WithName

func WithName(name string) Option

WithName returns an Option that sets the name. The default value is empty.

func WithNameKey

func WithNameKey(key string) Option

WithNameKey returns an Option that sets the name key. The default value is "logger".

func WithObserver

func WithObserver(observer Observer) Option

WithObserver returns an Option that sets the metrics Observer. There is no default Observer.

func WithSampler

func WithSampler(tick time.Duration, first, thereafter int, opts ...zapcore.SamplerOption) Option

WithSampler returns an Option that sets sampler options. The default is 1s tick, 100 first, and 100 thereafter.

func WithStacktraceEnabled

func WithStacktraceEnabled(enabled bool) Option

WithStacktraceEnabled returns an Option that sets whether the stacktrace field is enabled. It's disabled by default.

func WithStacktraceKey

func WithStacktraceKey(key string) Option

WithStacktraceKey returns an Option that sets the stacktrace key. The default value is "stacktrace".

func WithTimeEncoder

func WithTimeEncoder(encoder encoding.TimeEncoder) Option

WithTimeEncoder returns an Option that sets the encoder. The default encoding is ISO 8601.

func WithTimeKey

func WithTimeKey(key string) Option

WithTimeKey returns an Option that sets the time key. The default value is "time".

func WithWriteSyncer

func WithWriteSyncer(ws zapcore.WriteSyncer) Option

WithWriteSyncer returns an Option that sets the underlying writer. The default value is stderr.