tracer

package
v0.0.0-...-9cf347b Latest Latest
Warning

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

 Go to latest Published: Jul 7, 2024 License: BSD-3-Clause Imports: 4 Imported by: 12

README

Disclaimer

This API is experimental and has no stability guarantees.

Example

package tracer_test

import (
	"context"

	"github.com/facebookincubator/go-belt"
	"github.com/facebookincubator/go-belt/beltctx"
	"github.com/facebookincubator/go-belt/tool/experimental/tracer"
	"github.com/facebookincubator/go-belt/tool/experimental/tracer/implementation/logger"
	"github.com/facebookincubator/go-belt/tool/experimental/tracer/implementation/zipkin"
)

func Example() {
	// easy to use:
	t := logger.Default()
	someFunction(1, t)

	// implementation agnostic:
	t = zipkin.Default()
	someFunction(2, t)

	// one may still reuse all the features of the backend Tracer:
	t.(*zipkin.TracerImpl).ZipkinTracer.SetNoop(true)

	// use go-belt to manage the Tracer
	obs := belt.New()
	obs = tracer.BeltWithTracer(obs, t)
	someBeltyFunction(3, obs)

	// use context to manage the Tracer
	ctx := context.Background()
	ctx = tracer.CtxWithTracer(ctx, t)
	someContextyFunction(ctx, 4)

	// use a singletony Tracer:
	tracer.Default = func() tracer.Tracer {
		return t
	}
	yetOneMoreFunction(5)
}

func someFunction(arg int, t tracer.Tracer) {
	// experience close to logrus/zap:
	t = tracer.WithField(t, "arg", arg)
	anotherFunction(t)
}

func anotherFunction(t tracer.Tracer) {
	span := t.Start("hello", nil)
	defer span.Finish()
	// ..do something long here..
	oneMoreFunction(t, span)
}

func oneMoreFunction(t tracer.Tracer, parentSpan tracer.Span) {
	span := t.Start("child", parentSpan)
	defer span.Finish()
	// ..do something meaningful here..
}

func someBeltyFunction(arg int, obs *belt.Belt) {
	obs = obs.WithField("arg", arg)
	anotherBeltyFunction(obs)
}

func anotherBeltyFunction(obs *belt.Belt) {
	span, obs := tracer.StartChildSpanFromBelt(obs, "hello")
	defer span.Finish()
	// ..do something long here..
	oneMoreBeltyFunction(obs)
}

func oneMoreBeltyFunction(obs *belt.Belt) {
	span, obs := tracer.StartChildSpanFromBelt(obs, "child")
	defer span.Finish()
	// ..do something meaningful here..
	_ = obs
}

func someContextyFunction(ctx context.Context, arg int) {
	ctx = beltctx.WithField(ctx, "arg", arg)
	anotherContextyFunction(ctx)
}

func anotherContextyFunction(ctx context.Context) {
	span, ctx := tracer.StartChildSpanFromCtx(ctx, "hello")
	defer span.Finish()
	// ..do something long here..
	oneMoreContextyFunction(ctx)
}

func oneMoreContextyFunction(ctx context.Context) {
	span, ctx := tracer.StartChildSpanFromCtx(ctx, "child")
	defer span.Finish()
	// ..do something meaningful here..
	_ = ctx
}

func yetOneMoreFunction(arg int) {
	t := tracer.Default()
	t = tracer.WithField(t, "arg", arg)
	span := t.Start("hello", nil)
	defer span.Finish()
}

Interface

type Tracer interface {
	belt.Tool

	// Start creates a new Span, given its name, parent and options.
	Start(name string, parent Span, options ...SpanOption) Span

	// StartWithBelt creates a new root Span, given Belt, name and options.
	//
	// The returned Belt is a derivative of the provided one, with the Span added.
	StartWithBelt(belt *belt.Belt, name string, options ...SpanOption) (Span, *belt.Belt)

	// StartChildWithBelt creates a new child Span, given Belt, name and options.
	// The parent is extracted from the Belt. If one is not set in there then it is
	// an equivalent of StartWithBelt (a nil parent is used).
	//
	// The returned Belt is a derivative of the provided one, with the Span added.
	StartChildWithBelt(belt *belt.Belt, name string, options ...SpanOption) (Span, *belt.Belt)

	// StartWithCtx creates a new root Span, given Context, name and options.
	//
	// The returned Context is a derivative of the provided one, with the Span added.
	// Some implementations also injects a span structure with a specific key to the context.
	StartWithCtx(ctx context.Context, name string, options ...SpanOption) (Span, context.Context)

	// StartChildWithCtx creates a new child Span, given Context, name and options.
	// The parent is extracted from the Belt from the Context.
	// If one is not set in there then it is an equivalent of StartWithCtx (a nil parent is used).
	//
	// The returned Context is a derivative of the provided one, with the Span added.
	// Some implementations also injects a span structure with a specific key to the context.
	StartChildWithCtx(ctx context.Context, name string, options ...SpanOption) (Span, context.Context)

	// WithPreHooks returns a Tracer which includes/appends pre-hooks from the arguments.
	//
	// PreHook is the same as "Hook", but executed on early stages of building a Span
	// (before heavy computations).
	//
	// Special case: to reset hooks use `WithPreHooks()` (without any arguments).
	WithPreHooks(...Hook) Tracer

	// WithHooks returns a Tracer which includes/appends hooks from the arguments.
	//
	// See also description of "Hook".
	//
	// Special case: to reset hooks use `WithHooks()` (without any arguments).
	WithHooks(...Hook) Tracer

	// Flush forces to flush all buffers.
	Flush()
}

Documentation

Index

Constants

View Source 
const (
	RoleClient = SpanOptionRole("client")
	RoleServer = SpanOptionRole("server")
)

Variables

View Source 
var ArtifactIDSpan = artifactIDSpan{}

ArtifactIDSpan is the belt.ArtifactID for a Span.

The idea is that Span-s may have children and for convenience it should be possible to pass-through the parents through a context/Belt. So we use the Artifacts registry of the Belt to store the current Span, which could become a parent.

View Source 
var Default = func() Tracer {
	return noopTracer{}
}

Default is the (overridable) function which returns returns the default tracer.

It is used by FromBelt and FromCtx functions if a Tracer is not set in the Belt.

View Source 
var ToolID = toolID{}

ToolID is the tool.ID used for Tracer.

Functions

func BeltWithSpan 

func BeltWithSpan(belt *belt.Belt, span Span) *belt.Belt

BeltWithSpan returns a Belt derivative with the specified Span.

func BeltWithTracer 

func BeltWithTracer(belt *belt.Belt, tracer Tracer) *belt.Belt

BeltWithTracer returns a Belt derivative with the specified Tracer.

func CtxWithSpan 

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

CtxWithSpan returns a context derivative/clone with the specified Span.

func CtxWithTracer 

func CtxWithTracer(ctx context.Context, tracer Tracer) context.Context

CtxWithTracer returns a context derivative/clone with the specified Tracer.

func IsNoopSpan 

func IsNoopSpan(span Span) bool

IsNoopSpan returns true if the given Span is a NoopSpan.

Types

type Hook 

type Hook interface {
	// ProcessSpan is the main method of a Hook. It is executed before sending
	// a Span (to some backend). If it returns false then any further processing
	// and sending of the Span is cancelled.
	ProcessSpan(Span) bool

	// Flush just gracefully empties all the queues (if there are any).
	Flush()
}

Hook is executed right before sending a Span (to some backend).

type Hooks 

type Hooks []Hook

Hooks is a collection of multiple Hook-s.

func (Hooks) Flush 

func (s Hooks) Flush()

Flush implements Hook.

func (Hooks) ProcessSpan 

func (s Hooks) ProcessSpan(span Span) bool

ProcessSpan implements Hook.

type NoopSpan 

type NoopSpan struct {
	ParentValue  Span
	NameValue    string
	StartTSValue time.Time
}

NoopSpan is a no-op implementation of a Span. Supposed to be used for sampled out spans.

func NewNoopSpan 

func NewNoopSpan(name string, parent Span, now time.Time) *NoopSpan

NewNoopSpan returns a new instance of a NoopSpan.

func (*NoopSpan) Annotate 

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

Annotate implements Span.

func (*NoopSpan) Fields 

func (*NoopSpan) Fields() field.AbstractFields

Fields implements Span.

func (*NoopSpan) Finish 

func (*NoopSpan) Finish()

Finish implements Span.

func (*NoopSpan) FinishWithDuration 

func (*NoopSpan) FinishWithDuration(time.Duration)

FinishWithDuration implements Span.

func (*NoopSpan) Flush 

func (*NoopSpan) Flush()

Flush implements Span.

func (*NoopSpan) ID 

func (*NoopSpan) ID() any

ID implements Span.

func (*NoopSpan) Name 

func (s *NoopSpan) Name() string

Name implements Span.

func (*NoopSpan) Parent 

func (s *NoopSpan) Parent() Span

Parent implements Span.

func (*NoopSpan) SetField 

func (*NoopSpan) SetField(field.Key, field.Value)

SetField implements Span.

func (*NoopSpan) SetFields 

func (*NoopSpan) SetFields(field.AbstractFields)

SetFields implements Span.

func (*NoopSpan) SetName 

func (s *NoopSpan) SetName(name string)

SetName implements Span.

func (*NoopSpan) StartTS 

func (s *NoopSpan) StartTS() time.Time

StartTS implements Span.

func (*NoopSpan) TraceIDs 

func (*NoopSpan) TraceIDs() belt.TraceIDs

TraceIDs implements Span.

type Span 

type Span interface {
	// ID is the ID for the Span. It may have different types, depending
	// on specific implementation of the Tracer.
	//
	// Not all tracing systems may support that.
	ID() any

	// TraceIDs are the set if unique IDs associated with the current context.
	//
	// See the description of belt.TraceIDs.
	//
	// Not all tracing systems may support that.
	TraceIDs() belt.TraceIDs

	// Name is the name of the Span. Usually it explains what happens within
	// this span.
	Name() string

	// StartTS returns the timestamp of the beginning of the Span.
	//
	// Can be zero value if unknown. For example it could
	// happen due sampling, or it could just be not supported
	// byt a specific implementation.
	StartTS() time.Time

	// Fields is the set of structured data attached to the Span.
	Fields() field.AbstractFields

	// Parent is the parent Span. If there is no parent then an untyped nil is returned.
	Parent() Span

	// SetName sets the Name (see the description of method Name).
	SetName(string)

	// Annotate adds an event with the specified timestamp and description to the Span.
	//
	// Not all tracing systems may support that.
	Annotate(ts time.Time, description string)

	// SetField sets a structured field in the Span.
	//
	// Not all tracing systems may support that.
	SetField(field.Key, field.Value)

	// SetField set multiple structured fields at once in the Span.
	//
	// Not all tracing systems may support that.
	SetFields(field.AbstractFields)

	// Finish closes the Span using time.Now() as the ending timestamp and sends it.
	Finish()

	// FinishWithDuration closes the Span using startTS+duration as the ending timestamp and sends it.
	FinishWithDuration(duration time.Duration)

	// Flush forces to immediatelly empty all the buffers (send if something was delayed and so on).
	Flush()
}

Span is a single time interval.

func SpanFromBelt 

func SpanFromBelt(belt *belt.Belt) Span

SpanFromBelt extracts a Span from a Belt (for example, previously derived using StartChildSpanFromBelt, StartChildSpanFromCtx or BeltWithSpan).

func SpanFromCtx 

func SpanFromCtx(ctx context.Context) Span

SpanFromCtx returns the current span, given a context. Returns a NoopSpan if one is not set.

func StartChildSpanFromBelt 

func StartChildSpanFromBelt(belt *belt.Belt, name string, options ...SpanOption) (Span, *belt.Belt)

StartChildSpanFromBelt returns a child span given an Belt. The parent Span is extracted from the Belt. If one is not set, then a `nil` parent is set in the new Span.

The Span and an Belt which includes this Span are returned.

func StartChildSpanFromCtx 

func StartChildSpanFromCtx(ctx context.Context, name string, options ...SpanOption) (Span, context.Context)

StartChildSpanFromCtx creates a child span, given a context. The parent span is extracted from the Belt of the context. If one is not set, then the function returns a new root Span (a Span without a parent).

func StartSpanFromBelt 

func StartSpanFromBelt(belt *belt.Belt, name string, options ...SpanOption) (Span, *belt.Belt)

StartSpanFromBelt returns a span (without a parent) given an Belt.

The Span and an Belt which includes this Span are returned.

func StartSpanFromCtx 

func StartSpanFromCtx(ctx context.Context, name string, options ...SpanOption) (Span, context.Context)

StartSpanFromCtx creates a new (root) span, given a context.

type SpanOption 

type SpanOption interface {
	// contains filtered or unexported methods
}

SpanOption is an option which modifies a Span.

If some option is not supported by a specific implementation of the Tracer, then it is just ignored.

type SpanOptionAddFields 

type SpanOptionAddFields field.Fields

SpanOptionAddFields adds more structured fields to the Span.

Note: some distributing tracers may not support logging this data.

type SpanOptionResetFields 

type SpanOptionResetFields struct{}

SpanOptionResetFields resets structured fields within the Span to an empty set.

type SpanOptionRole 

type SpanOptionRole string

SpanOptionRole defines who is the issuer of this specific Span, which might be useful in some implementations of distributed tracing.

type SpanOptionStart 

type SpanOptionStart time.Time

SpanOptionStart overrides the starting timestamp of the Span.

type Spans 

type Spans []Span

Spans is a collection of Span-s.

func (Spans) Earliest 

func (s Spans) Earliest() Span

Earliest returns the Span with the lowest start timestamp.

type Tracer 

type Tracer interface {
	belt.Tool

	// Start creates a new Span, given its name, parent and options.
	Start(name string, parent Span, options ...SpanOption) Span

	// StartWithBelt creates a new root Span, given Belt, name and options.
	//
	// The returned Belt is a derivative of the provided one, with the Span added.
	StartWithBelt(belt *belt.Belt, name string, options ...SpanOption) (Span, *belt.Belt)

	// StartChildWithBelt creates a new child Span, given Belt, name and options.
	// The parent is extracted from the Belt. If one is not set in there then it is
	// an equivalent of StartWithBelt (a nil parent is used).
	//
	// The returned Belt is a derivative of the provided one, with the Span added.
	StartChildWithBelt(belt *belt.Belt, name string, options ...SpanOption) (Span, *belt.Belt)

	// StartWithCtx creates a new root Span, given Context, name and options.
	//
	// The returned Context is a derivative of the provided one, with the Span added.
	// Some implementations also injects a span structure with a specific key to the context.
	StartWithCtx(ctx context.Context, name string, options ...SpanOption) (Span, context.Context)

	// StartChildWithCtx creates a new child Span, given Context, name and options.
	// The parent is extracted from the Belt from the Context.
	// If one is not set in there then it is an equivalent of StartWithCtx (a nil parent is used).
	//
	// The returned Context is a derivative of the provided one, with the Span added.
	// Some implementations also injects a span structure with a specific key to the context.
	StartChildWithCtx(ctx context.Context, name string, options ...SpanOption) (Span, context.Context)

	// WithPreHooks returns a Tracer which includes/appends pre-hooks from the arguments.
	//
	// PreHook is the same as "Hook", but executed on early stages of building a Span
	// (before heavy computations).
	//
	// Special case: to reset hooks use `WithPreHooks()` (without any arguments).
	WithPreHooks(...Hook) Tracer

	// WithHooks returns a Tracer which includes/appends hooks from the arguments.
	//
	// See also description of "Hook".
	//
	// Special case: to reset hooks use `WithHooks()` (without any arguments).
	WithHooks(...Hook) Tracer
}

Tracer is a generic abstract distributed tracing system client.

func FromBelt 

func FromBelt(belt *belt.Belt) Tracer

FromBelt returns a Tracer given a Belt.

func FromCtx 

func FromCtx(ctx context.Context) Tracer

FromCtx returns a Tracer, given a context.

func WithField 

func WithField(t Tracer, key field.Key, value field.Value) Tracer

WithField adds a Tracer derivative with the field added.

Source Files

View all Source files

Directories

Path Synopsis
hooks
sampler
implementation
logger
zipkin

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.