apptracer

README

apptracer

apptracer is multiple trace system wrapper for Stackdriver Trace, AWS X-Ray and LightStep.

Usage

import (
	"github.com/evalphobia/apptracer"
	"github.com/evalphobia/apptracer/platform/localdebug"
	"github.com/evalphobia/apptracer/platform/lightstep"
	"github.com/evalphobia/apptracer/platform/opencensus/datadog"
	"github.com/evalphobia/apptracer/platform/opencensus/xray"
	"github.com/evalphobia/apptracer/platform/opencensus/stackdriver"
)

// global singleton tracer.
var tracer *apptracer.AppTracer

// Init initializes trace setting.
func Init() {
	// init tracer
	tracer = apptracer.New(apptracer.Config{
		Enable:      true,
		ServiceName: "my-cool-app",
		Version:     "v0.0.1",
		Environment: "stage",
	})

	// add localdebug trace (show trace data on the given Logger).
	if isDebug() {
		localCli := localdebug.NewClient(localdebug.Config{
			Logger: nil, // when it's nil, default std.err logger is set.
		})
		tracer.AddClient(localCli)
	}

	// add LightStep
	lsCli := lightstep.NewClient(lightstep.Config{
		AccessToken: "<LightStep access token>",
		ServiceName: "stage-my-cool-app",
	})
	tracer.AddClient(lsCli)

	// add opencensus trace
	{
		// datadog (installed agent is needed)
		ddExp, err := datadog.NewExporter(context.Background(), "my-cool-app")
		if err != nil {
			panic(err)
		}

		// stackdriver trace
		projectID := "test-morikawa"
		sdExp, err := stackdriver.NewExporter(context.Background(), stackdriver.Config{
			// auth setting
			PrivateKey: "<GCP private key>",
			Email:      "<GCP email address>",
			// Filename: "/path/to/pem.json",
		}, "<GCP projectID>")
		if err != nil {
			panic(err)
		}

		// aws xray trace
		xrayExp, err := xray.NewExporter(context.Background())

		ocCli := opencensus.NewClient(ddExp, sdExp, xrayExp)
		opencensus.SetSamplingRate(1) // 100%
		tracer.AddClient(ocCli)
	}

	tracer.Flush()
}

func MainFunction(ctx context.Context, r *http.Request) {
    // Before use tracer and get span, you have to call Init() to initialzed tracer.

	// defer tracer.Close()
	defer tracer.Flush()


	span := tracer.Trace(ctx).NewRootSpanFromRequest(r)
	defer func(){
		span.SetResponse(200).Finish()
		// debug print for localdebug client
		// span.OutputSummary()
	}()

	childFunction1(ctx)
	childFunction2(ctx)
	childFunction3(ctx)
}

func childFunction1(ctx context.Context) {
	defer tracer.Trace(ctx).NewChildSpan("childFunction1").Finish()
	// ... process something
}

// get user data
func childFunction2(ctx context.Context) error {
	var user string
	var err error

	span := tracer.Trace(ctx).NewChildSpan("childFunction2")
	defer func(){
		span.SetUser(user).SetError(err).Finish()
	}()

	user, err = getUserName()
	if err != nil {
		return err
	}

	// process something ...

	return nil
}


// exec sql
func childFunction3(ctx context.Context) error {
	var sql string

	span := tracer.Trace(ctx).NewChildSpan("childFunction3")
	defer func(){
		span.SetSQL(sql).Finish()
	}()

	sql = "SELECT * FROM users"
	users, err = execSQL(sql)
	if err != nil {
		return err
	}

	// process something ...

	return nil
}

Supported Platform

• OpenCensus
  • Datadog trace
    • Google Stackdriver trace
    • New Relic
    • AWS X-Ray
• LightStep

TODO

• Supports microservices tracing
• Supports other platforms

Whats For?

One code for multiple tracing platforms!

• Compare and PoC tracing platforms .
• Multiple platforms with different sampling rates.

Documentation

Index

• type AppTracer
  • func New(conf Config) *AppTracer
  • func (a *AppTracer) AddClient(c PlatformClient)
  • func (a *AppTracer) Close()
  • func (a *AppTracer) Flush()
  • func (a *AppTracer) Trace(ctx context.Context) *TraceWrapper
• type Config
• type Label
  • func NewLabel(key, value string) Label
• type PlatformClient
• type SpanWrapper
  • func (s *SpanWrapper) Context() context.Context
  • func (s *SpanWrapper) Finish()
  • func (s *SpanWrapper) GetSummary() []string
  • func (s *SpanWrapper) NewChildSpan(name string) *SpanWrapper
  • func (s *SpanWrapper) OutputSummary()
  • func (s *SpanWrapper) SetEnvironment(env string) *SpanWrapper
  • func (s *SpanWrapper) SetError(err error) *SpanWrapper
  • func (s *SpanWrapper) SetLabel(key, value string) *SpanWrapper
  • func (s *SpanWrapper) SetLabels(labels []Label) *SpanWrapper
  • func (s *SpanWrapper) SetResponse(status int) *SpanWrapper
  • func (s *SpanWrapper) SetSQL(sql string) *SpanWrapper
  • func (s *SpanWrapper) SetServiceName(name string) *SpanWrapper
  • func (s *SpanWrapper) SetUser(user string) *SpanWrapper
  • func (s *SpanWrapper) SetVersion(ver string) *SpanWrapper
• type TraceWrapper
  • func (t *TraceWrapper) NewChildSpan(name string) *SpanWrapper
  • func (t *TraceWrapper) NewRootSpan(name string) *SpanWrapper
  • func (t *TraceWrapper) NewRootSpanFromRequest(r *http.Request) *SpanWrapper

Types

type AppTracer

type AppTracer struct {
	Config
	ClientList []PlatformClient
}

AppTracer has multiple tracing platform clients to send tracing activity to the platforms.

func New

func New(conf Config) *AppTracer

New returns initialized AppTracer.

func (*AppTracer) AddClient

func (a *AppTracer) AddClient(c PlatformClient)

AddClient adds PlatformClient into ClientList.

func (*AppTracer) Close

func (a *AppTracer) Close()

Close closes all of the clients.

func (*AppTracer) Flush

func (a *AppTracer) Flush()

Flush waits for exported data to be uploaded.

func (*AppTracer) Trace

func (a *AppTracer) Trace(ctx context.Context) *TraceWrapper

Trace creates *TraceWrapper from context. TraceWrapper contains platform clients and generates span data for the platforms. TraceWrapper is cached in the context and you can get same TraceWrapper when pass the same context.

type Config

type Config struct {
	// Only if Enable is true then tracing data sends to tracing platform.
	Enable bool
	// DefaultLabels sets labels into every tracing data(span).
	DefaultLabels []Label
	// ServiceName is your application name.
	ServiceName string
	// Version is your application version.
	Version string
	// Environment is your application version. (e.g. dev, stage, prod)
	Environment string
}

Config contains tracing settings.

type Label

type Label struct {
	Key   string
	Value string
}

Label has key-value pair data for labeling.

func NewLabel

func NewLabel(key, value string) Label

NewLabel creates Label.

type PlatformClient

type PlatformClient interface {
	// NewTrace creates Trace of this tracing platform.
	// Trace could be generated for each request.
	NewTrace(context.Context) (platform.Trace, error)
	// Flush waits for exported data to be uploaded.
	Flush()
	// Close closes client.
	Close()
}

PlatformClient is tracing platform client. It's singleton struct for each platform.

type SpanWrapper

type SpanWrapper struct {
	IsRoot bool
	// contains filtered or unexported fields
}

SpanWrapper contains multiple Span data for each platforms.

func (*SpanWrapper) Context

func (s *SpanWrapper) Context() context.Context

Context returns context.Context in this SpanWrapper.

func (*SpanWrapper) Finish

func (s *SpanWrapper) Finish()

Finish sends tracing data(span) for each platforms.

func (*SpanWrapper) GetSummary

func (s *SpanWrapper) GetSummary() []string

GetSummary gets trace summary of the spans.

func (*SpanWrapper) NewChildSpan

func (s *SpanWrapper) NewChildSpan(name string) *SpanWrapper

NewChildSpan creates SpanWrapper with child span data.

func (*SpanWrapper) OutputSummary

func (s *SpanWrapper) OutputSummary()

OutputSummary prints trace summary of the spans.

func (*SpanWrapper) SetEnvironment

func (s *SpanWrapper) SetEnvironment(env string) *SpanWrapper

SetEnvironment sets environment data into each spans.

func (*SpanWrapper) SetError

func (s *SpanWrapper) SetError(err error) *SpanWrapper

SetError sets error data into each spans.

func (*SpanWrapper) SetLabel

func (s *SpanWrapper) SetLabel(key, value string) *SpanWrapper

SetLabel sets labels into each spans.

func (*SpanWrapper) SetLabels

func (s *SpanWrapper) SetLabels(labels []Label) *SpanWrapper

SetLabels sets multiple labels into each spans.

func (*SpanWrapper) SetResponse

func (s *SpanWrapper) SetResponse(status int) *SpanWrapper

SetResponse sets response status code into each spans.

func (*SpanWrapper) SetSQL

func (s *SpanWrapper) SetSQL(sql string) *SpanWrapper

SetSQL sets sql data into each spans.

func (*SpanWrapper) SetServiceName

func (s *SpanWrapper) SetServiceName(name string) *SpanWrapper

SetServiceName sets service name into each spans.

func (*SpanWrapper) SetUser

func (s *SpanWrapper) SetUser(user string) *SpanWrapper

SetUser sets user data into each spans.

func (*SpanWrapper) SetVersion

func (s *SpanWrapper) SetVersion(ver string) *SpanWrapper

SetVersion sets version data into each spans.

type TraceWrapper

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

TraceWrapper contains multiple Trace data for each platforms.

func (*TraceWrapper) NewChildSpan

func (t *TraceWrapper) NewChildSpan(name string) *SpanWrapper

NewChildSpan creates child *SpanWrapper.

func (*TraceWrapper) NewRootSpan

func (t *TraceWrapper) NewRootSpan(name string) *SpanWrapper

NewRootSpan creates root *SpanWrapper, which is top of parent span.

func (*TraceWrapper) NewRootSpanFromRequest

func (t *TraceWrapper) NewRootSpanFromRequest(r *http.Request) *SpanWrapper

NewRootSpanFromRequest creates root *SpanWrapper from *http.Request.