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

Expand ▾ Collapse ▴

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

    Constants

    This section is empty.

    Variables

      Log is the logger used by all trace package functions

      View Source
      var Namespace string

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

        View Source
        var Subsystem string

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

          View Source
          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.

                                          Directories

                                          Path Synopsis
                                          examples
                                          service
                                          Adapted from http://www.alexedwards.net/blog/a-recap-of-request-handling
                                          Adapted from http://www.alexedwards.net/blog/a-recap-of-request-handling