third_party/golibs/vendor/go.opencensus.io/trace/trace_api.go - fuchsia - Git at Google

 // Copyright 2020, OpenCensus Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //     http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.

 package trace

 import (
 	"context"
 )

 // DefaultTracer is the tracer used when package-level exported functions are invoked.
 var DefaultTracer Tracer = &tracer{}

 // Tracer can start spans and access context functions.
 type Tracer interface {

 	// StartSpan starts a new child span of the current span in the context. If
 	// there is no span in the context, creates a new trace and span.
 	//
 	// Returned context contains the newly created span. You can use it to
 	// propagate the returned span in process.
 	StartSpan(ctx context.Context, name string, o ...StartOption) (context.Context, *Span)

 	// StartSpanWithRemoteParent starts a new child span of the span from the given parent.
 	//
 	// If the incoming context contains a parent, it ignores. StartSpanWithRemoteParent is
 	// preferred for cases where the parent is propagated via an incoming request.
 	//
 	// Returned context contains the newly created span. You can use it to
 	// propagate the returned span in process.
 	StartSpanWithRemoteParent(ctx context.Context, name string, parent SpanContext, o ...StartOption) (context.Context, *Span)

 	// FromContext returns the Span stored in a context, or nil if there isn't one.
 	FromContext(ctx context.Context) *Span

 	// NewContext returns a new context with the given Span attached.
 	NewContext(parent context.Context, s *Span) context.Context
 }

 // StartSpan starts a new child span of the current span in the context. If
 // there is no span in the context, creates a new trace and span.
 //
 // Returned context contains the newly created span. You can use it to
 // propagate the returned span in process.
 func StartSpan(ctx context.Context, name string, o ...StartOption) (context.Context, *Span) {
 	return DefaultTracer.StartSpan(ctx, name, o...)
 }

 // StartSpanWithRemoteParent starts a new child span of the span from the given parent.
 //
 // If the incoming context contains a parent, it ignores. StartSpanWithRemoteParent is
 // preferred for cases where the parent is propagated via an incoming request.
 //
 // Returned context contains the newly created span. You can use it to
 // propagate the returned span in process.
 func StartSpanWithRemoteParent(ctx context.Context, name string, parent SpanContext, o ...StartOption) (context.Context, *Span) {
 	return DefaultTracer.StartSpanWithRemoteParent(ctx, name, parent, o...)
 }

 // FromContext returns the Span stored in a context, or a Span that is not
 // recording events if there isn't one.
 func FromContext(ctx context.Context) *Span {
 	return DefaultTracer.FromContext(ctx)
 }

 // NewContext returns a new context with the given Span attached.
 func NewContext(parent context.Context, s *Span) context.Context {
 	return DefaultTracer.NewContext(parent, s)
 }

 // SpanInterface represents a span of a trace.  It has an associated SpanContext, and
 // stores data accumulated while the span is active.
 //
 // Ideally users should interact with Spans by calling the functions in this
 // package that take a Context parameter.
 type SpanInterface interface {

 	// IsRecordingEvents returns true if events are being recorded for this span.
 	// Use this check to avoid computing expensive annotations when they will never
 	// be used.
 	IsRecordingEvents() bool

 	// End ends the span.
 	End()

 	// SpanContext returns the SpanContext of the span.
 	SpanContext() SpanContext

 	// SetName sets the name of the span, if it is recording events.
 	SetName(name string)

 	// SetStatus sets the status of the span, if it is recording events.
 	SetStatus(status Status)

 	// AddAttributes sets attributes in the span.
 	//
 	// Existing attributes whose keys appear in the attributes parameter are overwritten.
 	AddAttributes(attributes ...Attribute)

 	// Annotate adds an annotation with attributes.
 	// Attributes can be nil.
 	Annotate(attributes []Attribute, str string)

 	// Annotatef adds an annotation with attributes.
 	Annotatef(attributes []Attribute, format string, a ...interface{})

 	// AddMessageSendEvent adds a message send event to the span.
 	//
 	// messageID is an identifier for the message, which is recommended to be
 	// unique in this span and the same between the send event and the receive
 	// event (this allows to identify a message between the sender and receiver).
 	// For example, this could be a sequence id.
 	AddMessageSendEvent(messageID, uncompressedByteSize, compressedByteSize int64)

 	// AddMessageReceiveEvent adds a message receive event to the span.
 	//
 	// messageID is an identifier for the message, which is recommended to be
 	// unique in this span and the same between the send event and the receive
 	// event (this allows to identify a message between the sender and receiver).
 	// For example, this could be a sequence id.
 	AddMessageReceiveEvent(messageID, uncompressedByteSize, compressedByteSize int64)

 	// AddLink adds a link to the span.
 	AddLink(l Link)

 	// String prints a string representation of a span.
 	String() string
 }

 // NewSpan is a convenience function for creating a *Span out of a *span
 func NewSpan(s SpanInterface) *Span {
 	return &Span{internal: s}
 }

 // Span is a struct wrapper around the SpanInt interface, which allows correctly handling
 // nil spans, while also allowing the SpanInterface implementation to be swapped out.
 type Span struct {
 	internal SpanInterface
 }

 // Internal returns the underlying implementation of the Span
 func (s *Span) Internal() SpanInterface {
 	return s.internal
 }

 // IsRecordingEvents returns true if events are being recorded for this span.
 // Use this check to avoid computing expensive annotations when they will never
 // be used.
 func (s *Span) IsRecordingEvents() bool {
 	if s == nil {
 		return false
 	}
 	return s.internal.IsRecordingEvents()
 }

 // End ends the span.
 func (s *Span) End() {
 	if s == nil {
 		return
 	}
 	s.internal.End()
 }

 // SpanContext returns the SpanContext of the span.
 func (s *Span) SpanContext() SpanContext {
 	if s == nil {
 		return SpanContext{}
 	}
 	return s.internal.SpanContext()
 }

 // SetName sets the name of the span, if it is recording events.
 func (s *Span) SetName(name string) {
 	if !s.IsRecordingEvents() {
 		return
 	}
 	s.internal.SetName(name)
 }

 // SetStatus sets the status of the span, if it is recording events.
 func (s *Span) SetStatus(status Status) {
 	if !s.IsRecordingEvents() {
 		return
 	}
 	s.internal.SetStatus(status)
 }

 // AddAttributes sets attributes in the span.
 //
 // Existing attributes whose keys appear in the attributes parameter are overwritten.
 func (s *Span) AddAttributes(attributes ...Attribute) {
 	if !s.IsRecordingEvents() {
 		return
 	}
 	s.internal.AddAttributes(attributes...)
 }

 // Annotate adds an annotation with attributes.
 // Attributes can be nil.
 func (s *Span) Annotate(attributes []Attribute, str string) {
 	if !s.IsRecordingEvents() {
 		return
 	}
 	s.internal.Annotate(attributes, str)
 }

 // Annotatef adds an annotation with attributes.
 func (s *Span) Annotatef(attributes []Attribute, format string, a ...interface{}) {
 	if !s.IsRecordingEvents() {
 		return
 	}
 	s.internal.Annotatef(attributes, format, a...)
 }

 // AddMessageSendEvent adds a message send event to the span.
 //
 // messageID is an identifier for the message, which is recommended to be
 // unique in this span and the same between the send event and the receive
 // event (this allows to identify a message between the sender and receiver).
 // For example, this could be a sequence id.
 func (s *Span) AddMessageSendEvent(messageID, uncompressedByteSize, compressedByteSize int64) {
 	if !s.IsRecordingEvents() {
 		return
 	}
 	s.internal.AddMessageSendEvent(messageID, uncompressedByteSize, compressedByteSize)
 }

 // AddMessageReceiveEvent adds a message receive event to the span.
 //
 // messageID is an identifier for the message, which is recommended to be
 // unique in this span and the same between the send event and the receive
 // event (this allows to identify a message between the sender and receiver).
 // For example, this could be a sequence id.
 func (s *Span) AddMessageReceiveEvent(messageID, uncompressedByteSize, compressedByteSize int64) {
 	if !s.IsRecordingEvents() {
 		return
 	}
 	s.internal.AddMessageReceiveEvent(messageID, uncompressedByteSize, compressedByteSize)
 }

 // AddLink adds a link to the span.
 func (s *Span) AddLink(l Link) {
 	if !s.IsRecordingEvents() {
 		return
 	}
 	s.internal.AddLink(l)
 }

 // String prints a string representation of a span.
 func (s *Span) String() string {
 	if s == nil {
 		return "<nil>"
 	}
 	return s.internal.String()
 }
	// Copyright 2020, OpenCensus Authors
	//
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.

	package trace

	import (
	"context"
	)

	// DefaultTracer is the tracer used when package-level exported functions are invoked.
	var DefaultTracer Tracer = &tracer{}

	// Tracer can start spans and access context functions.
	type Tracer interface {

	// StartSpan starts a new child span of the current span in the context. If
	// there is no span in the context, creates a new trace and span.
	//
	// Returned context contains the newly created span. You can use it to
	// propagate the returned span in process.
	StartSpan(ctx context.Context, name string, o ...StartOption) (context.Context, *Span)

	// StartSpanWithRemoteParent starts a new child span of the span from the given parent.
	//
	// If the incoming context contains a parent, it ignores. StartSpanWithRemoteParent is
	// preferred for cases where the parent is propagated via an incoming request.
	//
	// Returned context contains the newly created span. You can use it to
	// propagate the returned span in process.
	StartSpanWithRemoteParent(ctx context.Context, name string, parent SpanContext, o ...StartOption) (context.Context, *Span)

	// FromContext returns the Span stored in a context, or nil if there isn't one.
	FromContext(ctx context.Context) *Span

	// NewContext returns a new context with the given Span attached.
	NewContext(parent context.Context, s *Span) context.Context
	}

	// StartSpan starts a new child span of the current span in the context. If
	// there is no span in the context, creates a new trace and span.
	//
	// Returned context contains the newly created span. You can use it to
	// propagate the returned span in process.
	func StartSpan(ctx context.Context, name string, o ...StartOption) (context.Context, *Span) {
	return DefaultTracer.StartSpan(ctx, name, o...)
	}

	// StartSpanWithRemoteParent starts a new child span of the span from the given parent.
	//
	// If the incoming context contains a parent, it ignores. StartSpanWithRemoteParent is
	// preferred for cases where the parent is propagated via an incoming request.
	//
	// Returned context contains the newly created span. You can use it to
	// propagate the returned span in process.
	func StartSpanWithRemoteParent(ctx context.Context, name string, parent SpanContext, o ...StartOption) (context.Context, *Span) {
	return DefaultTracer.StartSpanWithRemoteParent(ctx, name, parent, o...)
	}

	// FromContext returns the Span stored in a context, or a Span that is not
	// recording events if there isn't one.
	func FromContext(ctx context.Context) *Span {
	return DefaultTracer.FromContext(ctx)
	}

	// NewContext returns a new context with the given Span attached.
	func NewContext(parent context.Context, s *Span) context.Context {
	return DefaultTracer.NewContext(parent, s)
	}

	// SpanInterface represents a span of a trace. It has an associated SpanContext, and
	// stores data accumulated while the span is active.
	//
	// Ideally users should interact with Spans by calling the functions in this
	// package that take a Context parameter.
	type SpanInterface interface {

	// IsRecordingEvents returns true if events are being recorded for this span.
	// Use this check to avoid computing expensive annotations when they will never
	// be used.
	IsRecordingEvents() bool

	// End ends the span.
	End()

	// SpanContext returns the SpanContext of the span.
	SpanContext() SpanContext

	// SetName sets the name of the span, if it is recording events.
	SetName(name string)

	// SetStatus sets the status of the span, if it is recording events.
	SetStatus(status Status)

	// AddAttributes sets attributes in the span.
	//
	// Existing attributes whose keys appear in the attributes parameter are overwritten.
	AddAttributes(attributes ...Attribute)

	// Annotate adds an annotation with attributes.
	// Attributes can be nil.
	Annotate(attributes []Attribute, str string)

	// Annotatef adds an annotation with attributes.
	Annotatef(attributes []Attribute, format string, a ...interface{})

	// AddMessageSendEvent adds a message send event to the span.
	//
	// messageID is an identifier for the message, which is recommended to be
	// unique in this span and the same between the send event and the receive
	// event (this allows to identify a message between the sender and receiver).
	// For example, this could be a sequence id.
	AddMessageSendEvent(messageID, uncompressedByteSize, compressedByteSize int64)

	// AddMessageReceiveEvent adds a message receive event to the span.
	//
	// messageID is an identifier for the message, which is recommended to be
	// unique in this span and the same between the send event and the receive
	// event (this allows to identify a message between the sender and receiver).
	// For example, this could be a sequence id.
	AddMessageReceiveEvent(messageID, uncompressedByteSize, compressedByteSize int64)

	// AddLink adds a link to the span.
	AddLink(l Link)

	// String prints a string representation of a span.
	String() string
	}

	// NewSpan is a convenience function for creating a Span out of a span
	func NewSpan(s SpanInterface) *Span {
	return &Span{internal: s}
	}

	// Span is a struct wrapper around the SpanInt interface, which allows correctly handling
	// nil spans, while also allowing the SpanInterface implementation to be swapped out.
	type Span struct {
	internal SpanInterface
	}

	// Internal returns the underlying implementation of the Span
	func (s *Span) Internal() SpanInterface {
	return s.internal
	}

	// IsRecordingEvents returns true if events are being recorded for this span.
	// Use this check to avoid computing expensive annotations when they will never
	// be used.
	func (s *Span) IsRecordingEvents() bool {
	if s == nil {
	return false
	}
	return s.internal.IsRecordingEvents()
	}

	// End ends the span.
	func (s *Span) End() {
	if s == nil {
	return
	}
	s.internal.End()
	}

	// SpanContext returns the SpanContext of the span.
	func (s *Span) SpanContext() SpanContext {
	if s == nil {
	return SpanContext{}
	}
	return s.internal.SpanContext()
	}

	// SetName sets the name of the span, if it is recording events.
	func (s *Span) SetName(name string) {
	if !s.IsRecordingEvents() {
	return
	}
	s.internal.SetName(name)
	}

	// SetStatus sets the status of the span, if it is recording events.
	func (s *Span) SetStatus(status Status) {
	if !s.IsRecordingEvents() {
	return
	}
	s.internal.SetStatus(status)
	}

	// AddAttributes sets attributes in the span.
	//
	// Existing attributes whose keys appear in the attributes parameter are overwritten.
	func (s *Span) AddAttributes(attributes ...Attribute) {
	if !s.IsRecordingEvents() {
	return
	}
	s.internal.AddAttributes(attributes...)
	}

	// Annotate adds an annotation with attributes.
	// Attributes can be nil.
	func (s *Span) Annotate(attributes []Attribute, str string) {
	if !s.IsRecordingEvents() {
	return
	}
	s.internal.Annotate(attributes, str)
	}

	// Annotatef adds an annotation with attributes.
	func (s *Span) Annotatef(attributes []Attribute, format string, a ...interface{}) {
	if !s.IsRecordingEvents() {
	return
	}
	s.internal.Annotatef(attributes, format, a...)
	}

	// AddMessageSendEvent adds a message send event to the span.
	//
	// messageID is an identifier for the message, which is recommended to be
	// unique in this span and the same between the send event and the receive
	// event (this allows to identify a message between the sender and receiver).
	// For example, this could be a sequence id.
	func (s *Span) AddMessageSendEvent(messageID, uncompressedByteSize, compressedByteSize int64) {
	if !s.IsRecordingEvents() {
	return
	}
	s.internal.AddMessageSendEvent(messageID, uncompressedByteSize, compressedByteSize)
	}

	// AddMessageReceiveEvent adds a message receive event to the span.
	//
	// messageID is an identifier for the message, which is recommended to be
	// unique in this span and the same between the send event and the receive
	// event (this allows to identify a message between the sender and receiver).
	// For example, this could be a sequence id.
	func (s *Span) AddMessageReceiveEvent(messageID, uncompressedByteSize, compressedByteSize int64) {
	if !s.IsRecordingEvents() {
	return
	}
	s.internal.AddMessageReceiveEvent(messageID, uncompressedByteSize, compressedByteSize)
	}

	// AddLink adds a link to the span.
	func (s *Span) AddLink(l Link) {
	if !s.IsRecordingEvents() {
	return
	}
	s.internal.AddLink(l)
	}

	// String prints a string representation of a span.
	func (s *Span) String() string {
	if s == nil {
	return "<nil>"
	}
	return s.internal.String()
	}