package trace
Import Path
go.opentelemetry.io/otel/sdk/trace (on go.dev)
Dependency Relation
imports 31 packages, and imported by 3 packages
Involved Source Files
batch_span_processor.go
Package trace contains support for OpenTelemetry distributed tracing.
The following assumes a basic familiarity with OpenTelemetry concepts.
See https://opentelemetry.io.
See [go.opentelemetry.io/otel/sdk/trace/internal/x] for information about
the experimental features.
event.go
evictedqueue.go
id_generator.go
link.go
provider.go
sampler_env.go
sampling.go
simple_span_processor.go
snapshot.go
span.go
span_exporter.go
span_limits.go
span_processor.go
tracer.go
Package-Level Type Names (total 18)
BatchSpanProcessorOption configures a BatchSpanProcessor.
func WithBatchTimeout(delay time.Duration) BatchSpanProcessorOption
func WithBlocking() BatchSpanProcessorOption
func WithExportTimeout(timeout time.Duration) BatchSpanProcessorOption
func WithMaxExportBatchSize(size int) BatchSpanProcessorOption
func WithMaxQueueSize(size int) BatchSpanProcessorOption
func NewBatchSpanProcessor(exporter SpanExporter, options ...BatchSpanProcessorOption) SpanProcessor
func WithBatcher(e SpanExporter, opts ...BatchSpanProcessorOption) TracerProviderOption
BatchSpanProcessorOptions is configuration settings for a
BatchSpanProcessor.
BatchTimeout is the maximum duration for constructing a batch. Processor
forcefully sends available spans when timeout is reached.
The default value of BatchTimeout is 5000 msec.
BlockOnQueueFull blocks onEnd() and onStart() method if the queue is full
AND if BlockOnQueueFull is set to true.
Blocking option should be used carefully as it can severely affect the performance of an
application.
ExportTimeout specifies the maximum duration for exporting spans. If the timeout
is reached, the export will be cancelled.
The default value of ExportTimeout is 30000 msec.
MaxExportBatchSize is the maximum number of spans to process in a single batch.
If there are more than one batch worth of spans then it processes multiple batches
of spans one batch after the other without any delay.
The default value of MaxExportBatchSize is 512.
MaxQueueSize is the maximum queue size to buffer spans for delayed processing. If the
queue gets full it drops the spans. Use BlockOnQueueFull to change this behavior.
The default value of MaxQueueSize is 2048.
Event is a thing that happened during a Span's lifetime.
Attributes describe the aspects of the event.
DroppedAttributeCount is the number of attributes that were not
recorded due to configured limits being reached.
Name is the name of this event
Time at which this event was recorded.
func ReadOnlySpan.Events() []Event
func ReadWriteSpan.Events() []Event
IDGenerator allows custom generators for TraceID and SpanID.
NewIDs returns a new trace and span ID.
NewSpanID returns a ID for a new span in the trace with traceID.
func WithIDGenerator(g IDGenerator) TracerProviderOption
Link is the relationship between two Spans. The relationship can be within
the same Trace or across different Traces.
Attributes describe the aspects of the link.
DroppedAttributeCount is the number of attributes that were not
recorded due to configured limits being reached.
SpanContext of the linked Span.
func ReadOnlySpan.Links() []Link
func ReadWriteSpan.Links() []Link
ParentBasedSamplerOption configures the sampler for a particular sampling case.
func WithLocalParentNotSampled(s Sampler) ParentBasedSamplerOption
func WithLocalParentSampled(s Sampler) ParentBasedSamplerOption
func WithRemoteParentNotSampled(s Sampler) ParentBasedSamplerOption
func WithRemoteParentSampled(s Sampler) ParentBasedSamplerOption
func ParentBased(root Sampler, samplers ...ParentBasedSamplerOption) Sampler
ReadOnlySpan allows reading information from the data structure underlying a
trace.Span. It is used in places where reading information from a span is
necessary but changing the span isn't necessary or allowed.
Warning: methods may be added to this interface in minor releases.
Attributes returns the defining attributes of the span.
The order of the returned attributes is not guaranteed to be stable across invocations.
ChildSpanCount returns the count of spans that consider the span a
direct parent.
DroppedAttributes returns the number of attributes dropped by the span
due to limits being reached.
DroppedEvents returns the number of events dropped by the span due to
limits being reached.
DroppedLinks returns the number of links dropped by the span due to
limits being reached.
EndTime returns the time the span stopped recording. It will be zero if
the span has not ended.
Events returns all the events that occurred within in the spans
lifetime.
InstrumentationLibrary returns information about the instrumentation
library that created the span.
Deprecated: please use InstrumentationScope instead.
InstrumentationScope returns information about the instrumentation
scope that created the span.
Links returns all the links the span has to other spans.
Name returns the name of the span.
Parent returns the unique SpanContext that identifies the parent of the
span if one exists. If the span has no parent the returned SpanContext
will be invalid.
Resource returns information about the entity that produced the span.
SpanContext returns the unique SpanContext that identifies the span.
SpanKind returns the role the span plays in a Trace.
StartTime returns the time the span started recording.
Status returns the spans status.
ReadWriteSpan (interface)
ReadOnlySpan : github.com/polarsignals/frostdb/query/logicalplan.Named
func SpanExporter.ExportSpans(ctx context.Context, spans []ReadOnlySpan) error
func SpanProcessor.OnEnd(s ReadOnlySpan)
func go.opentelemetry.io/otel/exporters/otlp/otlptrace.(*Exporter).ExportSpans(ctx context.Context, ss []ReadOnlySpan) error
func go.opentelemetry.io/otel/exporters/otlp/otlptrace/internal/tracetransform.Spans(sdl []ReadOnlySpan) []*tracepb.ResourceSpans
ReadWriteSpan exposes the same methods as trace.Span and in addition allows
reading information from the underlying data structure.
This interface exposes the union of the methods of trace.Span (which is a
"write-only" span) and ReadOnlySpan. New methods for writing or reading span
information should be added under trace.Span or ReadOnlySpan, respectively.
Warning: methods may be added to this interface in minor releases.
AddEvent adds an event with the provided name and options.
AddLink adds a link.
Adding links at span creation using WithLinks is preferred to calling AddLink
later, for contexts that are available during span creation, because head
sampling decisions can only consider information present during span creation.
Attributes returns the defining attributes of the span.
The order of the returned attributes is not guaranteed to be stable across invocations.
ChildSpanCount returns the count of spans that consider the span a
direct parent.
DroppedAttributes returns the number of attributes dropped by the span
due to limits being reached.
DroppedEvents returns the number of events dropped by the span due to
limits being reached.
DroppedLinks returns the number of links dropped by the span due to
limits being reached.
End completes the Span. The Span is considered complete and ready to be
delivered through the rest of the telemetry pipeline after this method
is called. Therefore, updates to the Span are not allowed after this
method has been called.
EndTime returns the time the span stopped recording. It will be zero if
the span has not ended.
Events returns all the events that occurred within in the spans
lifetime.
InstrumentationLibrary returns information about the instrumentation
library that created the span.
Deprecated: please use InstrumentationScope instead.
InstrumentationScope returns information about the instrumentation
scope that created the span.
IsRecording returns the recording state of the Span. It will return
true if the Span is active and events can be recorded.
Links returns all the links the span has to other spans.
Name returns the name of the span.
Parent returns the unique SpanContext that identifies the parent of the
span if one exists. If the span has no parent the returned SpanContext
will be invalid.
RecordError will record err as an exception span event for this span. An
additional call to SetStatus is required if the Status of the Span should
be set to Error, as this method does not change the Span status. If this
span is not being recorded or err is nil then this method does nothing.
Resource returns information about the entity that produced the span.
SetAttributes sets kv as attributes of the Span. If a key from kv
already exists for an attribute of the Span it will be overwritten with
the value contained in kv.
SetName sets the Span name.
SetStatus sets the status of the Span in the form of a code and a
description, provided the status hasn't already been set to a higher
value before (OK > Error > Unset). The description is only included in a
status when the code is for an error.
SpanContext returns the SpanContext of the Span. The returned SpanContext
is usable even after the End method has been called for the Span.
SpanKind returns the role the span plays in a Trace.
StartTime returns the time the span started recording.
Status returns the spans status.
TracerProvider returns a TracerProvider that can be used to generate
additional Spans on the same telemetry pipeline as the current Span.
ReadWriteSpan : ReadOnlySpan
ReadWriteSpan : go.opentelemetry.io/otel/trace.Span
ReadWriteSpan : go.opentelemetry.io/otel/trace/embedded.Span
ReadWriteSpan : github.com/polarsignals/frostdb/query/logicalplan.Named
func SpanProcessor.OnStart(parent context.Context, s ReadWriteSpan)
Sampler decides whether a trace should be sampled and exported.
Description returns information describing the Sampler.
ShouldSample returns a SamplingResult based on a decision made from the
passed parameters.
Sampler : github.com/alexflint/go-arg.Described
func AlwaysSample() Sampler
func NeverSample() Sampler
func ParentBased(root Sampler, samplers ...ParentBasedSamplerOption) Sampler
func TraceIDRatioBased(fraction float64) Sampler
func ParentBased(root Sampler, samplers ...ParentBasedSamplerOption) Sampler
func WithLocalParentNotSampled(s Sampler) ParentBasedSamplerOption
func WithLocalParentSampled(s Sampler) ParentBasedSamplerOption
func WithRemoteParentNotSampled(s Sampler) ParentBasedSamplerOption
func WithRemoteParentSampled(s Sampler) ParentBasedSamplerOption
func WithSampler(s Sampler) TracerProviderOption
SamplingDecision indicates whether a span is dropped, recorded and/or sampled.
const Drop
const RecordAndSample
const RecordOnly
SamplingParameters contains the values passed to a Sampler.
Attributes []attribute.KeyValue
Kind trace.SpanKind
Links []trace.Link
Name string
ParentContext context.Context
TraceID trace.TraceID
func Sampler.ShouldSample(parameters SamplingParameters) SamplingResult
SamplingResult conveys a SamplingDecision, set of Attributes and a Tracestate.
Attributes []attribute.KeyValue
Decision SamplingDecision
Tracestate trace.TraceState
func Sampler.ShouldSample(parameters SamplingParameters) SamplingResult
SpanExporter handles the delivery of spans to external receivers. This is
the final component in the trace export pipeline.
ExportSpans exports a batch of spans.
This function is called synchronously, so there is no concurrency
safety requirement. However, due to the synchronous calling pattern,
it is critical that all timeouts and cancellations contained in the
passed context must be honored.
Any retry logic must be contained in this function. The SDK that
calls this function will not implement any retry logic. All errors
returned by this function are considered unrecoverable and will be
reported to a configured error Handler.
Shutdown notifies the exporter of a pending halt to operations. The
exporter is expected to perform any cleanup or synchronization it
requires while honoring all timeouts and cancellations contained in
the passed context.
*go.opentelemetry.io/otel/exporters/otlp/otlptrace.Exporter
func NewBatchSpanProcessor(exporter SpanExporter, options ...BatchSpanProcessorOption) SpanProcessor
func NewSimpleSpanProcessor(exporter SpanExporter) SpanProcessor
func WithBatcher(e SpanExporter, opts ...BatchSpanProcessorOption) TracerProviderOption
func WithSyncer(e SpanExporter) TracerProviderOption
SpanLimits represents the limits of a span.
AttributeCountLimit is the maximum allowed span attribute count. Any
attribute added to a span once this limit is reached will be dropped.
Setting this to zero means no attributes will be recorded.
Setting this to a negative value means no limit is applied.
AttributePerEventCountLimit is the maximum number of attributes allowed
per span event. Any attribute added after this limit reached will be
dropped.
Setting this to zero means no attributes will be recorded for events.
Setting this to a negative value means no limit is applied.
AttributePerLinkCountLimit is the maximum number of attributes allowed
per span link. Any attribute added after this limit reached will be
dropped.
Setting this to zero means no attributes will be recorded for links.
Setting this to a negative value means no limit is applied.
AttributeValueLengthLimit is the maximum allowed attribute value length.
This limit only applies to string and string slice attribute values.
Any string longer than this value will be truncated to this length.
Setting this to a negative value means no limit is applied.
EventCountLimit is the maximum allowed span event count. Any event
added to a span once this limit is reached means it will be added but
the oldest event will be dropped.
Setting this to zero means no events we be recorded.
Setting this to a negative value means no limit is applied.
LinkCountLimit is the maximum allowed span link count. Any link added
to a span once this limit is reached means it will be added but the
oldest link will be dropped.
Setting this to zero means no links we be recorded.
Setting this to a negative value means no limit is applied.
func NewSpanLimits() SpanLimits
func WithRawSpanLimits(limits SpanLimits) TracerProviderOption
func WithSpanLimits(sl SpanLimits) TracerProviderOption
SpanProcessor is a processing pipeline for spans in the trace signal.
SpanProcessors registered with a TracerProvider and are called at the start
and end of a Span's lifecycle, and are called in the order they are
registered.
ForceFlush exports all ended spans to the configured Exporter that have not yet
been exported. It should only be called when absolutely necessary, such as when
using a FaaS provider that may suspend the process after an invocation, but before
the Processor can export the completed spans.
OnEnd is called when span is finished. It is called synchronously and
hence not block.
OnStart is called when a span is started. It is called synchronously
and should not block.
Shutdown is called when the SDK shuts down. Any cleanup or release of
resources held by the processor should be done in this call.
Calls to OnStart, OnEnd, or ForceFlush after this has been called
should be ignored.
All timeouts and cancellations contained in ctx must be honored, this
should not block indefinitely.
func NewBatchSpanProcessor(exporter SpanExporter, options ...BatchSpanProcessorOption) SpanProcessor
func NewSimpleSpanProcessor(exporter SpanExporter) SpanProcessor
func WithSpanProcessor(sp SpanProcessor) TracerProviderOption
func (*TracerProvider).RegisterSpanProcessor(sp SpanProcessor)
func (*TracerProvider).UnregisterSpanProcessor(sp SpanProcessor)
Status is the classified state of a Span.
Code is an identifier of a Spans state classification.
Description is a user hint about why that status was set. It is only
applicable when Code is Error.
func ReadOnlySpan.Status() Status
func ReadWriteSpan.Status() Status
TracerProvider is an OpenTelemetry TracerProvider. It provides Tracers to
instrumentation so it can trace operational flow through a system.
TracerProvider embedded.TracerProvider
ForceFlush immediately exports all spans that have not yet been exported for
all the registered span processors.
RegisterSpanProcessor adds the given SpanProcessor to the list of SpanProcessors.
Shutdown shuts down TracerProvider. All registered span processors are shut down
in the order they were registered and any held computational resources are released.
After Shutdown is called, all methods are no-ops.
Tracer returns a Tracer with the given name and options. If a Tracer for
the given name and options does not exist it is created, otherwise the
existing Tracer is returned.
If name is empty, DefaultTracerName is used instead.
This method is safe to be called concurrently.
UnregisterSpanProcessor removes the given SpanProcessor from the list of SpanProcessors.
*TracerProvider : go.opentelemetry.io/otel/trace.TracerProvider
TracerProvider : go.opentelemetry.io/otel/trace/embedded.TracerProvider
func NewTracerProvider(opts ...TracerProviderOption) *TracerProvider
func github.com/pancsta/asyncmachine-go/pkg/telemetry.NewOtelProvider(source string, ctx context.Context) (trace.Tracer, *TracerProvider, error)
TracerProviderOption configures a TracerProvider.
func WithBatcher(e SpanExporter, opts ...BatchSpanProcessorOption) TracerProviderOption
func WithIDGenerator(g IDGenerator) TracerProviderOption
func WithRawSpanLimits(limits SpanLimits) TracerProviderOption
func WithResource(r *resource.Resource) TracerProviderOption
func WithSampler(s Sampler) TracerProviderOption
func WithSpanLimits(sl SpanLimits) TracerProviderOption
func WithSpanProcessor(sp SpanProcessor) TracerProviderOption
func WithSyncer(e SpanExporter) TracerProviderOption
func NewTracerProvider(opts ...TracerProviderOption) *TracerProvider
Package-Level Functions (total 25)
AlwaysSample returns a Sampler that samples every trace.
Be careful about using this sampler in a production application with
significant traffic: a new trace will be started and exported for every
request.
NeverSample returns a Sampler that samples no traces.
NewBatchSpanProcessor creates a new SpanProcessor that will send completed
span batches to the exporter with the supplied options.
If the exporter is nil, the span processor will perform no action.
NewSimpleSpanProcessor returns a new SpanProcessor that will synchronously
send completed spans to the exporter immediately.
This SpanProcessor is not recommended for production use. The synchronous
nature of this SpanProcessor makes it good for testing, debugging, or showing
examples of other features, but it will be slow and have a high computation
resource usage overhead. The BatchSpanProcessor is recommended for production
use instead.
NewSpanLimits returns a SpanLimits with all limits set to the value their
corresponding environment variable holds, or the default if unset.
• AttributeValueLengthLimit: OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT
(default: unlimited)
• AttributeCountLimit: OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT (default: 128)
• EventCountLimit: OTEL_SPAN_EVENT_COUNT_LIMIT (default: 128)
• AttributePerEventCountLimit: OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT (default:
128)
• LinkCountLimit: OTEL_SPAN_LINK_COUNT_LIMIT (default: 128)
• AttributePerLinkCountLimit: OTEL_LINK_ATTRIBUTE_COUNT_LIMIT (default: 128)
NewTracerProvider returns a new and configured TracerProvider.
By default the returned TracerProvider is configured with:
- a ParentBased(AlwaysSample) Sampler
- a random number IDGenerator
- the resource.Default() Resource
- the default SpanLimits.
The passed opts are used to override these default values and configure the
returned TracerProvider appropriately.
ParentBased returns a sampler decorator which behaves differently,
based on the parent of the span. If the span has no parent,
the decorated sampler is used to make sampling decision. If the span has
a parent, depending on whether the parent is remote and whether it
is sampled, one of the following samplers will apply:
- remoteParentSampled(Sampler) (default: AlwaysOn)
- remoteParentNotSampled(Sampler) (default: AlwaysOff)
- localParentSampled(Sampler) (default: AlwaysOn)
- localParentNotSampled(Sampler) (default: AlwaysOff)
TraceIDRatioBased samples a given fraction of traces. Fractions >= 1 will
always sample. Fractions < 0 are treated as zero. To respect the
parent trace's `SampledFlag`, the `TraceIDRatioBased` sampler should be used
as a delegate of a `Parent` sampler.
WithBatcher registers the exporter with the TracerProvider using a
BatchSpanProcessor configured with the passed opts.
WithBatchTimeout returns a BatchSpanProcessorOption that configures the
maximum delay allowed for a BatchSpanProcessor before it will export any
held span (whether the queue is full or not).
WithBlocking returns a BatchSpanProcessorOption that configures a
BatchSpanProcessor to wait for enqueue operations to succeed instead of
dropping data when the queue is full.
WithExportTimeout returns a BatchSpanProcessorOption that configures the
amount of time a BatchSpanProcessor waits for an exporter to export before
abandoning the export.
WithIDGenerator returns a TracerProviderOption that will configure the
IDGenerator g as a TracerProvider's IDGenerator. The configured IDGenerator
is used by the Tracers the TracerProvider creates to generate new Span and
Trace IDs.
If this option is not used, the TracerProvider will use a random number
IDGenerator by default.
WithLocalParentNotSampled sets the sampler for the case of local parent
which is not sampled.
WithLocalParentSampled sets the sampler for the case of sampled local parent.
WithMaxExportBatchSize returns a BatchSpanProcessorOption that configures
the maximum export batch size allowed for a BatchSpanProcessor.
WithMaxQueueSize returns a BatchSpanProcessorOption that configures the
maximum queue size allowed for a BatchSpanProcessor.
WithRawSpanLimits returns a TracerProviderOption that configures a
TracerProvider to use these limits. These limits bound any Span created by
a Tracer from the TracerProvider.
The limits will be used as-is. Zero or negative values will not be changed
to the default value like WithSpanLimits does. Setting a limit to zero will
effectively disable the related resource it limits and setting to a
negative value will mean that resource is unlimited. Consequentially, this
means that the zero-value SpanLimits will disable all span resources.
Because of this, limits should be constructed using NewSpanLimits and
updated accordingly.
If this or WithSpanLimits are not provided, the TracerProvider will use the
limits defined by environment variables, or the defaults if unset. Refer to
the NewSpanLimits documentation for information about this relationship.
WithRemoteParentNotSampled sets the sampler for the case of remote parent
which is not sampled.
WithRemoteParentSampled sets the sampler for the case of sampled remote parent.
WithResource returns a TracerProviderOption that will configure the
Resource r as a TracerProvider's Resource. The configured Resource is
referenced by all the Tracers the TracerProvider creates. It represents the
entity producing telemetry.
If this option is not used, the TracerProvider will use the
resource.Default() Resource by default.
WithSampler returns a TracerProviderOption that will configure the Sampler
s as a TracerProvider's Sampler. The configured Sampler is used by the
Tracers the TracerProvider creates to make their sampling decisions for the
Spans they create.
This option overrides the Sampler configured through the OTEL_TRACES_SAMPLER
and OTEL_TRACES_SAMPLER_ARG environment variables. If this option is not used
and the sampler is not configured through environment variables or the environment
contains invalid/unsupported configuration, the TracerProvider will use a
ParentBased(AlwaysSample) Sampler by default.
WithSpanLimits returns a TracerProviderOption that configures a
TracerProvider to use the SpanLimits sl. These SpanLimits bound any Span
created by a Tracer from the TracerProvider.
If any field of sl is zero or negative it will be replaced with the default
value for that field.
If this or WithRawSpanLimits are not provided, the TracerProvider will use
the limits defined by environment variables, or the defaults if unset.
Refer to the NewSpanLimits documentation for information about this
relationship.
Deprecated: Use WithRawSpanLimits instead which allows setting unlimited
and zero limits. This option will be kept until the next major version
incremented release.
WithSpanProcessor registers the SpanProcessor with a TracerProvider.
WithSyncer registers the exporter with the TracerProvider using a
SimpleSpanProcessor.
This is not recommended for production use. The synchronous nature of the
SimpleSpanProcessor that will wrap the exporter make it good for testing,
debugging, or showing examples of other feature, but it will be slow and
have a high computation resource usage overhead. The WithBatcher option is
recommended for production use instead.
Package-Level Constants (total 13)
DefaultAttributeCountLimit is the default maximum number of attributes
a span can have.
DefaultAttributePerEventCountLimit is the default maximum number of
attributes a span event can have.
DefaultAttributePerLinkCountLimit is the default maximum number of
attributes a span link can have.
DefaultAttributeValueLengthLimit is the default maximum allowed
attribute value length, unlimited.
DefaultEventCountLimit is the default maximum number of events a span
can have.
DefaultExportTimeout is the duration after which an export is cancelled, in milliseconds.
DefaultLinkCountLimit is the default maximum number of links a span can
have.
Defaults for BatchSpanProcessorOptions.
Defaults for BatchSpanProcessorOptions.
DefaultScheduleDelay is the delay interval between two consecutive exports, in milliseconds.
Drop will not record the span and all attributes/events will be dropped.
RecordAndSample indicates the span's IsRecording method returns true and trace.FlagsSampled flag
must be set.
RecordOnly indicates the span's IsRecording method returns true, but trace.FlagsSampled flag
must not be set.
 |
The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64) Golds is a Go 101 project developed by Tapir Liu. PR and bug reports are welcome and can be submitted to the issue list. Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds. |