Categorygithub.com/bketelsen/trace
modulepackage
0.0.0-20210910121725-d5539ae96423
Repository: https://github.com/bketelsen/trace.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
19
Dependents
2
Files
364 SLOC

# README

Trace

Go Report Card

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.

Requests Events

# Packages

No description provided by the author

# Functions

DumpMetrics returns the metrics prometheus would return when collected as a string, for fun and testing.
KeyValue creates a Key/Value pair that is suitable for use in the LogMessage() function.
LogMessage creates a message that complies with fmt.Stringer but also includes a message and key/value pairs for structured logging.
New returns a new Trace with the specified family and title.
NewContext returns a new context.Context and Trace with the given family and title.
NewEventLog returns an initialized EventLog with the given family and title.
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.
ServeMetrics serves Prometheus metrics endpoint on the provided net.Listener Use for long-running services.
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.
SetLogger replaces the default logger with a new one that writes to 'out', has 'prefix', and flags 'flag'.
TitleFromContext is a convenience function that returns the Trace's title from a context or an empty string if none exists.

# Variables

Log is the logger used by all trace package functions.
Namespace is used to differentiate metrics - and specifically used in prometheus reporting.
Subsystem is used to differentiate metrics - and specifically used in prometheus reporting.
TraceIDKey is the context key used to get the Trace's title out of a context if it exists.

# Structs

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