go2sky

README

GO2Sky

GO2Sky is an instrument SDK library, written in Go, by following Apache SkyWalking tracing and metrics formats.

Installation

$ go get -u github.com/SkyAPM/go2sky

The API of this project is still evolving. The use of vendoring tool is recommended.

Quickstart

By completing this quickstart, you will learn how to trace local methods. For more details, please view the example.

Configuration

GO2Sky can export traces to Apache SkyWalking OAP server or local logger. In the following example, we configure GO2Sky to export to OAP server, which is listening on oap-skywalking port 11800, and all the spans from this program will be associated with a service name example. reporter.GRPCReporter can also adjust the behavior through reporter.GRPCReporterOption, view all.

r, err := reporter.NewGRPCReporter("oap-skywalking:11800")
if err != nil {
    log.Fatalf("new reporter error %v \n", err)
}
defer r.Close()
tracer, err := go2sky.NewTracer("example", go2sky.WithReporter(r))
// create with sampler
// tracer, err := go2sky.NewTracer("example", go2sky.WithReporter(r), go2sky.WithSampler(0.5))

You can also create tracer with sampling rate.

....
tracer, err := go2sky.NewTracer("example", go2sky.WithReporter(r), go2sky.WithSampler(0.5))

Create span

To create a span in a trace, we used the Tracer to start a new span. We indicate this as the root span because of passing context.Background(). We must also be sure to end this span, which will be show in End span.

span, ctx, err := tracer.CreateLocalSpan(context.Background())

Get Global TraceID

Get the TraceID of the activeSpan in the Context.

go2sky.TraceID(ctx)

Create a sub span

A sub span created as the children of root span links to its parent with Context.

subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)

End span

We must end the spans so they becomes available for sending to the backend by a reporter.

subSpan.End()
span.End()

Advanced Concepts

We cover some advanced topics about GO2Sky.

Context propagation

Trace links spans belong to it by using context propagation which varies between different scenario.

In process

We use context package to link spans. The root span usually pick context.Background(), and sub spans will inject the context generated by its parent.

//Create a new context
entrySpan, entryCtx, err := tracer.CreateEntrySpan(context.Background(), ...)

// Some operation
...

// Link two spans by injecting entrySpan context into exitSpan
exitSpan, err := tracer.CreateExitSpan(entryCtx, ...)

Crossing process

We use Entry span to extract context from downstream service, and use Exit span to inject context to upstream service.

Entry and Exit spans make sense to OAP analysis which generates topology map and service metrics.

//Extract context from HTTP request header `sw8`
span, ctx, err := tracer.CreateEntrySpan(r.Context(), "/api/login", func() (string, error) {
		return r.Header.Get("sw8"), nil
})

// Some operation
...

// Inject context into HTTP request header `sw8`
span, err := tracer.CreateExitSpan(req.Context(), "/service/validate", "tomcat-service:8080", func(header string) error {
		req.Header.Set(propagation.Header, header)
		return nil
})

Tag

We set tags into a span which is stored in the backend, but some tags have special purpose. OAP server may use them to aggregate metrics, generate topology map and etc.

They are defined as constant in root package with prefix Tag.

Plugins

Go to go2sky-plugins repo to see all the plugins, click here.

License

Apache License 2.0. See LICENSE file for details.

Documentation

Overview

Package go2sky implements a native Apache SkyWalking agent library for Go.

See http://skywalking.apache.org/ for more information about Apache SkyWalking.

Index

• Constants
• func TraceID(ctx context.Context) string
• type ConstSampler
  • func NewConstSampler(sample bool) *ConstSampler
  • func (s *ConstSampler) IsSampled(operation string) bool
• type NoopSpan
  • func (*NoopSpan) End()
  • func (*NoopSpan) Error(time.Time, ...string)
  • func (*NoopSpan) GetOperationName() string
  • func (*NoopSpan) IsEntry() bool
  • func (*NoopSpan) IsExit() bool
  • func (*NoopSpan) Log(time.Time, ...string)
  • func (*NoopSpan) SetComponent(int32)
  • func (*NoopSpan) SetOperationName(string)
  • func (*NoopSpan) SetPeer(string)
  • func (*NoopSpan) SetSpanLayer(v3.SpanLayer)
  • func (*NoopSpan) Tag(Tag, string)
• type RandomSampler
  • func NewRandomSampler(samplingRate float64) *RandomSampler
  • func (s *RandomSampler) IsSampled(operation string) bool
• type ReportedSpan
• type Reporter
• type Sampler
• type SegmentContext
• type SkySpanType
• type Span
• type SpanOption
  • func WithContext(sc *propagation.SpanContext) SpanOption
  • func WithOperationName(operationName string) SpanOption
  • func WithSpanType(spanType SkySpanType) SpanOption
• type Tag
• type Tracer
  • func NewTracer(service string, opts ...TracerOption) (tracer *Tracer, err error)
  • func (t *Tracer) CreateEntrySpan(ctx context.Context, operationName string, extractor propagation.Extractor) (s Span, nCtx context.Context, err error)
  • func (t *Tracer) CreateExitSpan(ctx context.Context, operationName string, peer string, ...) (Span, error)
  • func (t *Tracer) CreateLocalSpan(ctx context.Context, opts ...SpanOption) (s Span, c context.Context, err error)
• type TracerOption
  • func WithInstance(instance string) TracerOption
  • func WithReporter(reporter Reporter) TracerOption
  • func WithSampler(samplingRate float64) TracerOption

Examples

• NewTracer

Constants

const (
	EmptyTraceID = "N/A"
	NoopTraceID  = "[Ignored Trace]"
)

const (
	ComponentIDHttpServer int32 = 49
)

Functions

func TraceID

func TraceID(ctx context.Context) string

Types

type ConstSampler

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

func NewConstSampler

func NewConstSampler(sample bool) *ConstSampler

NewConstSampler creates a ConstSampler.

func (*ConstSampler) IsSampled

func (s *ConstSampler) IsSampled(operation string) bool

IsSampled implements IsSampled() of Sampler.

type NoopSpan

type NoopSpan struct {
}

func (*NoopSpan) End

func (*NoopSpan) End()

func (*NoopSpan) Error

func (*NoopSpan) Error(time.Time, ...string)

func (*NoopSpan) GetOperationName

func (*NoopSpan) GetOperationName() string

func (*NoopSpan) IsEntry

func (*NoopSpan) IsEntry() bool

func (*NoopSpan) IsExit

func (*NoopSpan) IsExit() bool

func (*NoopSpan) Log

func (*NoopSpan) Log(time.Time, ...string)

func (*NoopSpan) SetComponent

func (*NoopSpan) SetComponent(int32)

func (*NoopSpan) SetOperationName

func (*NoopSpan) SetOperationName(string)

func (*NoopSpan) SetPeer

func (*NoopSpan) SetPeer(string)

func (*NoopSpan) SetSpanLayer

func (*NoopSpan) SetSpanLayer(v3.SpanLayer)

func (*NoopSpan) Tag

func (*NoopSpan) Tag(Tag, string)

type RandomSampler

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

func NewRandomSampler

func NewRandomSampler(samplingRate float64) *RandomSampler

func (*RandomSampler) IsSampled

func (s *RandomSampler) IsSampled(operation string) bool

IsSampled implements IsSampled() of Sampler.

type ReportedSpan

type ReportedSpan interface {
	Context() *SegmentContext
	Refs() []*propagation.SpanContext
	StartTime() int64
	EndTime() int64
	OperationName() string
	Peer() string
	SpanType() v3.SkySpanType
	SpanLayer() v3.SpanLayer
	IsError() bool
	Tags() []*common.KeyStringValuePair
	Logs() []*v3.Log
	ComponentID() int32
}

ReportedSpan is accessed by Reporter to load reported data

type Reporter

type Reporter interface {
	Boot(service string, serviceInstance string)
	Send(spans []ReportedSpan)
	Close()
}

Reporter is a data transit specification

type Sampler

type Sampler interface {
	IsSampled(operation string) (sampled bool)
}

type SegmentContext

type SegmentContext struct {
	TraceID         string
	SegmentID       string
	SpanID          int32
	ParentSpanID    int32
	ParentSegmentID string

	FirstSpan Span `json:"-"`
	// contains filtered or unexported fields
}

SegmentContext is the context in a segment

type SkySpanType

type SkySpanType int32

SpanType is used to identify entry, exit and local

const (
	// SpanTypeEntry is a entry span, eg http server
	SpanTypeEntry SkySpanType = 0
	// SpanTypeExit is a exit span, eg http client
	SpanTypeExit SkySpanType = 1
	// SpanTypeLocal is a local span, eg local method invoke
	SpanTypeLocal SkySpanType = 2
)

type Span

type Span interface {
	SetOperationName(string)
	GetOperationName() string
	SetPeer(string)
	SetSpanLayer(v3.SpanLayer)
	SetComponent(int32)
	Tag(Tag, string)
	Log(time.Time, ...string)
	Error(time.Time, ...string)
	End()
	IsEntry() bool
	IsExit() bool
}

Span interface as common span specification

type SpanOption

type SpanOption func(s *defaultSpan)

SpanOption allows for functional options to adjust behaviour of a Span to be created by CreateLocalSpan

func WithContext

func WithContext(sc *propagation.SpanContext) SpanOption

WithContext setup trace sc from propagation

func WithOperationName

func WithOperationName(operationName string) SpanOption

WithOperationName setup span OperationName of a span

func WithSpanType

func WithSpanType(spanType SkySpanType) SpanOption

WithSpanType setup span type of a span

type Tag

type Tag string

Tag are supported by sky-walking engine. As default, all Tags will be stored, but these ones have particular meanings.

const (
	TagURL             Tag = "url"
	TagStatusCode      Tag = "status_code"
	TagHTTPMethod      Tag = "http.method"
	TagDBType          Tag = "db.type"
	TagDBInstance      Tag = "db.instance"
	TagDBStatement     Tag = "db.statement"
	TagDBBindVariables Tag = "db.bind_vars"
	TagMQQueue         Tag = "mq.queue"
	TagMQBroker        Tag = "mq.broker"
	TagMQTopic         Tag = "mq.topic"
)

type Tracer

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

Tracer is go2sky tracer implementation.

func NewTracer

func NewTracer(service string, opts ...TracerOption) (tracer *Tracer, err error)

NewTracer return a new go2sky Tracer

Example

package main

import (
	"context"
	"log"
	"time"

	"github.com/hammercui/go2sky"
	"github.com/hammercui/go2sky/reporter"
)

func main() {
	// Use gRPC reporter for production
	r, err := reporter.NewLogReporter()
	if err != nil {
		log.Fatalf("new reporter error %v \n", err)
	}
	defer r.Close()
	tracer, err := go2sky.NewTracer("example", go2sky.WithReporter(r))
	if err != nil {
		log.Fatalf("create tracer error %v \n", err)
	}
	// This for test
	span, ctx, err := tracer.CreateLocalSpan(context.Background())
	if err != nil {
		log.Fatalf("create new local span error %v \n", err)
	}
	span.SetOperationName("invoke data")
	span.Tag("kind", "outer")
	time.Sleep(time.Second)
	subSpan, _, err := tracer.CreateLocalSpan(ctx)
	if err != nil {
		log.Fatalf("create new sub local span error %v \n", err)
	}
	subSpan.SetOperationName("invoke inner")
	subSpan.Log(time.Now(), "inner", "this is right")
	time.Sleep(time.Second)
	subSpan.End()
	time.Sleep(500 * time.Millisecond)
	span.End()
	time.Sleep(time.Second)
}

func (*Tracer) CreateEntrySpan

func (t *Tracer) CreateEntrySpan(ctx context.Context, operationName string, extractor propagation.Extractor) (s Span, nCtx context.Context, err error)

CreateEntrySpan creates and starts an entry span for incoming request

func (*Tracer) CreateExitSpan

func (t *Tracer) CreateExitSpan(ctx context.Context, operationName string, peer string, injector propagation.Injector) (Span, error)

CreateExitSpan creates and starts an exit span for client

func (*Tracer) CreateLocalSpan

func (t *Tracer) CreateLocalSpan(ctx context.Context, opts ...SpanOption) (s Span, c context.Context, err error)

CreateLocalSpan creates and starts a span for local usage

type TracerOption

type TracerOption func(t *Tracer)

TracerOption allows for functional options to adjust behaviour of a Tracer to be created by NewTracer

func WithInstance

func WithInstance(instance string) TracerOption

WithInstance setup instance identify

func WithReporter

func WithReporter(reporter Reporter) TracerOption

WithReporter setup report pipeline for tracer

func WithSampler

func WithSampler(samplingRate float64) TracerOption

WithSampler setup sampler