otelzap

README

OpenTelemetry Go instrumentation for Zap logging library

Moved to https://github.com/uptrace/opentelemetry-go-extra/tree/main/otelsql

Documentation

Index

• type Logger
  • func New(logger *zap.Logger, opts ...Option) *Logger
  • func Wrap(logger *zap.Logger, opts ...Option) *Logger
  • func (l *Logger) Clone(opts ...Option) *Logger
  • func (l *Logger) Ctx(ctx context.Context) LoggerWithCtx
  • func (l *Logger) DPanicContext(ctx context.Context, msg string, fields ...zapcore.Field)
  • func (l *Logger) DebugContext(ctx context.Context, msg string, fields ...zapcore.Field)
  • func (l *Logger) ErrorContext(ctx context.Context, msg string, fields ...zapcore.Field)
  • func (l *Logger) FatalContext(ctx context.Context, msg string, fields ...zapcore.Field)
  • func (l *Logger) InfoContext(ctx context.Context, msg string, fields ...zapcore.Field)
  • func (l *Logger) PanicContext(ctx context.Context, msg string, fields ...zapcore.Field)
  • func (l *Logger) Sugar() *SugaredLogger
  • func (l *Logger) WarnContext(ctx context.Context, msg string, fields ...zapcore.Field)
  • func (l *Logger) WithOptions(opts ...zap.Option) *Logger
• type LoggerWithCtx
  • func (l LoggerWithCtx) Clone(opts ...Option) LoggerWithCtx
  • func (l LoggerWithCtx) Context() context.Context
  • func (l LoggerWithCtx) DPanic(msg string, fields ...zapcore.Field)
  • func (l LoggerWithCtx) Debug(msg string, fields ...zapcore.Field)
  • func (l LoggerWithCtx) Error(msg string, fields ...zapcore.Field)
  • func (l LoggerWithCtx) Fatal(msg string, fields ...zapcore.Field)
  • func (l LoggerWithCtx) Info(msg string, fields ...zapcore.Field)
  • func (l LoggerWithCtx) Logger() *Logger
  • func (l LoggerWithCtx) Panic(msg string, fields ...zapcore.Field)
  • func (l LoggerWithCtx) Warn(msg string, fields ...zapcore.Field)
  • func (l LoggerWithCtx) WithOptions(opts ...zap.Option) LoggerWithCtx
  • func (l LoggerWithCtx) ZapLogger() *zap.Logger
• type Option
  • func WithCaller(on bool) Option
  • func WithErrorStatusLevel(lvl zapcore.Level) Option
  • func WithMinLevel(lvl zapcore.Level) Option
  • func WithStackTrace(on bool) Option
  • func WithTraceIDField(on bool) Option
• type SugaredLogger
  • func (s *SugaredLogger) Ctx(ctx context.Context) SugaredLoggerWithCtx
  • func (s *SugaredLogger) DPanicfContext(ctx context.Context, template string, args ...interface{})
  • func (s *SugaredLogger) DPanicwContext(ctx context.Context, msg string, keysAndValues ...interface{})
  • func (s *SugaredLogger) DebugfContext(ctx context.Context, template string, args ...interface{})
  • func (s *SugaredLogger) Desugar() *Logger
  • func (s *SugaredLogger) ErrorfContext(ctx context.Context, template string, args ...interface{})
  • func (s *SugaredLogger) ErrorwContext(ctx context.Context, msg string, keysAndValues ...interface{})
  • func (s *SugaredLogger) FatalfContext(ctx context.Context, template string, args ...interface{})
  • func (s *SugaredLogger) FatalwContext(ctx context.Context, msg string, keysAndValues ...interface{})
  • func (s *SugaredLogger) InfofContext(ctx context.Context, template string, args ...interface{})
  • func (s *SugaredLogger) InfowContext(ctx context.Context, msg string, keysAndValues ...interface{})
  • func (s *SugaredLogger) PanicfContext(ctx context.Context, template string, args ...interface{})
  • func (s *SugaredLogger) PanicwContext(ctx context.Context, msg string, keysAndValues ...interface{})
  • func (s *SugaredLogger) WarnfContext(ctx context.Context, template string, args ...interface{})
  • func (s *SugaredLogger) WarnwContext(ctx context.Context, msg string, keysAndValues ...interface{})
  • func (s *SugaredLogger) With(args ...interface{}) *SugaredLogger
• type SugaredLoggerWithCtx
  • func (s SugaredLoggerWithCtx) DPanicf(template string, args ...interface{})
  • func (s SugaredLoggerWithCtx) DPanicw(msg string, keysAndValues ...interface{})
  • func (s SugaredLoggerWithCtx) Debugf(template string, args ...interface{})
  • func (s SugaredLoggerWithCtx) Debugw(msg string, keysAndValues ...interface{})
  • func (s SugaredLoggerWithCtx) Desugar() *Logger
  • func (s SugaredLoggerWithCtx) Errorf(template string, args ...interface{})
  • func (s SugaredLoggerWithCtx) Errorw(msg string, keysAndValues ...interface{})
  • func (s SugaredLoggerWithCtx) Fatalf(template string, args ...interface{})
  • func (s SugaredLoggerWithCtx) Fatalw(msg string, keysAndValues ...interface{})
  • func (s SugaredLoggerWithCtx) Infof(template string, args ...interface{})
  • func (s SugaredLoggerWithCtx) Infow(msg string, keysAndValues ...interface{})
  • func (s SugaredLoggerWithCtx) Panicf(template string, args ...interface{})
  • func (s SugaredLoggerWithCtx) Panicw(msg string, keysAndValues ...interface{})
  • func (s SugaredLoggerWithCtx) Warnf(template string, args ...interface{})
  • func (s SugaredLoggerWithCtx) Warnw(msg string, keysAndValues ...interface{})

Types

type Logger

type Logger struct {
	*zap.Logger
	// contains filtered or unexported fields
}

Logger is a thin wrapper for zap.Logger that adds Ctx method.

func New

func New(logger *zap.Logger, opts ...Option) *Logger

func Wrap

func Wrap(logger *zap.Logger, opts ...Option) *Logger

Deprecated. Use New instead.

func (*Logger) Clone

func (l *Logger) Clone(opts ...Option) *Logger

Clone clones the current logger applying the supplied options.

func (*Logger) Ctx

func (l *Logger) Ctx(ctx context.Context) LoggerWithCtx

Ctx returns a new logger with the context.

func (*Logger) DPanicContext

func (l *Logger) DPanicContext(ctx context.Context, msg string, fields ...zapcore.Field)

func (*Logger) DebugContext

func (l *Logger) DebugContext(ctx context.Context, msg string, fields ...zapcore.Field)

func (*Logger) ErrorContext

func (l *Logger) ErrorContext(ctx context.Context, msg string, fields ...zapcore.Field)

func (*Logger) FatalContext

func (l *Logger) FatalContext(ctx context.Context, msg string, fields ...zapcore.Field)

func (*Logger) InfoContext

func (l *Logger) InfoContext(ctx context.Context, msg string, fields ...zapcore.Field)

func (*Logger) PanicContext

func (l *Logger) PanicContext(ctx context.Context, msg string, fields ...zapcore.Field)

func (*Logger) Sugar

func (l *Logger) Sugar() *SugaredLogger

Sugar wraps the Logger to provide a more ergonomic, but slightly slower, API. Sugaring a Logger is quite inexpensive, so it's reasonable for a single application to use both Loggers and SugaredLoggers, converting between them on the boundaries of performance-sensitive code.

func (*Logger) WarnContext

func (l *Logger) WarnContext(ctx context.Context, msg string, fields ...zapcore.Field)

func (*Logger) WithOptions

func (l *Logger) WithOptions(opts ...zap.Option) *Logger

WithOptions clones the current Logger, applies the supplied Options, and returns the resulting Logger. It's safe to use concurrently.

type LoggerWithCtx

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

LoggerWithCtx is a wrapper for Logger that also carries a context.Context.

func (LoggerWithCtx) Clone

func (l LoggerWithCtx) Clone(opts ...Option) LoggerWithCtx

Clone clones the current logger applying the supplied options.

func (LoggerWithCtx) Context

func (l LoggerWithCtx) Context() context.Context

Context returns logger's context.

func (LoggerWithCtx) DPanic

func (l LoggerWithCtx) DPanic(msg string, fields ...zapcore.Field)

DPanic logs a message at DPanicLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

If the logger is in development mode, it then panics (DPanic means "development panic"). This is useful for catching errors that are recoverable, but shouldn't ever happen.

func (LoggerWithCtx) Debug

func (l LoggerWithCtx) Debug(msg string, fields ...zapcore.Field)

Debug logs a message at DebugLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

func (LoggerWithCtx) Error

func (l LoggerWithCtx) Error(msg string, fields ...zapcore.Field)

Error logs a message at ErrorLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

func (LoggerWithCtx) Fatal

func (l LoggerWithCtx) Fatal(msg string, fields ...zapcore.Field)

Fatal logs a message at FatalLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

The logger then calls os.Exit(1), even if logging at FatalLevel is disabled.

func (LoggerWithCtx) Info

func (l LoggerWithCtx) Info(msg string, fields ...zapcore.Field)

Info logs a message at InfoLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

func (LoggerWithCtx) Logger

func (l LoggerWithCtx) Logger() *Logger

Logger returns the underlying logger.

func (LoggerWithCtx) Panic

func (l LoggerWithCtx) Panic(msg string, fields ...zapcore.Field)

Panic logs a message at PanicLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

The logger then panics, even if logging at PanicLevel is disabled.

func (LoggerWithCtx) Warn

func (l LoggerWithCtx) Warn(msg string, fields ...zapcore.Field)

Warn logs a message at WarnLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

func (LoggerWithCtx) WithOptions

func (l LoggerWithCtx) WithOptions(opts ...zap.Option) LoggerWithCtx

WithOptions clones the current Logger, applies the supplied Options, and returns the resulting Logger. It's safe to use concurrently.

func (LoggerWithCtx) ZapLogger

func (l LoggerWithCtx) ZapLogger() *zap.Logger

ZapLogger returns the underlying zap logger.

type Option

type Option func(l *Logger)

Option applies a configuration to the given config.

func WithCaller

func WithCaller(on bool) Option

WithCaller configures the logger to annotate each event with the filename, line number, and function name of the caller.

It is enabled by default.

func WithErrorStatusLevel

func WithErrorStatusLevel(lvl zapcore.Level) Option

WithErrorStatusLevel sets the minimal zap logging level on which the span status is set to codes.Error.

The default is >= zap.ErrorLevel.

func WithMinLevel

func WithMinLevel(lvl zapcore.Level) Option

WithMinLevel sets the minimal zap logging level on which the log message is recorded on the span.

The default is >= zap.WarnLevel.

func WithStackTrace

func WithStackTrace(on bool) Option

WithStackTrace configures the logger to capture logs with a stack trace.

func WithTraceIDField

func WithTraceIDField(on bool) Option

WithTraceID configures the logger to add `trace_id` field to structured log messages.

This option is only useful with backends that don't support OTLP and instead parse log messages to extract structured information.

type SugaredLogger

type SugaredLogger struct {
	*zap.SugaredLogger
	// contains filtered or unexported fields
}

A SugaredLogger wraps the base Logger functionality in a slower, but less verbose, API. Any Logger can be converted to a SugaredLogger with its Sugar method.

Unlike the Logger, the SugaredLogger doesn't insist on structured logging. For each log level, it exposes three methods: one for loosely-typed structured logging, one for println-style formatting, and one for printf-style formatting. For example, SugaredLoggers can produce InfoLevel output with Infow ("info with" structured context), Info, or Infof.

func (*SugaredLogger) Ctx

func (s *SugaredLogger) Ctx(ctx context.Context) SugaredLoggerWithCtx

Ctx returns a new sugared logger with the context.

func (*SugaredLogger) DPanicfContext

func (s *SugaredLogger) DPanicfContext(ctx context.Context, template string, args ...interface{})

DPanicf uses fmt.Sprintf to log a templated message. In development, the logger then panics. (See DPanicLevel for details.)

func (*SugaredLogger) DPanicwContext

func (s *SugaredLogger) DPanicwContext(
	ctx context.Context, msg string, keysAndValues ...interface{},
)

DPanicw logs a message with some additional context. In development, the logger then panics. (See DPanicLevel for details.) The variadic key-value pairs are treated as they are in With.

func (*SugaredLogger) DebugfContext

func (s *SugaredLogger) DebugfContext(ctx context.Context, template string, args ...interface{})

Debugf uses fmt.Sprintf to log a templated message.

func (*SugaredLogger) Desugar

func (s *SugaredLogger) Desugar() *Logger

Desugar unwraps a SugaredLogger, exposing the original Logger. Desugaring is quite inexpensive, so it's reasonable for a single application to use both Loggers and SugaredLoggers, converting between them on the boundaries of performance-sensitive code.

func (*SugaredLogger) ErrorfContext

func (s *SugaredLogger) ErrorfContext(ctx context.Context, template string, args ...interface{})

Errorf uses fmt.Sprintf to log a templated message.

func (*SugaredLogger) ErrorwContext

func (s *SugaredLogger) ErrorwContext(
	ctx context.Context, msg string, keysAndValues ...interface{},
)

Errorw logs a message with some additional context. The variadic key-value pairs are treated as they are in With.

func (*SugaredLogger) FatalfContext

func (s *SugaredLogger) FatalfContext(ctx context.Context, template string, args ...interface{})

Fatalf uses fmt.Sprintf to log a templated message, then calls os.Exit.

func (*SugaredLogger) FatalwContext

func (s *SugaredLogger) FatalwContext(
	ctx context.Context, msg string, keysAndValues ...interface{},
)

Fatalw logs a message with some additional context, then calls os.Exit. The variadic key-value pairs are treated as they are in With.

func (*SugaredLogger) InfofContext

func (s *SugaredLogger) InfofContext(ctx context.Context, template string, args ...interface{})

Infof uses fmt.Sprintf to log a templated message.

func (*SugaredLogger) InfowContext

func (s *SugaredLogger) InfowContext(
	ctx context.Context, msg string, keysAndValues ...interface{},
)

Infow logs a message with some additional context. The variadic key-value pairs are treated as they are in With.

func (*SugaredLogger) PanicfContext

func (s *SugaredLogger) PanicfContext(ctx context.Context, template string, args ...interface{})

Panicf uses fmt.Sprintf to log a templated message, then panics.

func (*SugaredLogger) PanicwContext

func (s *SugaredLogger) PanicwContext(
	ctx context.Context, msg string, keysAndValues ...interface{},
)

Panicw logs a message with some additional context, then panics. The variadic key-value pairs are treated as they are in With.

func (*SugaredLogger) WarnfContext

func (s *SugaredLogger) WarnfContext(ctx context.Context, template string, args ...interface{})

Warnf uses fmt.Sprintf to log a templated message.

func (*SugaredLogger) WarnwContext

func (s *SugaredLogger) WarnwContext(
	ctx context.Context, msg string, keysAndValues ...interface{},
)

Warnw logs a message with some additional context. The variadic key-value pairs are treated as they are in With.

func (*SugaredLogger) With

func (s *SugaredLogger) With(args ...interface{}) *SugaredLogger

With adds a variadic number of fields to the logging context. It accepts a mix of strongly-typed Field objects and loosely-typed key-value pairs. When processing pairs, the first element of the pair is used as the field key and the second as the field value.

For example,

 sugaredLogger.With(
   "hello", "world",
   "failure", errors.New("oh no"),
   Stack(),
   "count", 42,
   "user", User{Name: "alice"},
)

is the equivalent of

unsugared.With(
  String("hello", "world"),
  String("failure", "oh no"),
  Stack(),
  Int("count", 42),
  Object("user", User{Name: "alice"}),
)

Note that the keys in key-value pairs should be strings. In development, passing a non-string key panics. In production, the logger is more forgiving: a separate error is logged, but the key-value pair is skipped and execution continues. Passing an orphaned key triggers similar behavior: panics in development and errors in production.

type SugaredLoggerWithCtx

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

func (SugaredLoggerWithCtx) DPanicf

func (s SugaredLoggerWithCtx) DPanicf(template string, args ...interface{})

DPanicf uses fmt.Sprintf to log a templated message. In development, the logger then panics. (See DPanicLevel for details.)

func (SugaredLoggerWithCtx) DPanicw

func (s SugaredLoggerWithCtx) DPanicw(msg string, keysAndValues ...interface{})

DPanicw logs a message with some additional context. In development, the logger then panics. (See DPanicLevel for details.) The variadic key-value pairs are treated as they are in With.

func (SugaredLoggerWithCtx) Debugf

func (s SugaredLoggerWithCtx) Debugf(template string, args ...interface{})

Debugf uses fmt.Sprintf to log a templated message.

func (SugaredLoggerWithCtx) Debugw

func (s SugaredLoggerWithCtx) Debugw(msg string, keysAndValues ...interface{})

Debugw logs a message with some additional context. The variadic key-value pairs are treated as they are in With.

When debug-level logging is disabled, this is much faster than

s.With(keysAndValues).Debug(msg)

func (SugaredLoggerWithCtx) Desugar

func (s SugaredLoggerWithCtx) Desugar() *Logger

Desugar unwraps a SugaredLogger, exposing the original Logger. Desugaring is quite inexpensive, so it's reasonable for a single application to use both Loggers and SugaredLoggers, converting between them on the boundaries of performance-sensitive code.

func (SugaredLoggerWithCtx) Errorf

func (s SugaredLoggerWithCtx) Errorf(template string, args ...interface{})

Errorf uses fmt.Sprintf to log a templated message.

func (SugaredLoggerWithCtx) Errorw

func (s SugaredLoggerWithCtx) Errorw(msg string, keysAndValues ...interface{})

Errorw logs a message with some additional context. The variadic key-value pairs are treated as they are in With.

func (SugaredLoggerWithCtx) Fatalf

func (s SugaredLoggerWithCtx) Fatalf(template string, args ...interface{})

Fatalf uses fmt.Sprintf to log a templated message, then calls os.Exit.

func (SugaredLoggerWithCtx) Fatalw

func (s SugaredLoggerWithCtx) Fatalw(msg string, keysAndValues ...interface{})

Fatalw logs a message with some additional context, then calls os.Exit. The variadic key-value pairs are treated as they are in With.

func (SugaredLoggerWithCtx) Infof

func (s SugaredLoggerWithCtx) Infof(template string, args ...interface{})

Infof uses fmt.Sprintf to log a templated message.

func (SugaredLoggerWithCtx) Infow

func (s SugaredLoggerWithCtx) Infow(msg string, keysAndValues ...interface{})

Infow logs a message with some additional context. The variadic key-value pairs are treated as they are in With.

func (SugaredLoggerWithCtx) Panicf

func (s SugaredLoggerWithCtx) Panicf(template string, args ...interface{})

Panicf uses fmt.Sprintf to log a templated message, then panics.

func (SugaredLoggerWithCtx) Panicw

func (s SugaredLoggerWithCtx) Panicw(msg string, keysAndValues ...interface{})

Panicw logs a message with some additional context, then panics. The variadic key-value pairs are treated as they are in With.

func (SugaredLoggerWithCtx) Warnf

func (s SugaredLoggerWithCtx) Warnf(template string, args ...interface{})

Warnf uses fmt.Sprintf to log a templated message.

func (SugaredLoggerWithCtx) Warnw

func (s SugaredLoggerWithCtx) Warnw(msg string, keysAndValues ...interface{})

Warnw logs a message with some additional context. The variadic key-value pairs are treated as they are in With.