reqtrace

README

reqtrace is a package for simple request tracing. It requires nothing of its user except:

• They must use golang.org/x/net/context.
• They must add a single line to each function they want to be visible in traces.

In particular, reqtrace is console-based and doesn't require an HTTP server.

Warning: This package is still barebones and in its early days. I reserve the right to make backwards-incompatible changes to its API. But if it's useful to you in your current form, have at it.

Use

Call reqtrace.Trace anywhere you want to start a new root trace. (This is probably where you create your root context.) This returns a new context that you should pass to child operations, and a reporting function that you must use to inform reqtrace when the trace is complete.

For example:

func HandleRequest(r *someRequest) (err error) {
  ctx, report := reqtrace.Trace(context.Background(), "HandleRequest")
  defer func() { report(err) }()

  // Do two things for this request.
  DoSomething(ctx, r)
  DoSomethingElse(ctx, r)
}

Within other functions that you want to show up in the trace, you reqtrace.StartSpan (or its more convenient sibling reqtrace.StartSpanWithError):

func DoSomething(ctx context.Context, r *someRequest) (err error) {
  defer reqtrace.StartSpanWithError(&ctx, &err, "DoSomething")()

  // Process the request somehow using ctx. If downstream code also annotes
  // using reqtrace, reqtrace will know that its spans are descendants of
  // this one.
  CallAnotherLibrary(ctx, r.Param)
}

When --reqtrace.enable is set, the completion of a trace will cause helpful ASCII art to be spit out.

Documentation

Overview

Package reqtrace contains a very simple request tracing framework.

Index

• func Enabled() (enabled bool)
• func StartSpanWithError(ctx *context.Context, err *error, desc string) (f func())
• type ReportFunc
  • func StartSpan(parent context.Context, desc string) (ctx context.Context, report ReportFunc)
  • func Trace(parent context.Context, desc string) (ctx context.Context, report ReportFunc)

Functions

func Enabled

func Enabled() (enabled bool)

Return false only if traces are disabled, i.e. Trace will never cause a trace to be initiated.

REQUIRES: flag.Parsed()

func StartSpanWithError

func StartSpanWithError(
	ctx *context.Context,
	err *error,
	desc string) (f func())

A wrapper around StartSpan that can be more convenient to use when the lifetime of a span matches the lifetime of a function. Intended to be used in a defer statement within a function using a named error return parameter.

Equivalent to calling StartSpan with *ctx, replacing *ctx with the resulting new context, then setting f to a function that will invoke the report function with the contents of *error at the time that it is called.

Example:

func DoSomething(ctx context.Context) (err error) {
  defer reqtrace.StartSpanWithError(&ctx, &err, "DoSomething")()
  [...]
}

Types

type ReportFunc

type ReportFunc func(error)

A function that must be called exactly once to report the outcome of an operation represented by a span.

func StartSpan

func StartSpan(
	parent context.Context,
	desc string) (ctx context.Context, report ReportFunc)

Begin a span within the current trace. Return a new context that should be used for operations that logically occur within the span, and a report function that must be called with the outcome of the logical operation represented by the span.

If no trace is active, no span will be created but ctx and report will still be valid.

func Trace

func Trace(
	parent context.Context,
	desc string) (ctx context.Context, report ReportFunc)

Like StartSpan, but begins a root span for a new trace if no trace is active in the supplied context and tracing is enabled for the process.