tracer

Documentation

Overview

Package tracer starts an opencensus span with a logger automatically signed with the current calling function.

An additional method is provided to explicitly sign anonymous functions.

Index

• func Middleware(opts ...MiddlewareOption) func(http.Handler) http.Handler
• func RegisterPrefix(custom string)
• func StartNamedSpan(ctx context.Context, rt Loggable, signature string, fields ...zap.Field) (context.Context, *trace.Span, log.Logger)
• func StartSpan(ctx context.Context, rt Loggable, fields ...zap.Field) (context.Context, *trace.Span, log.Logger)
• type Loggable
• type MiddlewareOption
  • func IsHealthEndpoint(filter func(*http.Request) bool) MiddlewareOption
  • func IsPublicEndpoint(enabled bool) MiddlewareOption
  • func WithFormat(format propagation.HTTPFormat) MiddlewareOption
  • func WithFormatSpanName(fn func(*http.Request) string) MiddlewareOption
  • func WithGetStartOptions(fn func(*http.Request) trace.StartOptions) MiddlewareOption
  • func WithRoute(route string) MiddlewareOption
  • func WithStartOptions(opts ...trace.StartOption) MiddlewareOption

Examples

• StartNamedSpan
• StartSpan

Functions

func Middleware

func Middleware(opts ...MiddlewareOption) func(http.Handler) http.Handler

Middleware that wraps go.opencensus.io/plugin/ochttp for a more idiomatic usage.

Options available to ochtpp.Handler are exposed here as Options.

func RegisterPrefix

func RegisterPrefix(custom string)

RegisterPrefix sets a package level prefix at initialization time.

The default value is "function".

func StartNamedSpan

func StartNamedSpan(ctx context.Context, rt Loggable, signature string, fields ...zap.Field) (context.Context, *trace.Span, log.Logger)

StartNamedSpan is used inside anonymous functions. The caller may specify a signature.

Example

package main

import (
	"context"

	"github.com/fredbi/go-trace/log"
	"github.com/fredbi/go-trace/tracer"
	"go.uber.org/zap"
)

type Runtime struct {
	logger log.Factory
}

func (r Runtime) Logger() log.Factory {
	return r.logger
}

func main() {
	lg, _ := zap.NewDevelopment()
	rt := Runtime{logger: log.NewFactory(lg)}
	ctx := context.Background()

	// StartNamedSpan should be used in anonymous functions like so.
	handleFunc := func() {
		_, span, logger := tracer.StartNamedSpan(ctx, rt, "signature", zap.String("field", "fred"))
		defer span.End()

		logger.Info("test")
	}

	handleFunc()
}

func StartSpan

func StartSpan(ctx context.Context, rt Loggable, fields ...zap.Field) (context.Context, *trace.Span, log.Logger)

StartSpan returns an opencensus span and logger that prepends the caller's signature.

This spares us the boiler plate of repeatedly adding the prefix and function signatures in trace spans and logger.

Example

package main

import (
	"context"

	"github.com/fredbi/go-trace/log"
	"github.com/fredbi/go-trace/tracer"
	"go.uber.org/zap"
)

type Runtime struct {
	logger log.Factory
}

func (r Runtime) Logger() log.Factory {
	return r.logger
}

func main() {
	lg, _ := zap.NewProduction()
	rt := Runtime{logger: log.NewFactory(lg)}
	ctx := context.Background()

	// Instantiate a span and its associated span logger.
	//
	// This span is automatically signed with the current function, annotated with the source file and line
	_, span, logger := tracer.StartSpan(ctx, rt, zap.String("field", "fred"))
	defer span.End()

	logger.Info("test")

	// Should get something like:
	// 2023-11-01T17:19:58.615+0100	INFO	log/logger.go:35	test	{
	//	"function": "tracer.TestStartSpan",
	//	"source_file": ".../github.com/fredbi/go-trace/tracer/tracer_test.go",
	//	"source_line": 28,
	//	"field": "fred"
	//	}
}

Types

type Loggable

type Loggable interface {
	Logger() log.Factory
}

Loggable is a log factory provider

type MiddlewareOption

type MiddlewareOption func(*middlewareOptions)

func IsHealthEndpoint

func IsHealthEndpoint(filter func(*http.Request) bool) MiddlewareOption

IsHealthEndpoint instructs the tracer to skip tracing when the function returns true. a linked trace rather than a parent (for publicly accessible servers).

By default, paths like /healthz or /_ah/health are filtered out from tracing.

func IsPublicEndpoint

func IsPublicEndpoint(enabled bool) MiddlewareOption

IsPublicEndpoint instructs the tracer to consider incoming trace metadata as a linked trace rather than a parent (for publicly accessible servers).

func WithFormat

func WithFormat(format propagation.HTTPFormat) MiddlewareOption

WithFormat overrides the trace propagation format (default is B3).

func WithFormatSpanName

func WithFormatSpanName(fn func(*http.Request) string) MiddlewareOption

WithFormatSpanName injects a function to determine the span name according to the request.

func WithGetStartOptions

func WithGetStartOptions(fn func(*http.Request) trace.StartOptions) MiddlewareOption

WithGetStartOptions enables trace start options such a overriding the span kind or adding a sampler, on a per request basis.

func WithRoute

func WithRoute(route string) MiddlewareOption

WithRoute decorates the trace with an extra route tag

func WithStartOptions

func WithStartOptions(opts ...trace.StartOption) MiddlewareOption

WithStartOptions enables trace start options such a overriding the span kind or adding a sampler. See go.opencensus.io/trace.StartOptions.