otlpr

README

otlpr

This repository provides a logr.Logger that exports recorded messages as OpenTelemetry logs to an OTLP receiving endpoint.

🚧 This repository is a work in progress and not production ready.

Getting Started

A working gRPC connection to an OTLP receiving endpoint is needed to setup the logger.

conn, _ := grpc.NewClient(otlpTarget)

Create a logr.Logger with this connection.

logger := otlpr.New(conn)

See the example for a working example application.

Batching

By default the logger will batch the log messages as they are received. It will wait to batch 2048 messages before exporting.

A Batcher can be used to change this behavior.

opts := otlpr.Options{
	Batcher: otlpr.Batcher{
		// Only queue at most 100 messages.
		Messages: 100,
		// Only wait 3 seconds for the queue to fill.
		Timeout: 3 * time.Second,
	},
}
logger := otlpr.NewWithOptions(conn, opts)

Max messages in export

The Batcher can be configured to limit the number of messages it sends for each export with the ExportN setting.

opts := otlpr.Options{
	Batcher: otlpr.Batcher{
		// Only send at most 100 messages per export.
		ExportN: 100,
	},
}
logger := otlpr.NewWithOptions(conn, opts)

Annotating Span Context

OTLP is able to associate span context with log messages. Use the WithContext function to associate a context.Context that contains an active span with all logs the logger creates.

logger = otlpr.WithContext(logger, ctx)

The function can also be used to clear any span context from the logger.

logger = otlpr.WithContext(logger, context.Background())

Adding a Resource

The system a log message is produced in can be described with a Resource. Use the WithResource function to include this information with the exported OTLP data.

logger = otlpr.WithResource(logger, resource)

The function can also be used to clear any resource from the logger.

logger = otlpr.WithResource(logger, nil)

Adding Scope

The portion of a system a log message is produced in can be described with Scope. Use the WithScope function to include this information with the exported OTLP data.

logger = otlpr.WithScope(logger, resource)

The function can also be used to clear any scope from the logger.

logger = otlpr.WithScope(logger, instrumentation.Scope{})

Documentation

Overview

Package otlpr provides a github.com/go-logr/logr.Logger implementation that exports log records in the OpenTelemetry OTLP log format.

Index

• func New(conn *grpc.ClientConn) logr.Logger
• func NewWithOptions(conn *grpc.ClientConn, opts Options) logr.Logger
• func WithContext(l logr.Logger, ctx context.Context) logr.Logger
• func WithResource(l logr.Logger, res *resource.Resource) logr.Logger
• func WithScope(l logr.Logger, scope instrumentation.Scope) logr.Logger
• type Batcher
• type MessageClass
• type Options

Functions

func New

func New(conn *grpc.ClientConn) logr.Logger

New returns a new logr Logger that will export logs over conn using OTLP. The conn is expected to be ready to use when passed. If conn is nil a discard logger is returned.

func NewWithOptions

func NewWithOptions(conn *grpc.ClientConn, opts Options) logr.Logger

NewWithOptions returns a new logr Logger that will export logs over conn using OTLP. See New for details.

func WithContext

func WithContext(l logr.Logger, ctx context.Context) logr.Logger

WithContext returns an updated logger that will log information about any span in ctx if one exists with each log message. It does nothing for loggers where the sink doesn't support a context.

func WithResource

func WithResource(l logr.Logger, res *resource.Resource) logr.Logger

WithResource returns an updated logger that export log information with the provided resource. It does nothing for loggers where the sink doesn't support a resource.

func WithScope

func WithScope(l logr.Logger, scope instrumentation.Scope) logr.Logger

WithScope returns an updated logger that export log information with the provided instrumentation scope. It does nothing for loggers where the sink doesn't support a resource.

Types

type Batcher

type Batcher struct {
	// Messages is the maximum number of messages to queue. Once this many
	// messages have been queued the Batcher will export the queue.
	//
	// If Messages is zero, the default value of 2048 is used.
	Messages uint64
	// Timeout is the maximum time to wait for a full queue. Once this much
	// time has elapsed since the last export or start the Batcher will export
	// the queue.
	//
	// If Timeout is less than or equal to zero the Batcher will never export
	// based on queue staleness.
	Timeout time.Duration
	// ExportN is the maximum number of messages included in an export.
	//
	// For values less than or equal to zero the Batcher will export the whole
	// queue in a single export.
	ExportN int
}

type MessageClass

type MessageClass int

MessageClass indicates which category or categories of messages to consider.

const (
	// None ignores all message classes.
	None MessageClass = iota
	// All considers all message classes.
	All
	// Info only considers info messages.
	Info
	// Error only considers error messages.
	Error
)

type Options

type Options struct {
	// Depth biases the assumed number of call frames to the "true" caller.
	// This is useful when the calling code calls a function which then calls
	// stdr (e.g. a logging shim to another API).  Values less than zero will
	// be treated as zero.
	Depth int

	// LogCaller tells otlpr to add a "caller" key to some or all log lines.
	LogCaller MessageClass

	// LogCallerFunc tells otlpr to also log the calling function name. This
	// has no effect if caller logging is not enabled (see Options.LogCaller).
	LogCallerFunc bool

	// Batcher tells otlpr to batch log messages with the provided Batcher
	// configuration.
	Batcher Batcher
}

Options carries parameters which influence the way logs are generated.