tracing

package
v0.0.0-...-3e52749 Latest Latest
Warning

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

 Go to latest Published: Mar 26, 2022 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// rpc injection keys
	SimEventKey = "cc-simEvent"
	SpanIds     = "cc-spanIds"
	ChildId     = "cc-childId"

	// rpc infra source key values
	SourceIn        = "in"
	SourceOut       = "out"
	SourceAssumedIn = "assumedIn"
)
View Source 
const (
	ImpactCreate = "C"
	ImpactRead   = "R"
	ImpactModify = "W"
	ImpactDelete = "D"
	ImpactUse    = "E"
)

impact data is stored in a KeyValue pair under the ImpactKey. KV pairs have limited types that they support, so the impact targets are prefixed with the type of impact. This leaves the value as a string that can be decoded later in order to properly display the impact.

Variables

View Source 
var NullParentId = uuid.Nil.String()

NullParentId represents a non-existent parent ID, and hence marks a span with that ID as a root span.

View Source 
var NullSpanContext = SpanContext{
	TraceId: uuid.Nil,
	Id:      uuid.Nil,
}

NullSpanContext is the value used whenever a SpanContext is requested for a closed or non-existent SpanContext.

Functions

func AddImpact 

func AddImpact(ctx context.Context, level string, module string)

AddImpact adds an impact claim to the current span. It does not optimize out any duplicates -- all of those are retained.

func ContextWithSpan 

func ContextWithSpan(ctx context.Context, span SpanEx) context.Context

ContextWithSpan creates a new context with a current span set to the passed span.

func Debug 

func Debug(ctx context.Context, a ...interface{})

Debug posts a debug-level trace event

func Error 

func Error(ctx context.Context, a ...interface{}) error

Error posts an error trace event

func Fatal 

func Fatal(ctx context.Context, a ...interface{})

Fatal traces the error, and then terminates the process.

func Info 

func Info(ctx context.Context, a ...interface{})

Info posts an informational trace event

func InitializeFilters 

func InitializeFilters(showInternal bool)

func InternalData 

func InternalData(a ...interface{}) string

InternalData returns either the formatted string, if internal data is to be shown in the traces, or the empty string, if not.

func MethodName 

func MethodName(skip int) string

MethodName returns the caller's method name, without the leading directory paths.

func SetGlobalTracer 

func SetGlobalTracer(t *Tracer)

SetGlobalTracer is a function that replaces the global trace provider instance. It requires that the caller ensure proper synchronization.

func StackTrace 

func StackTrace(skip int) string

StackTrace produces a formatted call stack, in the form of filename and line number. A newline splits each entry.

func UpdateSpanName 

func UpdateSpanName(ctx context.Context, a ...interface{})

UpdateSpanName replaces the current span name string with the formatted string provided. The span will end up with the last name provided.

func UpdateSpanReason 

func UpdateSpanReason(ctx context.Context, a ...interface{})

UpdateSpanReason replaces the current span reason with the formatted string provided. The span will end up with the last reason provided.

func Warn 

func Warn(ctx context.Context, a ...interface{})

Warn posts a warning trace event

Types

type Detail 

type Detail struct {
	// At is the real world time when the event is recorded.
	At time.Time

	// SimAt is the simulated time tick when the event is recorded.
	SimAt int64

	// CallersName is the short name of the function that triggered the creation
	// of this Detail instance.
	CallersName string

	// StackTrace contains the formatted stack trace at the time this Detail
	// is created.
	StackTrace string

	// Severity is the type of detail created: e.g. informational, warning, or
	// error.
	Severity pbl.Severity

	// Text is the description of the detail event.
	Text string

	// Action is type of detail that is being recorded: a trace event, or the
	// marking of a child trace span creation.
	Action pbl.Action

	// ChildId holds the trace span ID of the child trace span.  It is ignored
	// unless the Action is for a trace span creation.
	ChildId uuid.UUID

	SimEvent SimEvent
}

Detail is a structure that holds the fields that define a trace detail event.

type EndOption 

type EndOption func(*SpanData)

EndOption sets options and attributes when the span is ended.

func WithEndTime 

func WithEndTime(t time.Time) EndOption

WithEndTime sets the end time of the span to provided time t, when it is ended.

func WithSimEndTime 

func WithSimEndTime(t int64) EndOption

WithSimEndTime sets the simulated time that the span completed to the provided tick.

type Forwarder 

type Forwarder interface {
	// Close the forwarder.  This flushes any in-flight export operations, and
	// terminates the communications with the target trace export instance.
	Close()

	// Export is a function that forwards a trace span's data fields to the
	// trace span exporter.  Processing may be deferred until the exporter is
	// formally opened.
	Export(data *SpanData)
}

Forwarder is the interface that a trace sink forwarder must implement. It handles the common lifecycle operations.

type Forwarders 

type Forwarders []Forwarder

Forwarders defines the type that represents a set of trace forwarder instances.

type NoopSpan 

type NoopSpan struct{}

NoopSpan is an empty span that is purposefully incapable of any changes. It is used as a placeholder when there is no active span.

func (*NoopSpan) AddDetail 

func (*NoopSpan) AddDetail(_ *Detail)

func (*NoopSpan) AddImpact 

func (*NoopSpan) AddImpact(_ string, _ string)

func (*NoopSpan) Closed 

func (*NoopSpan) Closed() bool

func (*NoopSpan) End 

func (*NoopSpan) End(_ ...EndOption)

func (*NoopSpan) Modify 

func (*NoopSpan) Modify(ctx context.Context, _ ...StartSpanOption) context.Context

func (*NoopSpan) SetName 

func (*NoopSpan) SetName(_ ...interface{})

func (*NoopSpan) SetReason 

func (*NoopSpan) SetReason(_ ...interface{})

func (*NoopSpan) SetSimEvent 

func (*NoopSpan) SetSimEvent(_ SimEvent)

func (*NoopSpan) SetStatus 

func (*NoopSpan) SetStatus(_ log.Severity, _ string)

func (*NoopSpan) SimEvent 

func (*NoopSpan) SimEvent() SimEvent

func (*NoopSpan) SpanContext 

func (*NoopSpan) SpanContext() SpanContext

type ReplacementRule 

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

type Replacements 

type Replacements interface {
	Add(rule *ReplacementRule)
	Remove(rule *ReplacementRule)
	Process(text string) string
}

type SimEvent 

type SimEvent int
const (
	InSimulation       SimEvent = 1
	OutsideSimulation  SimEvent = 2
	AssumeInSimulation SimEvent = 3
)

func ParseSimEvent 

func ParseSimEvent(value string) SimEvent

ParseSimEvent attempts to convert the supplied string to its equivalent SimEvent value. Any error results in returning an assumed in simulation state.

func (SimEvent) ToWire 

func (e SimEvent) ToWire() string

ToWire returns the string value that matches the in/out simulation status.

type SpanContext 

type SpanContext struct {
	TraceId uuid.UUID
	Id      uuid.UUID
}

SpanContext is a structure that holds the span and trace IDs for a given span. This can be used to identify the parent span to use with a new (remote) child span.

func NewSpanContext 

func NewSpanContext(s string) SpanContext

NewSpanContext returns a new SpanContext instance based on the value in the supplied string. That value is expected to match the format from a SpanContext String() function. If the value cannot be parsed, the NullSpanContext is returned.

func (SpanContext) String 

func (s SpanContext) String() string

String is a function that returns a formatted string representing the value of the SpanContext instance.

type SpanData 

type SpanData struct {
	// ParentId, Id, and TraceId define the unique position of this trace span
	// in a tree of related events.
	ParentId uuid.UUID
	Id       uuid.UUID
	TraceId  uuid.UUID

	// Remote is a flag that is true if the initiator of this trace span did so
	// via some form of remote or asynchronous call.
	Remote bool

	// Name defines a summary string for this instance.
	Name string

	// Reason expands on the summary by supplying user-friendly explanatory text
	// for why the trace span actions happen.
	Reason string

	// StackTrace contains the formatted stack trace at the time the trace span
	// is created.
	StackTrace string

	// SimEvent signals whether this trace span is part of the simulation, or
	// part of the simulator machinery, or indeterminate.  The Infrastructure
	// flag is an about to be obsoleted earlier form of this.
	SimEvent SimEvent

	// impact statement
	Impacts []string

	// Details [set of events]
	Details []*Detail

	// simulated start and end times
	SimStart int64
	SimEnd   int64

	// real world start and end times
	WallStart time.Time
	WallEnd   time.Time
	// contains filtered or unexported fields
}

SpanData is a structure that contains the data associated with a trace span.

type SpanEx 

type SpanEx interface {
	// Modify updates the span data using the same WithXxx functions that are
	// used for starting a span.
	Modify(ctx context.Context, options ...StartSpanOption) context.Context

	// End terminates an open span, with the option for setting final attributes.
	End(opts ...EndOption)

	// SetReason sets the friendly description string on this span to a
	// formatted string using the supplied arguments.
	SetReason(a ...interface{})

	// SetName replaces the current span name string with the formatted string
	// provided.
	SetName(a ...interface{})

	// AddDetail adds the new event detail to this span
	AddDetail(detail *Detail)

	// AddImpact adds an impact claim to this span.
	AddImpact(level string, module string)

	// SetStatus sets a completion status attribute for this span.
	SetStatus(sev pbl.Severity, message string)

	// Closed returns true if this span has already ended; false, otherwise.
	Closed() bool

	// SimEvent returns the in/out/maybe simulation designator for the span.
	SimEvent() SimEvent

	// SetSimEvent updates the in/out/maybe simulation designator for the span.
	SetSimEvent(event SimEvent)

	// SpanContext returns the current trace and span UUIDs, or the empty UUID
	// for the values, if no span is currently active.
	SpanContext() SpanContext
}

SpanEx is the interface for starting, modifying, or ending a tracing span. The span is a collection of related event details, including a subtree of related (child) spans.

func SpanFromContext 

func SpanFromContext(ctx context.Context) SpanEx

SpanFromContext returns the current span stored in the context. Since that span may be stale, it is ignored if it is closed and the no-op span returned instead.

func StartSpan 

func StartSpan(ctx context.Context, options ...StartSpanOption) (context.Context, SpanEx)

StartSpan is a function that starts a new trace span in the current active trace provider.

type SpanImpl 

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

SpanImpl defines the data associated with an active span. The core field in it is the span, which contains the data that is passed along to the tracer's forwarder processes.

func (*SpanImpl) AddDetail 

func (s *SpanImpl) AddDetail(detail *Detail)

func (*SpanImpl) AddImpact 

func (s *SpanImpl) AddImpact(level string, module string)

func (*SpanImpl) Closed 

func (s *SpanImpl) Closed() bool

func (*SpanImpl) End 

func (s *SpanImpl) End(opts ...EndOption)

func (*SpanImpl) Modify 

func (s *SpanImpl) Modify(ctx context.Context, options ...StartSpanOption) context.Context

func (*SpanImpl) SetName 

func (s *SpanImpl) SetName(a ...interface{})

func (*SpanImpl) SetReason 

func (s *SpanImpl) SetReason(a ...interface{})

func (*SpanImpl) SetSimEvent 

func (s *SpanImpl) SetSimEvent(event SimEvent)

func (*SpanImpl) SetStatus 

func (s *SpanImpl) SetStatus(_ log.Severity, _ string)

func (*SpanImpl) SimEvent 

func (s *SpanImpl) SimEvent() SimEvent

func (*SpanImpl) SpanContext 

func (s *SpanImpl) SpanContext() SpanContext

type StartSpanOption 

type StartSpanOption func(*SpanData)

StartSpanOption sets options and attributes when the span is started.

func WithContextValue 

func WithContextValue(action decorator) StartSpanOption

WithContextValue decorates the resulting context using the supplied function

func WithForcedId 

func WithForcedId(spanId uuid.UUID) StartSpanOption

WithForcedId forcibly sets the span ID for the new instance. This is used when the parent is asynchronously (i.e. remotely) starting a child, and therefore needs to know the span ID prior to the span's creation.

func WithImpact 

func WithImpact(impact string, element string) StartSpanOption

WithImpact states that the activity covered in the calling trace event had the specified impact on the specified element.

func WithName 

func WithName(a ...interface{}) StartSpanOption

WithName adds the supplied value as the name of the span under creation

func WithReason 

func WithReason(reason string) StartSpanOption

WithReason adds a friendly description for the reason behind the logic in the span.

func WithSimulation 

func WithSimulation(flag SimEvent) StartSpanOption

WithSimulation sets the in/out/maybe simulation state for the span under creation.

func WithSpanContext 

func WithSpanContext(ctx SpanContext) StartSpanOption

WithSpanContext specifies that the span is to start with the supplied parent and trace IDs, but as a remote child.

type TraceAnnotation 

type TraceAnnotation func(cfg *TraceDetail)

TraceAnnotation defines the type signature for an annotation function that decorates a log trace event.

func WithReplacement 

func WithReplacement(match *regexp.Regexp, repl string) TraceAnnotation

WithReplacement states that the event text is to be searched using the match regex, and for every occurrence that is found, it is to be replaced by the value of the repl parameter.

type TraceDetail 

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

TraceDetail holds attributes and processing data that is used as part of the underlying AddTrace call.

type Tracer 

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

Tracer defines the data fields for a trace provider instance. Currently, this is the set of trace sink forwarders, and the common event text filter rules. The latter is currently latent.

func Current 

func Current() *Tracer

Current is a function that returns the global trace provider instance. It requires that the caller ensure proper synchronization relative to replacement with a new global tracer instance.

func NewTracer 

func NewTracer(forwarders Forwarders, replacements Replacements) *Tracer

NewTracer constructs a new trace provider instance.

func (*Tracer) NewSpan 

func (t *Tracer) NewSpan(ctx context.Context, options ...StartSpanOption) (context.Context, SpanEx)

NewSpan is the function on a trace provider instance that begins a new trace space.

func (*Tracer) Post 

func (t *Tracer) Post(span *SpanData)

Post forwards a trace span to all trace sink forwarder instances.

func (*Tracer) Stop 

func (t *Tracer) Stop()

Stop closes all trace sink forwarder instances.

Source Files

View all Source files

Directories

Path Synopsis

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.