otel: go.opentelemetry.io/otel/api/trace Index | Files | Directories

package trace

import "go.opentelemetry.io/otel/api/trace"

Index

Package Files

always_sampler.go api.go b3_propagator.go context.go doc.go never_sampler.go noop_span.go noop_trace.go noop_trace_provider.go sampler.go trace_context_propagator.go

Constants

const (
    B3SingleHeader       = "X-B3"
    B3DebugFlagHeader    = "X-B3-Flags"
    B3TraceIDHeader      = "X-B3-TraceId"
    B3SpanIDHeader       = "X-B3-SpanId"
    B3SampledHeader      = "X-B3-Sampled"
    B3ParentSpanIDHeader = "X-B3-ParentSpanId"
)
const (
    TraceparentHeader = "Traceparent"
)

func ContextWithRemoteSpanContext Uses

func ContextWithRemoteSpanContext(ctx context.Context, sc core.SpanContext) context.Context

ContextWithRemoteSpanContext creates a new context with a remote span context set to the passed span context.

func ContextWithSpan Uses

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

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

func DefaultHTTPPropagator Uses

func DefaultHTTPPropagator() propagation.HTTPPropagator

DefaultHTTPPropagator returns the default trace HTTP propagator.

func RemoteSpanContextFromContext Uses

func RemoteSpanContextFromContext(ctx context.Context) core.SpanContext

RemoteSpanContextFromContext returns the remote span context stored in the context.

type B3 Uses

type B3 struct {
    SingleHeader bool
}

B3 propagator serializes core.SpanContext to/from B3 Headers. This propagator supports both version of B3 headers,

1. Single Header :
  X-B3: {TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}
2. Multiple Headers:
  X-B3-TraceId: {TraceId}
  X-B3-ParentSpanId: {ParentSpanId}
  X-B3-SpanId: {SpanId}
  X-B3-Sampled: {SamplingState}
  X-B3-Flags: {DebugFlag}

If SingleHeader is set to true then X-B3 header is used to inject and extract. Otherwise, separate headers are used to inject and extract.

func (B3) Extract Uses

func (b3 B3) Extract(ctx context.Context, supplier propagation.HTTPSupplier) context.Context

Extract retrieves B3 Headers from the supplier

func (B3) GetAllKeys Uses

func (b3 B3) GetAllKeys() []string

func (B3) Inject Uses

func (b3 B3) Inject(ctx context.Context, supplier propagation.HTTPSupplier)

type Decision Uses

type Decision struct {
    // Sampled is set true if the span should be sampled.
    Sampled bool

    // Attributes provides insight into Sample	r's decision process.
    // It could be empty slice or nil if no attributes are recorded by the sampler.
    Attributes []core.KeyValue
}

type EndConfig Uses

type EndConfig struct {
    EndTime time.Time
}

EndConfig provides options to set properties of span at the time of ending the span.

type EndOption Uses

type EndOption func(*EndConfig)

EndOption applies changes to EndConfig that sets options when the span is ended.

func WithEndTime Uses

func WithEndTime(t time.Time) EndOption

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

type Link struct {
    core.SpanContext
    Attributes []core.KeyValue
}

Link is used to establish relationship between two spans within the same Trace or across different Traces. Few examples of Link usage.

1. Batch Processing: A batch of elements may contain elements associated with one
   or more traces/spans. Since there can only be one parent SpanContext, Link is
   used to keep reference to SpanContext of all elements in the batch.
2. Public Endpoint: A SpanContext in incoming client request on a public endpoint
   is untrusted from service provider perspective. In such case it is advisable to
   start a new trace with appropriate sampling decision.
   However, it is desirable to associate incoming SpanContext to new trace initiated
   on service provider side so two traces (from Client and from Service Provider) can
   be correlated.

type NoopProvider Uses

type NoopProvider struct{}

func (NoopProvider) Tracer Uses

func (p NoopProvider) Tracer(name string) Tracer

Tracer returns noop implementation of Tracer.

type NoopSpan Uses

type NoopSpan struct {
}

func (NoopSpan) AddEvent Uses

func (NoopSpan) AddEvent(ctx context.Context, name string, attrs ...core.KeyValue)

AddEvent does nothing.

func (NoopSpan) AddEventWithTimestamp Uses

func (NoopSpan) AddEventWithTimestamp(ctx context.Context, timestamp time.Time, name string, attrs ...core.KeyValue)

AddEventWithTimestamp does nothing.

func (NoopSpan) End Uses

func (NoopSpan) End(options ...EndOption)

End does nothing.

func (NoopSpan) IsRecording Uses

func (NoopSpan) IsRecording() bool

IsRecording always returns false for NoopSpan.

func (NoopSpan) SetAttributes Uses

func (NoopSpan) SetAttributes(attributes ...core.KeyValue)

SetAttributes does nothing.

func (NoopSpan) SetError Uses

func (NoopSpan) SetError(v bool)

SetError does nothing.

func (NoopSpan) SetName Uses

func (NoopSpan) SetName(name string)

SetName does nothing.

func (NoopSpan) SetStatus Uses

func (NoopSpan) SetStatus(status codes.Code)

SetStatus does nothing.

func (NoopSpan) SpanContext Uses

func (NoopSpan) SpanContext() core.SpanContext

SpanContext returns an invalid span context.

func (NoopSpan) Tracer Uses

func (NoopSpan) Tracer() Tracer

Tracer returns noop implementation of Tracer.

type NoopTracer Uses

type NoopTracer struct{}

func (NoopTracer) Start Uses

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

Start starts a noop span.

func (NoopTracer) WithSpan Uses

func (t NoopTracer) WithSpan(ctx context.Context, name string, body func(context.Context) error, opts ...StartOption) error

WithSpan wraps around execution of func with noop span.

type Provider Uses

type Provider interface {
    // Tracer creates a named tracer that implements Tracer interface.
    // If the name is an empty string then provider uses default name.
    Tracer(name string) Tracer
}

type Sampler Uses

type Sampler interface {
    // ShouldSample returns a Decision that contains a decision whether to sample
    // or not sample the span to be created. Decision is based on a Sampler specific
    // algorithm that takes into account one or more input parameters.
    ShouldSample(
        sc core.SpanContext,
        remote bool,
        traceID core.TraceID,
        spanID uint64,
        spanName string,
    ) Decision

    // Description returns of the sampler. It contains its name or short description
    // and its configured properties.
    // For example 'ProbabilitySampler:{0.00001}'
    Description() string
}

func AlwaysSampleSampler Uses

func AlwaysSampleSampler() Sampler

func NeverSampleSampler Uses

func NeverSampleSampler() Sampler

type Span Uses

type Span interface {
    // Tracer returns tracer used to create this span. Tracer cannot be nil.
    Tracer() Tracer

    // End completes the span. No updates are allowed to span after it
    // ends. The only exception is setting status of the span.
    End(options ...EndOption)

    // AddEvent adds an event to the span.
    AddEvent(ctx context.Context, name string, attrs ...core.KeyValue)
    // AddEventWithTimestamp adds an event with a custom timestamp
    // to the span.
    AddEventWithTimestamp(ctx context.Context, timestamp time.Time, name string, attrs ...core.KeyValue)

    // IsRecording returns true if the span is active and recording events is enabled.
    IsRecording() bool

    // SpanContext returns span context of the span. Returned SpanContext is usable
    // even after the span ends.
    SpanContext() core.SpanContext

    // SetStatus sets the status of the span. The status of the span can be updated
    // even after span ends.
    SetStatus(codes.Code)

    // SetName sets the name of the span.
    SetName(name string)

    // Set span attributes
    SetAttributes(...core.KeyValue)
}

func SpanFromContext Uses

func SpanFromContext(ctx context.Context) Span

SpanFromContext returns the current span stored in the context.

type SpanKind Uses

type SpanKind int

SpanKind represents the role of a Span inside a Trace. Often, this defines how a Span will be processed and visualized by various backends.

const (
    // As a convenience, these match the proto definition, see
    // opentelemetry/proto/trace/v1/trace.proto
    //
    // The unspecified value is not a valid `SpanKind`.  Use
    // `ValidateSpanKind()` to coerce a span kind to a valid
    // value.
    SpanKindUnspecified SpanKind = 0
    SpanKindInternal    SpanKind = 1
    SpanKindServer      SpanKind = 2
    SpanKindClient      SpanKind = 3
    SpanKindProducer    SpanKind = 4
    SpanKindConsumer    SpanKind = 5
)

func ValidateSpanKind Uses

func ValidateSpanKind(spanKind SpanKind) SpanKind

ValidateSpanKind returns a valid span kind value. This will coerce invalid values into the default value, SpanKindInternal.

func (SpanKind) String Uses

func (sk SpanKind) String() string

String returns the specified name of the SpanKind in lower-case.

type StartConfig Uses

type StartConfig struct {
    Attributes []core.KeyValue
    StartTime  time.Time
    Links      []Link
    Record     bool
    NewRoot    bool
    SpanKind   SpanKind
}

StartConfig provides options to set properties of span at the time of starting a new span.

type StartOption Uses

type StartOption func(*StartConfig)

StartOption applies changes to StartConfig that sets options at span start time.

func LinkedTo Uses

func LinkedTo(sc core.SpanContext, attrs ...core.KeyValue) StartOption

LinkedTo allows instantiating a Span with initial Links.

func WithAttributes Uses

func WithAttributes(attrs ...core.KeyValue) StartOption

WithAttributes sets attributes to span. These attributes provides additional data about the span. Multiple `WithAttributes` options appends the attributes preserving the order.

func WithNewRoot Uses

func WithNewRoot() StartOption

WithNewRoot specifies that the current span or remote span context in context passed to `Start` should be ignored when deciding about a parent, which effectively means creating a span with new trace ID. The current span and the remote span context may be added as links to the span by the implementation.

func WithRecord Uses

func WithRecord() StartOption

WithRecord specifies that the span should be recorded. Note that the implementation may still override this preference, e.g., if the span is a child in an unsampled trace.

func WithSpanKind Uses

func WithSpanKind(sk SpanKind) StartOption

WithSpanKind specifies the role a Span on a Trace.

func WithStartTime Uses

func WithStartTime(t time.Time) StartOption

WithStartTime sets the start time of the span to provided time t, when it is started. In absence of this option, wall clock time is used as start time. This option is typically used when starting of the span is delayed.

type TraceContext Uses

type TraceContext struct{}

TraceContext propagates SpanContext in W3C TraceContext format. nolint:golint

func (TraceContext) Extract Uses

func (tc TraceContext) Extract(ctx context.Context, supplier propagation.HTTPSupplier) context.Context

func (TraceContext) GetAllKeys Uses

func (TraceContext) GetAllKeys() []string

func (TraceContext) Inject Uses

func (TraceContext) Inject(ctx context.Context, supplier propagation.HTTPSupplier)

type Tracer Uses

type Tracer interface {
    // Start a span.
    Start(ctx context.Context, spanName string, opts ...StartOption) (context.Context, Span)

    // WithSpan wraps the execution of the fn function with a span.
    // It starts a new span, sets it as an active span in the context,
    // executes the fn function and closes the span before returning the result of fn.
    WithSpan(
        ctx context.Context,
        spanName string,
        fn func(ctx context.Context) error,
        opts ...StartOption,
    ) error
}

Directories

PathSynopsis
testtrace

Package trace imports 9 packages (graph) and is imported by 34 packages. Updated 2020-02-21. Refresh now. Tools for package owners.