go2sky

package module
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 28, 2022 License: Apache-2.0 Imports: 15 Imported by: 156

README

GO2Sky

Build Coverage GoDoc

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))

In some scenarios, we may need a filter to filter segments that do not need to be submitted, for example, to reduce the load of gRPC reporting, or only track the request of error.

r, err := reporter.NewGRPCReporter("oap-skywalking:11800", reporter.WithReportStrategy(func(s *v3.SegmentObject) bool {
	var isReport bool
	for _, span := s.GetSpans() {
		if span.GetIsError() {
			isReport = true
			break
		}
	}
	
	return isReport
}))

You can also create tracer with sampling rate. It supports decimals between 0-1 (two decimal places), representing the sampling percentage of trace.

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

Also could customize correlation context config.

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

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())

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)

Get correlation

Get custom data from tracing context.

value := go2sky.GetCorrelation(ctx, key)

Put correlation

Put custom data to tracing context.

success := go2sky.PutCorrelation(ctx, key, value)

End span

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

subSpan.End()
span.End()

Global Tracer

Set and get global Tracer

// new tracer
tr, err := go2sky.NewTracer("example")

// registers `tracer` as the global Tracer
go2sky.SetGlobalTracer(tr)

// returns the registered global Tracer
// if none is registered then an instance of `nil` is returned
tracer := go2sky.GetGlobalTracer()

Get Active Span

Get the activeSpan in the Context.

go2sky.ActiveSpan(ctx)

With Span

Save the activeSpan to Context

go2sky.WithSpan(ctx, activeSpan)

Get Global Service Name

Get the ServiceName of the activeSpan in the Context.

go2sky.ServiceName(ctx)

Get Global Service Instance Name

Get the ServiceInstanceName of the activeSpan in the Context.

go2sky.ServiceInstanceName(ctx)

Get Global TraceID

Get the TraceID of the activeSpan in the Context.

go2sky.TraceID(ctx)

Get Global TraceSegmentID

Get the TraceSegmentID of the activeSpan in the Context.

go2sky.TraceSegmentID(ctx)

Get Global SpanID

Get the SpanID of the activeSpan in the Context.

go2sky.SpanID(ctx)

Periodically Report

Go2sky agent reports the segments periodically. It would not wait for all finished segments reported when the service exits.

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(key string) (string, error) {
		return r.Header.Get(key), nil
})

// Some operation
...

// Inject context into HTTP request header `sw8`
span, err := tracer.CreateExitSpan(req.Context(), "/service/validate", "tomcat-service:8080", func(key, value string) error {
		req.Header.Set(key, value)
		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.

Log x Trace context

Inject trace context into the log text. SkyWalking LAL(log analysis language) engine could extract the context from the text and correlate trace and logs.

// Get trace context data
import go2skylog "github.com/SkyAPM/go2sky/log"
logContext = go2skylog.FromContext(ctx)

// Build context data string
// Inject context string into log
// Context format string: [$serviceName,$instanceName,$traceId,$traceSegmentId,$spanId]
contextString := logContext.String()

Plugins

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

Supported Environment Variables

Below is the full list of supported environment variables you can set to customize the agent behavior, please read the descriptions for what they can achieve.

Environment Variable Description Default
SW_AGENT_NAME The name of the Go service unset
SW_AGENT_LAYER Instance belong layer name which define in the backend unset
SW_AGENT_INSTANCE_NAME The name of the Go service instance Randomly generated
SW_AGENT_SAMPLE Sample rate, 1 setting it to 1 means full sampling 1
SW_AGENT_COLLECTOR_BACKEND_SERVICES The backend OAP server address unset
SW_AGENT_AUTHENTICATION The authentication token to verify that the agent is trusted by the backend OAP, as for how to configure the backend, refer to the yaml. unset
SW_AGENT_COLLECTOR_HEARTBEAT_PERIOD Agent heartbeat report period. Unit, second 20
SW_AGENT_COLLECTOR_GET_AGENT_DYNAMIC_CONFIG_INTERVAL Sniffer get agent dynamic config interval. Unit, second 20
SW_AGENT_COLLECTOR_MAX_SEND_QUEUE_SIZE Send span queue buffer length 30000
SW_AGENT_PROCESS_STATUS_HOOK_ENABLE Enable the Process Status Hook feature false
SW_AGENT_PROCESS_LABELS The labels of the process, multiple labels split by "," unset

CDS - Configuration Discovery Service

Configuration Discovery Service provides the dynamic configuration for the agent, defined in gRPC and stored in the backend.

Available key(s) and value(s) in Golang Agent.

Golang agent supports the following dynamic configurations.

Config Key Value Description Value Format Example
agent.sample_rate The percentage of trace when sampling. It's [0, 1], Same with WithSampler parameter. 0.1

Process Status Hook

This feature is used in cooperation with the skywalking-rover project.

When go2sky keeps alive with the backend, it would write a metadata file to the local (temporary directory) at the same time, which describes the information of the current process. The rover side scans all processes, find out which process contains this metadata file. Finally, the rover could collect, profiling, with this process.

Metadata File

The metadata file use to save metadata with current process, it save in: {TMPDIR}/apache_skywalking/process/{pid}/metadata.properties.

Also, when the go2sky keep alive with backend, modify and open time of the metadata file would be updated.

Key Type Description
layer string this process layer.
service_name string this process service name.
instance_name string this process instance name.
process_name string this process process name, it's same with the instance name.
properties json the properties in instance, the process labels also in the properties value.
labels string the process labels, multiple labels split by ",".
language string current process language, which is golang.

Please read the official documentation of rover to get more information.

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

Examples

Constants

View Source 
const (
	EmptyServiceName         = ""
	EmptyServiceInstanceName = ""
	EmptyTraceID             = "N/A"
	EmptyTraceSegmentID      = "N/A"
	EmptySpanID              = -1
)
View Source 
const (
	ComponentIDHttpServer int32 = 49
)

Variables

This section is empty.

Functions

func GetCorrelation added in v1.0.0 

func GetCorrelation(ctx context.Context, key string) string

func PutCorrelation added in v1.0.0 

func PutCorrelation(ctx context.Context, key, value string) bool

func ServiceInstanceName added in v1.1.0 

func ServiceInstanceName(ctx context.Context) string

func ServiceName added in v1.1.0 

func ServiceName(ctx context.Context) string

func SetGlobalTracer added in v1.4.0 

func SetGlobalTracer(tracer *Tracer)

SetGlobalTracer registers `tracer` as the global Tracer.

func SpanID added in v1.1.0 

func SpanID(ctx context.Context) int32

func TraceID added in v0.3.0 

func TraceID(ctx context.Context) string

func TraceSegmentID added in v1.1.0 

func TraceSegmentID(ctx context.Context) string

func WithSpan added in v1.4.1 

func WithSpan(ctx context.Context, span Span) context.Context

Types

type AgentConfigChangeWatcher added in v1.1.0 

type AgentConfigChangeWatcher interface {
	Key() string
	Notify(eventType AgentConfigEventType, newValue string)
	Value() string
}

type AgentConfigEventType added in v1.1.0 

type AgentConfigEventType int32
const (
	MODIFY AgentConfigEventType = iota
	DELETED
)

type ConfigDiscoveryService added in v1.1.0 

type ConfigDiscoveryService struct {
	UUID string
	// contains filtered or unexported fields
}

func NewConfigDiscoveryService added in v1.1.0 

func NewConfigDiscoveryService() *ConfigDiscoveryService

func (*ConfigDiscoveryService) BindWatchers added in v1.1.0 

func (s *ConfigDiscoveryService) BindWatchers(watchers []AgentConfigChangeWatcher)

func (*ConfigDiscoveryService) HandleCommand added in v1.1.0 

func (s *ConfigDiscoveryService) HandleCommand(command *common.Command)

type ConstSampler added in v0.6.0 

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

func NewConstSampler added in v0.6.0 

func NewConstSampler(sample bool) *ConstSampler

NewConstSampler creates a ConstSampler.

func (*ConstSampler) IsSampled added in v0.6.0 

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

IsSampled implements IsSampled() of Sampler.

type CorrelationConfig added in v1.0.0 

type CorrelationConfig struct {
	MaxKeyCount  int
	MaxValueSize int
}

type DynamicSampler added in v1.1.0 

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

func NewDynamicSampler added in v1.1.0 

func NewDynamicSampler(samplingRate float64, tracer *Tracer) *DynamicSampler

func (*DynamicSampler) IsSampled added in v1.1.0 

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

IsSampled implements IsSampled() of Sampler.

func (*DynamicSampler) Key added in v1.1.0 

func (s *DynamicSampler) Key() string

func (*DynamicSampler) Notify added in v1.1.0 

func (s *DynamicSampler) Notify(eventType AgentConfigEventType, newValue string)

func (*DynamicSampler) Value added in v1.1.0 

func (s *DynamicSampler) Value() string

type NoopSpan 

type NoopSpan struct {
}

func (*NoopSpan) End 

func (*NoopSpan) End()

func (*NoopSpan) Error 

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

func (*NoopSpan) GetOperationName added in v0.3.0 

func (*NoopSpan) GetOperationName() string

func (*NoopSpan) IsEntry added in v0.3.0 

func (*NoopSpan) IsEntry() bool

func (*NoopSpan) IsExit added in v0.3.0 

func (*NoopSpan) IsExit() bool

func (*NoopSpan) IsValid added in v1.4.0 

func (*NoopSpan) IsValid() 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(agentv3.SpanLayer)

func (*NoopSpan) Tag 

func (*NoopSpan) Tag(Tag, string)

type RandomSampler added in v0.6.0 

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

RandomSampler Use sync.Pool to implement concurrent-safe for randomizer.

func NewRandomSampler added in v0.6.0 

func NewRandomSampler(samplingRate float64) *RandomSampler

func (*RandomSampler) IsSampled added in v0.6.0 

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() agentv3.SpanType
	SpanLayer() agentv3.SpanLayer
	IsError() bool
	Tags() []*commonv3.KeyStringValuePair
	Logs() []*agentv3.Log
	ComponentID() int32
}

ReportedSpan is accessed by Reporter to load reported data

type Reporter 

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

Reporter is a data transit specification

type Sampler added in v0.6.0 

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:"-"`
	CorrelationContext map[string]string
	// contains filtered or unexported fields
}

SegmentContext is the context in a segment

type Span 

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

Span interface as commonv3 span specification

func ActiveSpan added in v1.4.0 

func ActiveSpan(ctx context.Context) Span

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 added in v0.6.0 

func WithOperationName(operationName string) SpanOption

WithOperationName setup span OperationName of a span

func WithSpanType 

func WithSpanType(spanType SpanType) SpanOption

WithSpanType setup span type of a span

type SpanType 

type SpanType int32

SpanType is used to identify entry, exit and local 

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

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"
	TagDBSqlParameters Tag = "db.sql.parameters"
	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 GetGlobalTracer added in v1.4.0 

func GetGlobalTracer() *Tracer

GetGlobalTracer returns the registered global Tracer. If none is registered then an instance of `nil` is returned.

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/SkyAPM/go2sky"
	"github.com/SkyAPM/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) (s Span, err error)

CreateExitSpan creates and starts an exit span for client

func (*Tracer) CreateExitSpanWithContext added in v1.2.0 

func (t *Tracer) CreateExitSpanWithContext(ctx context.Context, operationName string, peer string,
	injector propagation.Injector) (s Span, nCtx context.Context, err error)

CreateExitSpanWithContext creates and starts an exit span for client with context

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 WithCorrelation added in v1.0.0 

func WithCorrelation(keyCount, valueSize int) TracerOption

func WithCustomSampler added in v1.0.0 

func WithCustomSampler(sampler Sampler) TracerOption

WithCustomSampler setup custom sampler

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 added in v0.6.0 

func WithSampler(samplingRate float64) TracerOption

WithSampler setup sampler

Source Files

View all Source files

Directories

Path Synopsis
internal
idgen
tool
Package log help to build trace context data into log plugins.
 Package log help to build trace context data into log plugins.
plugins
http
Package http contains several client/server http plugin which can be used for integration with net/http.
 Package http contains several client/server http plugin which can be used for integration with net/http.
http/test/client command
http/test/server command
Package propagation holds the required function signatures for Injection and Extraction.
 Package propagation holds the required function signatures for Injection and Extraction.
Package reporter holds reporters contain official reporter implementations.
 Package reporter holds reporters contain official reporter implementations.
grpc/language-agent/mock_trace
Package mock_v3 is a generated GoMock package.
 Package mock_v3 is a generated GoMock package.
grpc/management/mock_management
Package mock_v3 is a generated GoMock package.
 Package mock_v3 is a generated GoMock package.
test
e2e/cases/environment-variable/server command
e2e/example-server command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.