otelzap

README

OpenTelemetry Zap Log Bridge

Documentation

Overview

Package otelzap provides a bridge between the go.uber.org/zap and OpenTelemetry.

Record Conversion

The zapcore.Entry and zapcore.Field are converted to OpenTelemetry log.Record in the following way:

• Time is set as the Timestamp.
• Message is set as the Body using a log.StringValue.
• Level is transformed and set as the Severity. The SeverityText is also set.
• Fields are transformed and set as the Attributes.
• Field value of type context.Context is used as context when emitting log records.
• For named loggers, LoggerName is used to access log.Logger from log.LoggerProvider

The Level is transformed to the OpenTelemetry Severity types in the following way.

• zapcore.DebugLevel is transformed to log.SeverityDebug
• zapcore.InfoLevel is transformed to log.SeverityInfo
• zapcore.WarnLevel is transformed to log.SeverityWarn
• zapcore.ErrorLevel is transformed to log.SeverityError
• zapcore.DPanicLevel is transformed to log.SeverityFatal1
• zapcore.PanicLevel is transformed to log.SeverityFatal2
• zapcore.FatalLevel is transformed to log.SeverityFatal3

Fields are transformed based on their type into log attributes, or into a string value encoded using fmt.Sprintf if there is no matching type.

Example

package main

import (
	"context"

	"go.opentelemetry.io/contrib/bridges/otelzap"
	"go.opentelemetry.io/otel/log/noop"

	"go.uber.org/zap"
)

func main() {
	// Use a working LoggerProvider implementation instead e.g. use go.opentelemetry.io/otel/sdk/log.
	provider := noop.NewLoggerProvider()

	// Initialize a zap logger with the otelzap bridge core.
	// This method actually doesn't log anything on your STDOUT, as everything
	// is shipped to a configured otel endpoint.
	logger := zap.New(otelzap.NewCore("my/pkg/name", otelzap.WithLoggerProvider(provider)))

	// You can now use your logger in your code.
	logger.Info("something really cool")

	// You can set context for trace correlation using zap.Any or zap.Reflect
	ctx := context.Background()
	logger.Info("setting context", zap.Any("context", ctx))
}

Example (Multiple)

package main

import (
	"os"

	"go.opentelemetry.io/contrib/bridges/otelzap"
	"go.opentelemetry.io/otel/log/noop"

	"go.uber.org/zap"
	"go.uber.org/zap/zapcore"
)

func main() {
	// Use a working LoggerProvider implementation instead e.g. use go.opentelemetry.io/otel/sdk/log.
	provider := noop.NewLoggerProvider()

	// If you want to log also on stdout, you can initialize a new zap.Core
	// that has multiple outputs using the method zap.NewTee(). With the following code,
	// logs will be written to stdout and also exported to the OTEL endpoint through the bridge.
	core := zapcore.NewTee(
		zapcore.NewCore(zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()), zapcore.AddSync(os.Stdout), zapcore.InfoLevel),
		otelzap.NewCore("my/pkg/name", otelzap.WithLoggerProvider(provider)),
	)
	logger := zap.New(core)

	// You can now use your logger in your code.
	logger.Info("something really cool")
}

Index

• type Core
  • func NewCore(name string, opts ...Option) *Core
  • func (o *Core) Check(ent zapcore.Entry, ce *zapcore.CheckedEntry) *zapcore.CheckedEntry
  • func (o *Core) Enabled(level zapcore.Level) bool
  • func (o *Core) Sync() error
  • func (o *Core) With(fields []zapcore.Field) zapcore.Core
  • func (o *Core) Write(ent zapcore.Entry, fields []zapcore.Field) error
• type Option
  • func WithLoggerProvider(provider log.LoggerProvider) Option
  • func WithSchemaURL(schemaURL string) Option
  • func WithVersion(version string) Option

Examples

• Package
• Package (Multiple)

Types

type Core

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

Core is a zapcore.Core that sends logging records to OpenTelemetry.

func NewCore

func NewCore(name string, opts ...Option) *Core

NewCore creates a new zapcore.Core that can be used with go.uber.org/zap.New. The name should be the package import path that is being logged. The name is ignored for named loggers created using go.uber.org/zap.Logger.Named.

func (*Core) Check

func (o *Core) Check(ent zapcore.Entry, ce *zapcore.CheckedEntry) *zapcore.CheckedEntry

Check determines whether the supplied Entry should be logged. If the entry should be logged, the Core adds itself to the CheckedEntry and returns the result.

func (*Core) Enabled

func (o *Core) Enabled(level zapcore.Level) bool

Enabled decides whether a given logging level is enabled when logging a message.

func (*Core) Sync

func (o *Core) Sync() error

Sync flushes buffered logs (if any).

func (*Core) With

func (o *Core) With(fields []zapcore.Field) zapcore.Core

With adds structured context to the Core.

func (*Core) Write

func (o *Core) Write(ent zapcore.Entry, fields []zapcore.Field) error

Write method encodes zap fields to OTel logs and emits them.

type Option

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

Option configures a Core.

func WithLoggerProvider

func WithLoggerProvider(provider log.LoggerProvider) Option

WithLoggerProvider returns an Option that configures log.LoggerProvider used by a Core to create its log.Logger.

By default if this Option is not provided, the Handler will use the global LoggerProvider.

func WithSchemaURL

func WithSchemaURL(schemaURL string) Option

WithSchemaURL returns an Option that configures the semantic convention schema URL of the log.Logger used by a Core. The schemaURL should be the schema URL for the semantic conventions used in log records.

func WithVersion

func WithVersion(version string) Option

WithVersion returns an Option that configures the version of the log.Logger used by a Core. The version should be the version of the package that is being logged.