README

Trace

trace is a wrapper for the net/trace package that adds logging and metrics to de-clutter your functions.

trace wraps all of the functionality of net/trace, but also replicates the logs to a structured logger built on Go's standard logging library.

Metrics are exported to Prometheus with trace duration histograms by name/family, trace counts by name/family, and errors by trace name/family.

the net/trace#EventLog is also implemented in the same manner, minus metrics exposition, which doesn't make sense there.

examples/gogrep has an example command-line application that shows usage of the trace functionality to both capture trace information and logs with a single tool.

examples/service has an example web application that shows usage of the trace functionality to both capture trace information and logs with a single tool, combined with the trace.EventLog which serves as a single logging and event source for your application.

Log Output - trace

2016/10/03 00:27:34 message=found file=../../events.go trace=main
2016/10/03 00:27:34 message=found file=../../examples/gogrep/main.go trace=main
2016/10/03 00:27:34 message=found file=../../log.go trace=main
2016/10/03 00:27:34 message=found file=../../trace.go trace=main
2016/10/03 00:27:34 message=found file=../../metrics.go trace=main
2016/10/03 00:27:34 trace=main : hit count 5
2016/10/03 00:27:34 message=finished hits=5 trace=main

Log Output - EventLog

2016/10/03 00:34:05 name=http - Listening on :3000

Metrics Output

trace offers two useful and one fun way to expose your metrics.

trace.ServeMetrics() will serve the metrics in Prometheus text format. Use this for long-running apps/services.

trace.PushMetrics() will push the metrics to a Prometheus push server. Use this for command-line utilities.

trace.DumpMetrics() will return a string with the metrics that Prometheus would serve, suitable for inspection, printing, tests.

/debug endpoints

trace exposes the underlying net/trace /debug/requests and /debug/events endpoints for handy visual representation of the traces, their timing/histograms, and the event log of your application.

Documentation

Overview

Package trace is a wrapper for [the net/trace package](https://github.com/golang/net/tree/master/trace) that adds logging and metrics to de-clutter your functions.

`trace` wraps all of the functionality of net/trace, but also replicates the logs to a structured logger built on Go's standard logging library.

Metrics are exported to Prometheus of trace durations by name/family, trace counts by name/family, and errors by trace name/family.

the net/trace#EventLog is also implemented in the same manner, minus metrics exposition, which doesn't make sense there.

examples/gogrep has an example command-line application that shows usage of the `trace` functionality to both capture trace information and logs with a single tool.

examples/service has an example web application that shows usage of the `trace` functionality to both capture trace information and logs with a single tool, combined with the `trace.EventLog` which serves as a single logging and event source for your application.

Index

• Variables
• func DumpMetrics(ctx context.Context, task string) (string, error)
• func KeyValue(key string, val interface{}) keyval
• func LogMessage(message string, keyvals ...keyval) *logmessage
• func New(family, title string) xtr.Trace
• func NewContext(ctx context.Context, family, title string) (xtr.Trace, context.Context)
• func NewEventLog(family, title string) xtr.EventLog
• func PushMetrics(ctx context.Context, task string, gatewayURL string)
• func ServeMetrics(ctx context.Context, l net.Listener) error
• func SetAuthRequest(f func(req *http.Request) (any, sensitive bool))
• func SetLogger(out io.Writer, prefix string, flag int)
• func TitleFromContext(ctx context.Context) string
• type EventLog
  • func (e *EventLog) Errorf(format string, a ...interface{})
  • func (e *EventLog) Finish()
  • func (e *EventLog) Printf(format string, a ...interface{})

Constants

This section is empty.

Variables

var Log = stdlog.New(os.Stderr, "", stdlog.LstdFlags)

Log is the logger used by all trace package functions

var Namespace string

Namespace is used to differentiate metrics - and specifically used in prometheus reporting. It may safely be left blank.

var Subsystem string

Subsystem is used to differentiate metrics - and specifically used in prometheus reporting. It may safely be left blank.

var TraceIDKey = ctxKey(1)

TraceIDKey is the context key used to get the Trace's title out of a context if it exists

Functions

func DumpMetrics

func DumpMetrics(ctx context.Context, task string) (string, error)

DumpMetrics returns the metrics prometheus would return when collected as a string, for fun and testing

func KeyValue

func KeyValue(key string, val interface{}) keyval

KeyValue creates a Key/Value pair that is suitable for use in the LogMessage() function

func LogMessage

func LogMessage(message string, keyvals ...keyval) *logmessage

LogMessage creates a message that complies with fmt.Stringer but also includes a message and key/value pairs for structured logging. Use it in trace.LazyLog:

t.LazyLog(trace.LogMessage("found", trace.KeyValue("file", name)), false)

func New

func New(family, title string) xtr.Trace

New returns a new Trace with the specified family and title.

func NewContext

func NewContext(ctx context.Context, family, title string) (xtr.Trace, context.Context)

NewContext returns a new context.Context and Trace with the given family and title. The trace will be stored in the context.

func NewEventLog

func NewEventLog(family, title string) xtr.EventLog

NewEventLog returns an initialized EventLog with the given family and title.

func PushMetrics

func PushMetrics(ctx context.Context, task string, gatewayURL string)

PushMetrics sends the metrics collected to the prometheus push gateway at the url in `gatewayURL` with the job name of `task` Should be called in a defer in main() of a cli application. For long-running services, use ServeMetrics instead

func ServeMetrics

func ServeMetrics(ctx context.Context, l net.Listener) error

ServeMetrics serves Prometheus metrics endpoint on the provided net.Listener Use for long-running services. For cli tools, use PushMetrics instead.

func SetAuthRequest

func SetAuthRequest(f func(req *http.Request) (any, sensitive bool))

SetAuthRequest sets the AuthRequest function for the underlying trace HTTP listener, which determines whether a specific request is permitted to load the /debug/requests or /debug/events pages.

func SetLogger

func SetLogger(out io.Writer, prefix string, flag int)

SetLogger replaces the default logger with a new one that writes to 'out', has 'prefix', and flags 'flag'

func TitleFromContext

func TitleFromContext(ctx context.Context) string

TitleFromContext is a convenience function that returns the Trace's title from a context or an empty string if none exists

Types

type EventLog

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

An EventLog provides a log of events associated with a specific object.

func (*EventLog) Errorf

func (e *EventLog) Errorf(format string, a ...interface{})

Errorf is like Printf, but it marks this event as an error.

func (*EventLog) Finish

func (e *EventLog) Finish()

Finish declares that this event log is complete. The event log should not be used after calling this method.

func (*EventLog) Printf

func (e *EventLog) Printf(format string, a ...interface{})

Printf formats its arguments with fmt.Sprintf and adds the result to the event log.