api

Documentation

Overview

Package api provides the utilities necessary to instrument an application or library.

The instrumentation of a piece of code is independent of setting up any specific monitoring implementation when executing it. To setup a monitoring pipeline/stack at runtime use the `sdk` package.

Index

• Variables
• func AsEventData(data interface{}) otel.Attributes
• func AsHTTP(r *http.Request) otel.Attributes
• func AsInfo() otel.Attributes
• func AsNavigation(to, from string) otel.Attributes
• func AsOperation(name string) otel.Attributes
• func AsQuery() otel.Attributes
• func AsTags(kv map[string]interface{}) otel.Attributes
• func AsTransaction() otel.Attributes
• func AsWarning() otel.Attributes
• func Export(ctx context.Context) ([]byte, error)
• func Headers(sp SpanManaged) http.Header
• func Restore(data []byte) (context.Context, error)
• type Span
  • func SpanFromContext(ctx context.Context) Span
  • func Start(ctx context.Context, name string, opts ...SpanOption) Span
• type SpanKind
  • func (sk SpanKind) String() string
• type SpanManaged
• type SpanOption
  • func WithAttributes(attrs map[string]interface{}) SpanOption
  • func WithSpanKind(kind SpanKind) SpanOption
  • func WithStartOptions(opts ...apiTrace.SpanStartOption) SpanOption
• type Tracer
  • func GetTracer() Tracer

Variables

var ExceptionReportKey = attribute.Key("exception.report")

ExceptionReportKey is the attribute Key conforming to the "exception.report" semantic conventions. It represents a report obtained from the error provided when closing/ending a span.

Type: string
RequirementLevel: Optional
Stability: stable

Functions

func AsEventData

func AsEventData(data interface{}) otel.Attributes

AsEventData sets the `event.data` attribute to the provided value.

func AsHTTP

func AsHTTP(r *http.Request) otel.Attributes

AsHTTP returns a set of attributes to mark an event as describing an HTTP request started by the application.

func AsInfo

func AsInfo() otel.Attributes

AsInfo returns a set of attributes to mark an event as providing additional information.

func AsNavigation

func AsNavigation(to, from string) otel.Attributes

AsNavigation returns a set of attributes to mark an event as describing a navigation event.

func AsOperation

func AsOperation(name string) otel.Attributes

AsOperation returns a set of attributes to mark an event as an operation with a given name.

func AsQuery

func AsQuery() otel.Attributes

AsQuery returns a set of attributes to mark an event as a query.

func AsTags

func AsTags(kv map[string]interface{}) otel.Attributes

AsTags returns a set of attributes from the provided key-value pairs.

func AsTransaction

func AsTransaction() otel.Attributes

AsTransaction returns a set of attributes to mark an event as describing a tracing event.

func AsWarning

func AsWarning() otel.Attributes

AsWarning returns a set of attributes to mark an event as a warning.

func Export

func Export(ctx context.Context) ([]byte, error)

Export available span details. Useful when manually propagating a task context across process boundaries.

func Headers

func Headers(sp SpanManaged) http.Header

Headers return the cross-cutting concerns from span context as a set of HTTP headers. This is particularly useful when manually propagating the span across network boundaries using a non-conventional transport, like Websockets.

func Restore

func Restore(data []byte) (context.Context, error)

Restore previously exported span context data.

Types

type Span

type Span interface {
	// End will mark the span as completed. If `err` is not nil, the
	// status for the span will be marked as failed.
	End(err error)

	SpanManaged // inherit "managed" span functionality
}

Span represents a unit of work, performed over a certain period of time. You MUST finish all spans you create using the `End` method.

A span supports 2 independent data mechanisms that need to be properly propagated across service boundaries for the spans to be captured correctly.

The trace context provides trace information (trace IDs, span IDs, etc.), which ensure that all spans for a single request are part of the same trace.

Baggage, which are arbitrary key/value pairs that you can use to pass observability data between services (for example, sharing a customer ID from one service to the next).

func SpanFromContext

func SpanFromContext(ctx context.Context) Span

SpanFromContext returns the current Span from ctx.

If no Span is currently set in ctx an implementation of a Span that performs no operations is returned.

func Start

func Start(ctx context.Context, name string, opts ...SpanOption) Span

Start a new span using the global tracer instance. Remember to mark it as complete using `End` when done.

task := Start(context.TODO(), "my-task")
defer task.End(nil)

type SpanKind

type SpanKind string

SpanKind indicates the nature and/or owner of the traced operation.

const (
	// SpanKindUnspecified is the default value used when no span kind
	// is explicitly set.
	SpanKindUnspecified SpanKind = "unspecified"

	// SpanKindInternal should be used for internal-only tasks.
	SpanKindInternal SpanKind = "internal"

	// SpanKindServer should be used for server-side operations.
	SpanKindServer SpanKind = "server"

	// SpanKindClient should be used for client-side operations.
	SpanKindClient SpanKind = "client"

	// SpanKindConsumer should be used when an operation starts
	// by receiving a message from an MQ broker.
	SpanKindConsumer SpanKind = "consumer"

	// SpanKindProducer should be used when an operation involves
	// the publishing of a message to an MQ broker.
	SpanKindProducer SpanKind = "producer"
)

func (SpanKind) String

func (sk SpanKind) String() string

type SpanManaged

type SpanManaged interface {
	// Context of the span instance. Creating a new span with this context
	// will establish a parent -> child relationship.
	Context() context.Context

	// Unwrap returns the underlying OpenTelemetry span instance.
	// Useful for integrating with 3rd party libraries.
	Unwrap() trace.Span

	// ID returns the span identifier, if any.
	ID() string

	// TraceID returns the span's parent trace identifier, if any.
	TraceID() string

	// IsSampled returns if the sampling bit is set in the span context's.
	IsSampled() bool

	// Event produces a log marker during the execution of the span.
	Event(msg string, attributes ...map[string]interface{})

	// SetAttribute adjust `key` to report `value` as attribute of the Span.
	// If a `key` already exists for an attribute of the Span it will be
	// overwritten with `value`.
	SetAttribute(key string, value interface{})

	// SetAttributes adjust multiple attributes of the Span.
	SetAttributes(attributes map[string]interface{})
}

SpanManaged represents a unit of work that was initiated by another component. You may get a read-only reference to the span to inspect it or add additional events to it but you won't be able to close it directly.

You can also use the `Context()` of the managed span to initiate child tasks of your own.

type SpanOption

type SpanOption func(conf *spanConfig)

SpanOption allow adjusting span settings at the moment of creation.

func WithAttributes

func WithAttributes(attrs map[string]interface{}) SpanOption

WithAttributes adds additional metadata related to a specific task. These attributes are used to describe the work a Span represents. If multiple of these options are passed the attributes of each successive option will extend/override any previously set value.

func WithSpanKind

func WithSpanKind(kind SpanKind) SpanOption

WithSpanKind adjust the `span.kind` value for the created span. When no value is provided, `unspecified` is used by default.

func WithStartOptions

func WithStartOptions(opts ...apiTrace.SpanStartOption) SpanOption

WithStartOptions allows passing additional options to the span creation process.

type Tracer

type Tracer interface {
	// Start a new span.
	Start(ctx context.Context, name string, opts ...SpanOption) Span
}

Tracer instances can be used to create spans.

func GetTracer

func GetTracer() Tracer

GetTracer returns the global tracer instance.