tab

README

Trace Abstraction (tab)

OpenTracing and OpenCensus abstraction for tracing and logging.

Why? Well, sometimes you want to let the consumer choose the tracing / logging implementation.

Getting Started

Installing the library

go get -u github.com/devigned/tab

If you need to install Go, follow the official instructions

Usage

package main

import (
	"context"
	"fmt"
	
	"github.com/devigned/tab"
	_ "github.com/devigned/tab/opencensus" // use OpenCensus
	// _ "github.com/devigned/tab/opentracing" // use OpenTracing
)

func main() {
	// start a root span
	ctx, span := tab.StartSpan(context.Background(), "main")
	defer span.End() // close span when done
	
	// pass context w/ span to child func
	printHelloWorld(ctx)
}

func printHelloWorld(ctx context.Context) {
	// start new span from parent
	_, span := tab.StartSpan(ctx, "printHelloWorld")
	defer span.End() // close span when done
	
	// add attribute to span
	span.AddAttributes(tab.StringAttribute("interesting", "value"))
	fmt.Println("Hello World!")
	tab.For(ctx).Info("after println call")
}

Documentation

Index

• func NewContext(ctx context.Context, span Spanner) context.Context
• func Register(t Tracer)
• type Attribute
  • func BoolAttribute(key string, value bool) Attribute
  • func Int64Attribute(key string, value int64) Attribute
  • func StringAttribute(key, value string) Attribute
• type Carrier
• type Logger
  • func For(ctx context.Context) Logger
• type NoOpTracer
  • func (nt *NoOpTracer) FromContext(ctx context.Context) Spanner
  • func (nt *NoOpTracer) NewContext(parent context.Context, span Spanner) context.Context
  • func (nt *NoOpTracer) StartSpan(ctx context.Context, operationName string, opts ...interface{}) (context.Context, Spanner)
  • func (nt *NoOpTracer) StartSpanWithRemoteParent(ctx context.Context, operationName string, carrier Carrier, ...) (context.Context, Spanner)
• type SpanLogger
  • func (sl SpanLogger) Debug(msg string, attributes ...Attribute)
  • func (sl SpanLogger) Error(err error, attributes ...Attribute)
  • func (sl SpanLogger) Fatal(msg string, attributes ...Attribute)
  • func (sl SpanLogger) Info(msg string, attributes ...Attribute)
• type Spanner
  • func FromContext(ctx context.Context) Spanner
  • func StartSpan(ctx context.Context, operationName string, opts ...interface{}) (context.Context, Spanner)
  • func StartSpanWithRemoteParent(ctx context.Context, operationName string, carrier Carrier, ...) (context.Context, Spanner)
• type Tracer

Functions

func NewContext

func NewContext(ctx context.Context, span Spanner) context.Context

NewContext returns a new context with the given Span attached.

func Register

func Register(t Tracer)

Register a Tracer instance

Types

type Attribute

type Attribute struct {
	Key   string
	Value interface{}
}

Attribute is a key value pair for decorating spans

func BoolAttribute

func BoolAttribute(key string, value bool) Attribute

BoolAttribute returns a bool-valued attribute.

func Int64Attribute

func Int64Attribute(key string, value int64) Attribute

Int64Attribute returns an int64-valued attribute.

func StringAttribute

func StringAttribute(key, value string) Attribute

StringAttribute returns a string-valued attribute.

type Carrier

type Carrier interface {
	Set(key string, value interface{})
	GetKeyValues() map[string]interface{}
}

Carrier is an abstraction over OpenTracing and OpenCensus propagation carrier

type Logger

type Logger interface {
	Info(msg string, attributes ...Attribute)
	Error(err error, attributes ...Attribute)
	Fatal(msg string, attributes ...Attribute)
	Debug(msg string, attributes ...Attribute)
}

Logger is a generic interface for logging

func For

func For(ctx context.Context) Logger

For will return a logger for a given context

type NoOpTracer

type NoOpTracer struct{}

NoOpTracer is a Tracer implementation that does nothing, thus no op

func (*NoOpTracer) FromContext

func (nt *NoOpTracer) FromContext(ctx context.Context) Spanner

FromContext returns a no op Spanner without regard to the input context

func (*NoOpTracer) NewContext

func (nt *NoOpTracer) NewContext(parent context.Context, span Spanner) context.Context

NewContext returns the parent context

func (*NoOpTracer) StartSpan

func (nt *NoOpTracer) StartSpan(ctx context.Context, operationName string, opts ...interface{}) (context.Context, Spanner)

StartSpan returns the input context and a no op Spanner

func (*NoOpTracer) StartSpanWithRemoteParent

func (nt *NoOpTracer) StartSpanWithRemoteParent(ctx context.Context, operationName string, carrier Carrier, opts ...interface{}) (context.Context, Spanner)

StartSpanWithRemoteParent returns the input context and a no op Spanner

type SpanLogger

type SpanLogger struct {
	Span Spanner
}

SpanLogger is a Logger implementation which logs to a tracing span

func (SpanLogger) Debug

func (sl SpanLogger) Debug(msg string, attributes ...Attribute)

Debug logs a debug tag with message to a span

func (SpanLogger) Error

func (sl SpanLogger) Error(err error, attributes ...Attribute)

Error logs an error tag with message to a span

func (SpanLogger) Fatal

func (sl SpanLogger) Fatal(msg string, attributes ...Attribute)

Fatal logs an error tag with message to a span

func (SpanLogger) Info

func (sl SpanLogger) Info(msg string, attributes ...Attribute)

Info logs an info tag with message to a span

type Spanner

type Spanner interface {
	AddAttributes(attributes ...Attribute)
	End()
	Logger() Logger
	Inject(carrier Carrier) error
	InternalSpan() interface{}
}

Spanner is an abstraction over OpenTracing and OpenCensus Spans

func FromContext

func FromContext(ctx context.Context) Spanner

FromContext returns the Span stored in a context, or nil if there isn't one.

func StartSpan

func StartSpan(ctx context.Context, operationName string, opts ...interface{}) (context.Context, Spanner)

StartSpan starts a new child span

func StartSpanWithRemoteParent

func StartSpanWithRemoteParent(ctx context.Context, operationName string, carrier Carrier, opts ...interface{}) (context.Context, Spanner)

StartSpanWithRemoteParent starts a new child span of the span from the given parent.

type Tracer

type Tracer interface {
	StartSpan(ctx context.Context, operationName string, opts ...interface{}) (context.Context, Spanner)
	StartSpanWithRemoteParent(ctx context.Context, operationName string, carrier Carrier, opts ...interface{}) (context.Context, Spanner)
	FromContext(ctx context.Context) Spanner
	NewContext(parent context.Context, span Spanner) context.Context
}

Tracer is an abstraction over OpenTracing and OpenCensus trace implementations