tracing

README

Tracing

Tracing is a go.opentelemetry.io Tracer wrapper for instrumenting golang applications to collect traces in jaeger.

Install

go get github.com/loghole/tracing

Usage

package main

import (
	"context"
	"time"

	"github.com/loghole/tracing"
)

func main() {
	tracer, err := tracing.NewTracer(tracing.DefaultConfiguration("example", "udp://127.0.0.1:6831"))
	if err != nil {
		panic(err)
	}

	defer tracer.Close()

	ctx, span := tracer.NewSpan().WithName("root").StartWithContext(context.Background())
	defer span.End()

	next(ctx)
}

func next(ctx context.Context) {
	defer tracing.ChildSpan(&ctx).End()

	// Some work...
	time.Sleep(time.Second)
}

Examples

• HTTP Client
• HTTP Server
• Simple

Documentation

Overview

Package tracing implements tracing part of the OpenTelemetry API.

Index

• Variables
• func ContextWithoutCancel(parent context.Context) context.Context
• func EnablePrometheusMetrics() error
• func InjectHeaders(ctx context.Context, carrier http.Header)
• func InjectMap(ctx context.Context, carrier map[string]string)
• func SpanContextFromContext(ctx context.Context) trace.SpanContext
• func SpanFromContext(ctx context.Context) trace.Span
• type Configuration
  • func DefaultConfiguration(service, addr string) *Configuration
• type Span
  • func ChildSpan(ctx *context.Context) (s *Span)
  • func (s *Span) AddEvent(name string, options ...trace.EventOption)
  • func (s *Span) End(options ...trace.SpanEndOption)
  • func (s *Span) Finish()
  • func (s *Span) IsRecording() bool
  • func (s *Span) RecordError(err error, options ...trace.EventOption)
  • func (s *Span) SetAttributes(kv ...attribute.KeyValue)
  • func (s *Span) SetName(name string)
  • func (s *Span) SetStatus(code codes.Code, description string)
  • func (s *Span) SetTag(key string, value interface{}) *Span
  • func (s *Span) SpanContext() trace.SpanContext
  • func (s *Span) TracerProvider() trace.TracerProvider
• type SpanBuilder
  • func (b SpanBuilder) ExtractHeaders(carrier http.Header) SpanBuilder
  • func (b SpanBuilder) ExtractMap(carrier map[string]string) SpanBuilder
  • func (b SpanBuilder) Start(ctx context.Context) *Span
  • func (b SpanBuilder) StartWithContext(ctx context.Context) (context.Context, *Span)
  • func (b SpanBuilder) WithName(name string) SpanBuilder
• type Tracer
  • func NewNoopTracer() *Tracer
  • func NewTracer(configuration *Configuration) (*Tracer, error)
  • func (t *Tracer) Close() error
  • func (t *Tracer) NewSpan() SpanBuilder
  • func (t *Tracer) Start(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)

Variables

var ErrInvalidConfiguration = errors.New("invalid configuration")

Functions

func ContextWithoutCancel

func ContextWithoutCancel(parent context.Context) context.Context

ContextWithoutCancel returns a context that is never canceled.

func EnablePrometheusMetrics

func EnablePrometheusMetrics() error

func InjectHeaders

func InjectHeaders(ctx context.Context, carrier http.Header)

InjectHeaders set tracecontext from the Context into the http.Header carrier.

func InjectMap

func InjectMap(ctx context.Context, carrier map[string]string)

InjectMap set tracecontext from the Context into the map[string]string carrier.

func SpanContextFromContext

func SpanContextFromContext(ctx context.Context) trace.SpanContext

SpanContextFromContext returns the current Span's SpanContext.

func SpanFromContext

func SpanFromContext(ctx context.Context) trace.Span

SpanFromContext returns the current Span from ctx. If no Span is currently set in ctx an implementation of a Span that performs no operations is returned.

Types

type Configuration

type Configuration struct {
	ServiceName string
	Addr        string
	Disabled    bool

	Sampler              tracesdk.Sampler
	Attributes           []attribute.KeyValue
	SpanProcessorOptions []tracesdk.BatchSpanProcessorOption
}

Configuration configures Tracer.

func DefaultConfiguration

func DefaultConfiguration(service, addr string) *Configuration

DefaultConfiguration returns base configuration with default params.

type Span

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

Span is wrapper for `trace.Span` interface.

func ChildSpan

func ChildSpan(ctx *context.Context) (s *Span)

ChildSpan starts new span and replace original context.

Example:

func example(ctx context.Context) {
    defer tracing.ChildSpan(&ctx).End()

    time.Sleep(time.Second)
}

func (*Span) AddEvent

func (s *Span) AddEvent(name string, options ...trace.EventOption)

AddEvent adds an event with the provided name and options.

func (*Span) End

func (s *Span) End(options ...trace.SpanEndOption)

End completes the Span. The Span is considered complete and ready to be delivered through the rest of the telemetry pipeline after this method is called. Therefore, updates to the Span are not allowed after this method has been called.

func (*Span) Finish

func (s *Span) Finish()

Finish is alias of End function.

func (*Span) IsRecording

func (s *Span) IsRecording() bool

IsRecording returns the recording state of the Span. It will return true if the Span is active and events can be recorded.

func (*Span) RecordError

func (s *Span) RecordError(err error, options ...trace.EventOption)

RecordError will record err as an exception span event for this span. An additional call to SetStatus is required if the Status of the Span should be set to Error, as this method does not change the Span status. If this span is not being recorded or err is nil then this method does nothing.

func (*Span) SetAttributes

func (s *Span) SetAttributes(kv ...attribute.KeyValue)

SetAttributes sets kv as attributes of the Span. If a key from kv already exists for an attribute of the Span it will be overwritten with the value contained in kv.

func (*Span) SetName

func (s *Span) SetName(name string)

SetName sets the Span name.

func (*Span) SetStatus

func (s *Span) SetStatus(code codes.Code, description string)

SetStatus sets the status of the Span in the form of a code and a description, overriding previous values set. The description is only included in a status when the code is for an error.

func (*Span) SetTag

func (s *Span) SetTag(key string, value interface{}) *Span

func (*Span) SpanContext

func (s *Span) SpanContext() trace.SpanContext

SpanContext returns the SpanContext of the Span. The returned SpanContext is usable even after the End method has been called for the Span.

func (*Span) TracerProvider

func (s *Span) TracerProvider() trace.TracerProvider

TracerProvider returns a TracerProvider that can be used to generate additional Spans on the same telemetry pipeline as the current Span.

type SpanBuilder

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

SpanBuilder is a helper for creating a span through a chain of calls.

func (SpanBuilder) ExtractHeaders

func (b SpanBuilder) ExtractHeaders(carrier http.Header) SpanBuilder

ExtractHeaders reads tracecontext from the `http.Header` carrier and set remote SpanContext for new span.

func (SpanBuilder) ExtractMap

func (b SpanBuilder) ExtractMap(carrier map[string]string) SpanBuilder

ExtractMap reads tracecontext from the `map[string]string` carrier and set remote SpanContext for new span.

func (SpanBuilder) Start

func (b SpanBuilder) Start(ctx context.Context) *Span

Start creates a span.

func (SpanBuilder) StartWithContext

func (b SpanBuilder) StartWithContext(ctx context.Context) (context.Context, *Span)

StartWithContext creates a span and a context.Context containing the newly-created span.

func (SpanBuilder) WithName

func (b SpanBuilder) WithName(name string) SpanBuilder

WithName sets custom span name.

type Tracer

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

Tracer is the wrapper for `trace.Tracer` with span builder.

func NewNoopTracer

func NewNoopTracer() *Tracer

NewNoopTracer returns a Tracer that performs no operations. The Tracer and Spans created from the returned Tracer also perform no operations.

func NewTracer

func NewTracer(configuration *Configuration) (*Tracer, error)

NewTracer returns initialized Tracer with jaeger exporter.

Example:

func main() {
    tracer, err := tracing.NewTracer(DefaultConfiguration(
        "example-service",
        "udp://127.0.0.1:6831",
    ))
    if err != nil {
        log.Fatalf("init tracer: %v", err)
    }

    defer tracer.Close()

    _, span := tracer.NewSpan().WithName("example-span").StartWithContext(context.Background())
    defer span.End()

    time.Sleep(time.Second)
}

func (*Tracer) Close

func (t *Tracer) Close() error

Close shuts down the span processors in the order they were registered.

func (*Tracer) NewSpan

func (t *Tracer) NewSpan() SpanBuilder

NewSpan creates a SpanBuilder.

func (*Tracer) Start

func (t *Tracer) Start(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)

Start creates a span and a context.Context containing the newly-created span.

If the context.Context provided in `ctx` contains a Span then the newly-created Span will be a child of that span, otherwise it will be a root span. This behavior can be overridden by providing `WithNewRoot()` as a SpanOption, causing the newly-created Span to be a root span even if `ctx` contains a Span.

When creating a Span it is recommended to provide all known span attributes using the `WithAttributes()` SpanOption as samplers will only have access to the attributes provided when a Span is created.

Any Span that is created MUST also be ended. This is the responsibility of the user. Implementations of this API may leak memory or other resources if Spans are not ended.