larry

README

larry

Larry is a minimal frontend for OpenTelemetry's Log SDK. This is inherently an unstable library because logs are only in Beta at the time of writing. This is intentionally a very thin wrapper for the Log SDK that just provides typical logging semantics. It has almost no features because the expectation is that any significant features would make more sense to implement via the OpenTelemetry Logs SDK instead of in this library. The only reason you should use this library (once logs go stable and this library is updated for those changes) instead of something like slog+slog bridge is if it bothers you on a personal level to log with slog only for it to be translated into OTel logs instead of using Otel types directly.

FAQ

Why isn't there a Fatal()?

Typically in Go, calling Fatal causes the process to exit via calling os.Exit(1), but doing this bypasses deferred functions, meaning that if one is using a non-synchronous LoggerProvider, the log message may not end up being flushed to the logging backend since, typically, the LoggerProvider is flushed in a deferred function. As a result, implementing this in the typical way might result in crashing the program without ever logging why it crashed, which defeats the point of having a Fatal log level. This leaves us with 3 options

1. Try to flush the LoggerProvider ourselves. We could check if the LoggerProvider has a ForceFlush method and use it if present, but given that this materially changes how Larry operates in a potentially unexpected fashion, we don't do it. If ForceFlush was part of the LoggerProvider interface, then we would probably take this option.
2. Don't crash the program. This is what the first version of this library did, but this is very counter-intuitive for Go veterans since it is generally expected that Fatal will crash the program, so this approach was abandoned.
3. Throw a panic. A panic doesn't prevent deferred functions from running and will (unless recovered) crash the program. This would still behave differently than typical Go Fatal calls do since os.Exit which cannot be recovered from is the typical choice.

As a result, the only options are to do something unexpected or to not do anything at all. Loggers should not be a source of unexpected behaviour, so we are left with doing nothing at all.

Future Improvements

• Remove the attribute.KeyValue -> log.KeyValue translation. This can be done once https://github.com/open-telemetry/opentelemetry-go/issues/7034 is completed and Record gets native support for KeyValue

Documentation

Index

• type Logger
  • func New(name string, opts ...Option) *Logger
  • func (o *Logger) Child(name string, opts ...Option) *Logger
  • func (o *Logger) Debug(ctx context.Context, msg string, attrs ...attribute.KeyValue)
  • func (o *Logger) Error(ctx context.Context, msg string, attrs ...attribute.KeyValue)
  • func (o *Logger) Info(ctx context.Context, msg string, attrs ...attribute.KeyValue)
  • func (o *Logger) Trace(ctx context.Context, msg string, attrs ...attribute.KeyValue)
  • func (o *Logger) Warn(ctx context.Context, msg string, attrs ...attribute.KeyValue)
  • func (o *Logger) With(attrs ...attribute.KeyValue) *Logger
• type Option
  • func WithAttributes(attrs ...attribute.KeyValue) Option
  • func WithLoggerOpts(opts ...log.LoggerOption) Option
  • func WithLoggerProvider(p log.LoggerProvider) Option

Types

type Logger

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

func New

func New(name string, opts ...Option) *Logger

func (*Logger) Child

func (o *Logger) Child(name string, opts ...Option) *Logger

Child creates a new logger that will share the attributes from the parent logger.

func (*Logger) Debug

func (o *Logger) Debug(ctx context.Context, msg string, attrs ...attribute.KeyValue)

func (*Logger) Error

func (o *Logger) Error(ctx context.Context, msg string, attrs ...attribute.KeyValue)

func (*Logger) Info

func (o *Logger) Info(ctx context.Context, msg string, attrs ...attribute.KeyValue)

func (*Logger) Trace

func (o *Logger) Trace(ctx context.Context, msg string, attrs ...attribute.KeyValue)

func (*Logger) Warn

func (o *Logger) Warn(ctx context.Context, msg string, attrs ...attribute.KeyValue)

func (*Logger) With

func (o *Logger) With(attrs ...attribute.KeyValue) *Logger

With returns a logger with the same configuration as this logger, but with additional attributes. It reuses the logger from the original logger. This should not be confused with Child(), which should be used to create a _new_ logger that inherits the parent's attributes.

type Option

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

func WithAttributes

func WithAttributes(attrs ...attribute.KeyValue) Option

func WithLoggerOpts

func WithLoggerOpts(opts ...log.LoggerOption) Option

func WithLoggerProvider

func WithLoggerProvider(p log.LoggerProvider) Option