trace

README

Trace v2

This guide will help you to setup and use the trace/v2 lib. We have a usage example in examples folder.

Configuring

This lib provides a Config struct and this section will explain how to properly configure.

Provider

1. stackdriver to export the trace to stackdriver
2. Empty string to not export the trace, but the trace will be created

Probability sample

1. 0 will not sample or export (if provider was set)
2. Float between 0 and 1 will use the number as a probability for sampling and export (if provider was set)
3. 1 will sample and export (if provider was set)

Stackdriver

Information to connect in stackdriver

Setting up and using the lib

Using in your config.go file

var config struct {
    // (...)

	Trace trace.Config
}

Creating a setup method

func setupTrace() {
	traceShutdown := trace.Setup(config.Trace)
	app.RegisterShutdownHandler(
		&app.ShutdownHandler{
			Name:     "opentelemetry_trace",
			Priority: app.ShutdownPriority(shutdownPriorityTrace),
			Handler:  traceShutdown,
			Policy:   app.ErrorPolicyAbort,
		})
}

Setting the trace up AFTER create a new App in main.go

func main() {
	app.SetupConfig(&config)

    // (...)

	if err := app.NewDefaultApp(ctx); err != nil {
		log.Ctx(ctx).Fatal().Err(err).Msg("Failed to create app")
	}

	setupTrace()

    // (...)
}

Starting a span

ctx, span := trace.Start(ctx, "SPAN-NAME")
defer span.End()

Recovering trace informations and logging it

type TraceInfo struct {
	ID        string
	IsSampled bool
}

t := trace.GetTraceInfoFromContext(ctx)
log.Ctx(ctx).Info().EmbedObject(t).Msg("Hello")

Propagating the trace

API

Using in transport layer

func MakeHTTPHandler(e endpoint.Endpoint) http.Handler {
    // (...)

	r := mux.NewRouter()
	r.Use(trace.MuxHTTPMiddleware("SERVER-NAME"))

    //(...)
	return r
}

Using in a HTTP request

request, err := http.NewRequestWithContext(
    ctx,
    "POST",
    url,
    bytes.NewReader(body),
)
if err != nil {
    return "", errors.E(op, err)
}

trace.SetTraceInRequest(request)

Using in a HTTP response

func encodeResponse(
	ctx context.Context,
	w http.ResponseWriter,
	r interface{},
) error {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	trace.SetTraceInResponse(ctx, w)
	return json.NewEncoder(w).Encode(r)
}

Workers

[WIP]

Documentation

Index

• func MuxHTTPMiddleware(service string) mux.MiddlewareFunc
• func SetTraceInRequest(r *http.Request)
• func SetTraceInResponse(ctx context.Context, r http.ResponseWriter)
• func Setup(c Config) app.ShutdownFunc
• type Config
• type OTLPConfig
  • func (c *OTLPConfig) Options() []otlptracehttp.Option
• type Span
  • func Start(ctx context.Context, name string) (context.Context, Span)
  • func (s Span) End()
• type StackdriverConfig
• type TraceInfo
  • func GetTraceInfoFromContext(ctx context.Context) TraceInfo
  • func (t TraceInfo) MarshalZerologObject(e *zerolog.Event)

Functions

func MuxHTTPMiddleware

func MuxHTTPMiddleware(service string) mux.MiddlewareFunc

MuxHTTPMiddleware sets up a handler to start tracing the incoming requests. The service parameter should describe the name of the (virtual) server handling the request.

func SetTraceInRequest

func SetTraceInRequest(r *http.Request)

SetTraceInRequest will put the trace in @r headers

func SetTraceInResponse

func SetTraceInResponse(ctx context.Context, r http.ResponseWriter)

SetTraceInResponse will put the trace in @r headers

func Setup

func Setup(c Config) app.ShutdownFunc

Setup use Config to setup an trace exporter and returns a shutdown handler

Types

type Config

type Config struct {
	Exporter          string  `default:""`
	ProbabilitySample float64 `default:"0"`
	Stackdriver       StackdriverConfig
	OTLP              OTLPConfig
}

Config represents all trace's configuration

type OTLPConfig

type OTLPConfig struct {
	// Endpoint allows one to set the address of the collector
	// endpoint that the driver will use to send spans.
	// It is a string in the form <host>:<port>.
	// If unset, it will instead try to use the default endpoint
	// from package otlptracehttp (at the time of this writing
	// the default is localhost:4318).
	// Note that the endpoint must not contain any URL path.
	Endpoint string
	// Compression tells the driver to compress the sent data.
	// Possible values are:
	// - "" (empty string) or "none": No compression
	// - "gzip": GZIP compression.
	Compression string
	// Insecure tells the driver to connect to the collector using the
	// HTTP scheme, instead of HTTPS.
	Insecure bool
}

OTLPConfig allows for configuring the OpenTelemery Protocol.

func (*OTLPConfig) Options

func (c *OTLPConfig) Options() []otlptracehttp.Option

type Span

type Span struct {
	// contains filtered or unexported fields
}

Span is the individual component of a trace. It represents a single named and timed operation of a workflow that is traced

func Start

func Start(ctx context.Context, name string) (context.Context, Span)

Start creates a new span. If other spans were created using @ctx, this method will bind them all

func (Span) End

func (s Span) End()

End stops an span sampling

type StackdriverConfig

type StackdriverConfig struct {
	ProjectID string
}

StackdriverConfig contains all the configuration of the Starkdriver exporter.

type TraceInfo

type TraceInfo struct {
	ID        string
	IsSampled bool
}

TraceInfo carries the trace informations

func GetTraceInfoFromContext

func GetTraceInfoFromContext(ctx context.Context) TraceInfo

GetTraceInfoFromContext returns a TraceInfo from the context @ctx or logs if there is no TraceInfo in context

func (TraceInfo) MarshalZerologObject

func (t TraceInfo) MarshalZerologObject(e *zerolog.Event)

MarshalZerologObject implements the zerolog marshaler so it can be logged using: log.With().EmbededObject(t).Msg("Some message")