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
Constants ¶
This section is empty.
Variables ¶
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 ¶
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 NewContext ¶
NewContext returns a new context.Context and Trace with the given family and title. The trace will be stored in the context.
func NewEventLog ¶
NewEventLog returns an initialized EventLog with the given family and title.
func PushMetrics ¶
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 ¶
ServeMetrics serves Prometheus metrics endpoint on the provided net.Listener Use for long-running services. For cli tools, use PushMetrics instead.
func SetAuthRequest ¶
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 ¶
SetLogger replaces the default logger with a new one that writes to 'out', has 'prefix', and flags 'flag'
func TitleFromContext ¶
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.
Source Files
Directories