log

Documentation

Overview

Package log is a replacement for the standard library log package that logs to OTEL spans contained in Context objects. These are seen as events with the attribute "log" set to true.

The preferred way to log is to use an event:

func someFunc(ctx context.Context) {
	e := NewEvent("someFunc()")
	defer e.Done(ctx)
	start := time.Now()
	defer func() {
		e.Add("latency.ns", int(time.Since(start)))
	}()
}

This records an event in the current span that has a key of "latency.ns" with the value in nano-seconds the operation took.

You can use this to log in a similar manner to the logging package with Println and Printf. This is generally only useful for some generic debugging where you want to log something and filter the trace by messages with key "log". Generally these are messages you don't want to keep.

func main() {
	ctx := context.Background()

	log.SetFlags(log.LstdFlags | log.Lshortfile)

	log.Println(ctx, "Starting main")

	log.Printf(ctx, "Env variables: %v", os.Environ())
}

The above won't log anything, as there is no Span on the Context. If there was it would get output to the Open Telementry provider.

If you need to use the standard library log, you can use Logger:

log.Logger.Println("hello world")

This would print whever the stanard logger prints to. This defaults to the standard logger, but you can replace with another Logger if you wish.

You should only log messages with a standard logger when it can't be output to a trace. These are critical messages that indicate a definite bug. This keeps logging to only critical events and de-clutters what you need to look at to when doing a debug.

Index

• Constants
• Variables
• func Printf(ctx context.Context, format string, v ...interface{})
• func Println(ctx context.Context, v ...interface{})
• func SetFlags(flag int)
• type Event
  • func NewEvent(name string) *Event
  • func (e *Event) Add(k string, i interface{})
  • func (e *Event) Done(ctx context.Context)

Constants

const (
	Ldate         = 1 << iota     // the date in the local time zone: 2009/01/23
	Ltime                         // the time in the local time zone: 01:23:23
	Lmicroseconds                 // microsecond resolution: 01:23:23.123123.  assumes Ltime.
	Llongfile                     // full file name and line number: /a/b/c/d.go:23
	Lshortfile                    // final file name element and line number: d.go:23. overrides Llongfile
	LUTC                          // if Ldate or Ltime is set, use UTC rather than the local time zone
	LstdFlags     = Ldate | Ltime // initial values for the standard logger
)

Variables

var Logger *log.Logger = log.Default()

Logger provides access to the standard library's default logger. This can be replaced in main with a logger of your choice.

Functions

func Printf

func Printf(ctx context.Context, format string, v ...interface{})

Printf acts like log.Printf() except we log to the OTEL span in the Context.

func Println

func Println(ctx context.Context, v ...interface{})

Println acts like log.Println() except we log to the OTEL span in the Context.

func SetFlags

func SetFlags(flag int)

SetFlags sets the output flags for the standard logger.

Types

type Event

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

Event represents a named event that occurs. This is the prefered way to log data. Events have attributes and those attributes are key/value pairs. You create an event and stuff attributes using Add() until the event is over and call Done(). This will render the event to the current span. if no attrs exist, the event is ignored. To avoid extra allocations

func NewEvent

func NewEvent(name string) *Event

NewEvent returns a new Event.

func (*Event) Add

func (e *Event) Add(k string, i interface{})

Add adds an attribute named k with value i. i can be: bool, []bool, float64, []float64, int, []int, int64, []int64, string and []string. If the value isn't one of those values, a standard log message is printed indicating a bug.

func (*Event) Done

func (e *Event) Done(ctx context.Context)

Done renders the Event to the span in the Context. If there are no attributes on the Event, this is a no-oop. Once Done is called, the Event object MUST not be used again.