instana

README

Instana Go Sensor

golang-sensor requires Go version 1.7 or greater.

The Instana Go sensor consists of two parts:

• metrics sensor
• OpenTracing tracer

Sensor

To use sensor only without tracing ability, import the instana package and run

instana.InitSensor(opt)

in your main function. The init function takes an Options object with the following optional fields:

• Service - global service name that will be used to identify the program in the Instana backend
• AgentHost, AgentPort - default to localhost:42699, set the coordinates of the Instana proxy agent
• LogLevel - one of Error, Warn, Info or Debug

Once initialized, the sensor will try to connect to the given Instana agent and in case of connection success will send metrics and snapshot information through the agent to the backend.

OpenTracing

In case you want to use the OpenTracing tracer, it will automatically initialize the sensor and thus also activate the metrics stream. To activate the global tracer, run for example

ot.InitGlobalTracer(instana.NewTracerWithOptions(&instana.Options{
	Service:  SERVICE,
	LogLevel: instana.DEBUG}))

in your main function. The tracer takes the same options that the sensor takes for initialization, described above.

The tracer is able to protocol and piggyback OpenTracing baggage, tags and logs. Only text mapping is implemented yet, binary is not supported. Also, the tracer tries to map the OpenTracing spans to the Instana model based on OpenTracing recommended tags. See simple example for details on how recommended tags are used.

The Instana tracer will remap OpenTracing HTTP headers into Instana Headers, so parallel use with some other OpenTracing model is not possible. The Instana tracer is based on the OpenTracing Go basictracer with necessary modifications to map to the Instana tracing model. Also, sampling isn't implemented yet and will be focus of future work.

Events API

The sensor, be it instantiated explicitly or implicitly through the tracer, provides a simple wrapper API to send events to Instana as described in its documentation.

To learn more, see the Events API document in this repository.

Examples

Following examples are included in the examples folder:

• ot-simple/simple.go - Demonstrates basic usage of the tracer
• webserver/http.go - Demonstrates how http server and client should be instrumented
• rpc/rpc.go - Demonstrates a basic RPC service
• event/ - Demonstrates usage of the event API

Documentation

Index

• Constants
• func EumSnippet(apiKey string, traceID string, meta map[string]string) string
• func Header2ID(header string) (int64, error)
• func ID2Header(id int64) (string, error)
• func InitSensor(options *Options)
• func NewTracer() ot.Tracer
• func NewTracerWithEverything(options *Options, recorder SpanRecorder) ot.Tracer
• func NewTracerWithOptions(options *Options) ot.Tracer
• func SendDefaultServiceEvent(title string, text string, sev severity, duration time.Duration)
• func SendHostEvent(title string, text string, sev severity, duration time.Duration)
• func SendServiceEvent(service string, title string, text string, sev severity, ...)
• type EntityData
• type EventData
• type MemoryS
• type MetricsS
• type Options
• type Recorder
  • func NewRecorder() *Recorder
  • func NewTestRecorder() *Recorder
  • func (r *Recorder) GetQueuedSpans() []jsonSpan
  • func (r *Recorder) QueuedSpansCount() int
  • func (r *Recorder) RecordSpan(span *spanS)
• type SnapshotS
• type SpanContext
  • func (c SpanContext) ForeachBaggageItem(handler func(k, v string) bool)
  • func (c SpanContext) WithBaggageItem(key, val string) SpanContext
• type SpanRecorder
• type Tracer
• type TracerOptions

Constants

const (
	SeverityChange   severity = -1
	SeverityWarning  severity = 5
	SeverityCritical severity = 10
)

Severity values for events sent to the instana agent

const (
	ServicePlugin = "com.instana.forge.connection.http.logical.LogicalWebApp"
	ServiceHost   = ""
)

Defaults for the Event API

const (
	Error = 0
	Warn  = 1
	Info  = 2
	Debug = 3
)

Valid log levels

const (
	// FieldT Trace ID header
	FieldT = "x-instana-t"
	// FieldS Span ID header
	FieldS = "x-instana-s"
	// FieldL Level header
	FieldL = "x-instana-l"
	// FieldB OT Baggage header
	FieldB = "x-instana-b-"
)

Instana header constants

const (
	DefaultMaxBufferedSpans = 1000
	DefaultForceSpanSendAt  = 500
)

const (
	// MaxLogsPerSpan The maximum number of logs allowed on a span.
	MaxLogsPerSpan = 2
)

const (
	// SnapshotPeriod is the amount of time in seconds between snapshot reports.
	SnapshotPeriod = 600
)

Functions

func EumSnippet

func EumSnippet(apiKey string, traceID string, meta map[string]string) string

EumSnippet generates javascript code to initialize JavaScript agent

func Header2ID

func Header2ID(header string) (int64, error)

Header2ID converts an header context value into an Instana ID. More specifically, this converts an unsigned 64 bit hex value into a signed 64bit integer.

func ID2Header

func ID2Header(id int64) (string, error)

ID2Header converts an Instana ID to a value that can be used in context propagation (such as HTTP headers). More specifically, this converts a signed 64 bit integer into an unsigned hex string.

func InitSensor

func InitSensor(options *Options)

InitSensor Intializes the sensor (without tracing) to begin collecting and reporting metrics.

func NewTracer

func NewTracer() ot.Tracer

NewTracer Get a new Tracer with the default options applied.

func NewTracerWithEverything

func NewTracerWithEverything(options *Options, recorder SpanRecorder) ot.Tracer

NewTracerWithEverything Get a new Tracer with the works.

func NewTracerWithOptions

func NewTracerWithOptions(options *Options) ot.Tracer

NewTracerWithOptions Get a new Tracer with the specified options.

func SendDefaultServiceEvent

func SendDefaultServiceEvent(title string, text string, sev severity, duration time.Duration)

SendDefaultServiceEvent sends a default event which already contains the service and host

func SendHostEvent

func SendHostEvent(title string, text string, sev severity, duration time.Duration)

SendHostEvent send an event on the current host

func SendServiceEvent

func SendServiceEvent(service string, title string, text string, sev severity, duration time.Duration)

SendServiceEvent send an event on a specific service

Types

type EntityData

type EntityData struct {
	PID      int        `json:"pid"`
	Snapshot *SnapshotS `json:"snapshot,omitempty"`
	Metrics  *MetricsS  `json:"metrics"`
}

EntityData struct to hold snapshot data.

type EventData

type EventData struct {
	Title string `json:"title"`
	Text  string `json:"text"`
	// Duration in milliseconds
	Duration int `json:"duration"`
	// Severity with value of -1, 5, 10 : see type severity
	Severity int    `json:"severity"`
	Plugin   string `json:"plugin,omitempty"`
	ID       string `json:"id,omitempty"`
	Host     string `json:"host"`
}

EventData is the construct serialized for the host agent

type MemoryS

type MemoryS struct {
	Alloc         uint64  `json:"alloc"`
	TotalAlloc    uint64  `json:"total_alloc"`
	Sys           uint64  `json:"sys"`
	Lookups       uint64  `json:"lookups"`
	Mallocs       uint64  `json:"mallocs"`
	Frees         uint64  `json:"frees"`
	HeapAlloc     uint64  `json:"heap_alloc"`
	HeapSys       uint64  `json:"heap_sys"`
	HeapIdle      uint64  `json:"heap_idle"`
	HeapInuse     uint64  `json:"heap_in_use"`
	HeapReleased  uint64  `json:"heap_released"`
	HeapObjects   uint64  `json:"heap_objects"`
	PauseTotalNs  uint64  `json:"pause_total_ns"`
	PauseNs       uint64  `json:"pause_ns"`
	NumGC         uint32  `json:"num_gc"`
	GCCPUFraction float64 `json:"gc_cpu_fraction"`
}

MemoryS struct to hold snapshot data.

type MetricsS

type MetricsS struct {
	CgoCall   int64    `json:"cgo_call"`
	Goroutine int      `json:"goroutine"`
	Memory    *MemoryS `json:"memory"`
}

MetricsS struct to hold snapshot data.

type Options

type Options struct {
	Service                     string
	AgentHost                   string
	AgentPort                   int
	MaxBufferedSpans            int
	ForceTransmissionStartingAt int
	LogLevel                    int
}

Options allows the user to configure the to-be-initialized sensor

type Recorder

type Recorder struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Recorder accepts spans, processes and queues them for delivery to the backend.

func NewRecorder

func NewRecorder() *Recorder

NewRecorder Establish a Recorder span recorder

func NewTestRecorder

func NewTestRecorder() *Recorder

NewTestRecorder Establish a new span recorder used for testing

func (*Recorder) GetQueuedSpans

func (r *Recorder) GetQueuedSpans() []jsonSpan

GetQueuedSpans returns a copy of the queued spans and clears the queue.

func (*Recorder) QueuedSpansCount

func (r *Recorder) QueuedSpansCount() int

QueuedSpansCount returns the number of queued spans

Used only in tests currently.

func (*Recorder) RecordSpan

func (r *Recorder) RecordSpan(span *spanS)

RecordSpan accepts spans to be recorded and and added to the span queue for eventual reporting to the host agent.

type SnapshotS

type SnapshotS struct {
	Name     string `json:"name"`
	Version  string `json:"version"`
	Root     string `json:"goroot"`
	MaxProcs int    `json:"maxprocs"`
	Compiler string `json:"compiler"`
	NumCPU   int    `json:"cpu"`
}

SnapshotS struct to hold snapshot data.

type SpanContext

type SpanContext struct {
	// A probabilistically unique identifier for a [multi-span] trace.
	TraceID int64

	// A probabilistically unique identifier for a span.
	SpanID int64

	// Whether the trace is sampled.
	Sampled bool

	// The span's associated baggage.
	Baggage map[string]string // initialized on first use
}

SpanContext holds the basic Span metadata.

func (SpanContext) ForeachBaggageItem

func (c SpanContext) ForeachBaggageItem(handler func(k, v string) bool)

ForeachBaggageItem belongs to the opentracing.SpanContext interface

func (SpanContext) WithBaggageItem

func (c SpanContext) WithBaggageItem(key, val string) SpanContext

WithBaggageItem returns an entirely new SpanContext with the given key:value baggage pair set.

type SpanRecorder

type SpanRecorder interface {
	// Implementations must determine whether and where to store `span`.
	RecordSpan(span *spanS)
}

A SpanRecorder handles all of the `RawSpan` data generated via an associated `Tracer` (see `NewStandardTracer`) instance. It also names the containing process and provides access to a straightforward tag map.

type Tracer

type Tracer interface {
	opentracing.Tracer

	// Options gets the Options used in New() or NewWithOptions().
	Options() TracerOptions
}

Tracer extends the opentracing.Tracer interface

type TracerOptions

type TracerOptions struct {
	// ShouldSample is a function which is called when creating a new Span and
	// determines whether that Span is sampled. The randomized TraceID is supplied
	// to allow deterministic sampling decisions to be made across different nodes.
	// For example,
	//
	//   func(traceID uint64) { return traceID % 64 == 0 }
	//
	// samples every 64th trace on average.
	ShouldSample func(traceID int64) bool
	// TrimUnsampledSpans turns potentially expensive operations on unsampled
	// Spans into no-ops. More precisely, tags and log events are silently
	// discarded. If NewSpanEventListener is set, the callbacks will still fire.
	TrimUnsampledSpans bool
	// Recorder receives Spans which have been finished.
	Recorder SpanRecorder
	// NewSpanEventListener can be used to enhance the tracer by effectively
	// attaching external code to trace events. See NetTraceIntegrator for a
	// practical example, and event.go for the list of possible events.
	NewSpanEventListener func() func(bt.SpanEvent)
	// DropAllLogs turns log events on all Spans into no-ops.
	// If NewSpanEventListener is set, the callbacks will still fire.
	DropAllLogs bool
	// MaxLogsPerSpan limits the number of Logs in a span (if set to a nonzero
	// value). If a span has more logs than this value, logs are dropped as
	// necessary (and replaced with a log describing how many were dropped).
	//
	// About half of the MaxLogPerSpan logs kept are the oldest logs, and about
	// half are the newest logs.
	//
	// If NewSpanEventListener is set, the callbacks will still fire for all log
	// events. This value is ignored if DropAllLogs is true.
	MaxLogsPerSpan int
	// DebugAssertSingleGoroutine internally records the ID of the goroutine
	// creating each Span and verifies that no operation is carried out on
	// it on a different goroutine.
	// Provided strictly for development purposes.
	// Passing Spans between goroutine without proper synchronization often
	// results in use-after-Finish() errors. For a simple example, consider the
	// following pseudocode:
	//
	//  func (s *Server) Handle(req http.Request) error {
	//    sp := s.StartSpan("server")
	//    defer sp.Finish()
	//    wait := s.queueProcessing(opentracing.ContextWithSpan(context.Background(), sp), req)
	//    select {
	//    case resp := <-wait:
	//      return resp.Error
	//    case <-time.After(10*time.Second):
	//      sp.LogEvent("timed out waiting for processing")
	//      return ErrTimedOut
	//    }
	//  }
	//
	// This looks reasonable at first, but a request which spends more than ten
	// seconds in the queue is abandoned by the main goroutine and its trace
	// finished, leading to use-after-finish when the request is finally
	// processed. Note also that even joining on to a finished Span via
	// StartSpanWithOptions constitutes an illegal operation.
	//
	// Code bases which do not require (or decide they do not want) Spans to
	// be passed across goroutine boundaries can run with this flag enabled in
	// tests to increase their chances of spotting wrong-doers.
	DebugAssertSingleGoroutine bool
	// DebugAssertUseAfterFinish is provided strictly for development purposes.
	// When set, it attempts to exacerbate issues emanating from use of Spans
	// after calling Finish by running additional assertions.
	DebugAssertUseAfterFinish bool
	// EnableSpanPool enables the use of a pool, so that the tracer reuses spans
	// after Finish has been called on it. Adds a slight performance gain as it
	// reduces allocations. However, if you have any use-after-finish race
	// conditions the code may panic.
	EnableSpanPool bool
}

TracerOptions allows creating a customized Tracer via NewWithOptions. The object must not be updated when there is an active tracer using it.