instatrace

README

Instana OpenCensus trace exporter

Package instatrace provides Instana trace continuation by mapping the spans created within code instrumented with OpenCensus onto ongoing Instana traces.

Installation

The OpenCensus exporter is provided as a separate package and can be installed via go get:

go get github.com/instana/go-sensor/instrumentation/go.opencensus.io/instatrace

Usage

To map OpenCensus traces to Instana ones first register an instatrace.Mapper as an exporter for OpenCensus spans (this is usually done in your main() function, close to where Instana sensor is initialized:

sensor := instana.NewSensor("my-opencensus-service")
trace.RegisterExporter(instatrace.NewMapper(sensor))

To correlate traces, the instatrace.Mapper needs an entry point to the code instrumented with OpenCensus. (*instatrace.Mapper).Context() checks whether there is an active OpenCensus trace present in provided context and maps this trace to an ongoing Instana trace stored within the same context. If there is no active OpenCensus trace yet, (*instatrace.Mapper).Context() initiates one:

func InstanaInstrumentedMethod(exporter *instatrace.Mapper) {
	// Initialize and inject an Instana trace into context.Context. This is usually already done for you
	// by an instrumentation wrapper provided with github.com/instana/go-sensor
	sp := sensor.Tracer().StartSpan("entry")
	defer sp.Finish()

	ctx := instana.ContextWithSpan(context.Background(), sp)

	// Mark the entry point into the OpenCensus-instrumented code block to correlate its spans with Instana trace
	ctx, _ := exporter.Context(ctx)
	OpenCensusInstrumentedMethod(ctx)
	// ...
}

Once this is done, the exporter will send an Instana span for every OpenCensus span created from within this context, and attribute them to the same Instana trace.

Documentation

Overview

Package instatrace provides Instana trace continuation by mapping the spans created within code instrumented with OpenCensus onto ongoing Instana traces.

To map OpenCensus traces to Instana ones first register an exporter (this is usually done in your main() function, close to where Instana sensor is initialized:

sensor := instana.NewSensor("my-opencensus-service")
trace.RegisterExporter(instatrace.NewMapper(sensor))

To correlate traces, the instatrace.Mapper needs an entry point to the code instrumented with OpenCensus. (*instatrace.Mapper).Context() checks whether there is an active OpenCensus trace present in provided context and maps this trace to an ongoing Instana trace stored within the same context. If there is no active OpenCensus trace yet, (*instatrace.Mapper).Context() initiates one:

    func InstanaInstrumentedMethod(exporter *instatrace.Mapper) {
        // Initialize and inject an Instana trace into context.Context. This is usually already done for you
	// by an instrumentation wrapper provided with github.com/instana/go-sensor
        sp := sensor.Tracer().StartSpan("entry")
        defer sp.Finish()

        ctx := instana.ContextWithSpan(context.Background(), sp)

        // Mark the entry point into the OpenCensus-instrumented code block to correlate its spans with Instana trace
	ctx, _ := exporter.Context(ctx)
	OpenCensusInstrumentedMethod(ctx)
        // ...
    }

Once this is done, the exporter will send an Instana span for every OpenCensus span created from within this context, and attribute them to the same Instana trace.

Index

• type Mapper
  • func NewMapper(sensor *instana.Sensor) *Mapper
  • func NewMapperWithOptions(sensor *instana.Sensor, opts MapperOptions) *Mapper
  • func (exp *Mapper) Context(ctx context.Context) (context.Context, *trace.Span)
  • func (exp *Mapper) ExportSpan(s *trace.SpanData)
• type MapperOptions

Types

type Mapper

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

Mapper is an go.opencensus.io/trace.Exporter that listens for OpenCensus spans and maps them to Instana traces

func NewMapper

func NewMapper(sensor *instana.Sensor) *Mapper

NewMapper initializes a new opencensus.Mapper with default options

func NewMapperWithOptions

func NewMapperWithOptions(sensor *instana.Sensor, opts MapperOptions) *Mapper

NewMapper initializes a new opencensus.Mapper with provided options

func (*Mapper) Context

func (exp *Mapper) Context(ctx context.Context) (context.Context, *trace.Span)

Context starts a new OpenCensus span and injects it into provided context. This span is than used to correlate the OpenCensus trace with Instana

func (*Mapper) ExportSpan

func (exp *Mapper) ExportSpan(s *trace.SpanData)

ExportSpan implements go.opencensus.io/trace.Exporter for Exporter

type MapperOptions

type MapperOptions struct {
	// The maximum time to keep OpenCensus spans that cannot be mapped to Instana trace in cache.
	// If an exit span for a trace does not arrive within this period of time, it will be discarded.
	// By default the exported does not discard any spans.
	MaxTraceDuration time.Duration
}

ExporterOptions contains configuration for Exporter