telemetry

Documentation

Index

• Constants
• Variables
• func Close()
• func ConfiguredSpanExporter(ctx context.Context) (sdktrace.SpanExporter, bool)
• func Encapsulate() trace.SpanStartOption
• func End(span trace.Span, fn func() error)
• func Flush(ctx context.Context)
• func Init(ctx context.Context, cfg Config) context.Context
• func InitEmbedded(ctx context.Context, res *resource.Resource) context.Context
• func Internal() trace.SpanStartOption
• func NewBatchSpanProcessor(exporter trace.SpanExporter, options ...BatchSpanProcessorOption) *batchSpanProcessor
• func NewSimpleSpanProcessor(exporter trace.SpanExporter) *simpleSpanProcessor
• func OtelConfigured() bool
• type BatchSpanProcessorOption
  • 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
• type BatchSpanProcessorOptions
• type Config
• type LiveSpanProcessor
• type ProxyTraceProvider
  • func NewProxyTraceProvider(tp *tracesdk.TracerProvider, onUpdate func(trace.Span)) *ProxyTraceProvider
  • func (tp *ProxyTraceProvider) ForceFlush(ctx context.Context) error
  • func (tp *ProxyTraceProvider) Shutdown(ctx context.Context) error
  • func (tp *ProxyTraceProvider) Tracer(name string, options ...trace.TracerOption) trace.Tracer
• type ProxyTracer
  • func (t ProxyTracer) Start(ctx context.Context, spanName string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
• type TracerUpdater

Constants

const (
	DagDigestAttr = "dagger.io/dag.digest"

	DagInputsAttr = "dagger.io/dag.inputs"
	DagOutputAttr = "dagger.io/dag.output"

	CachedAttr   = "dagger.io/dag.cached"
	CanceledAttr = "dagger.io/dag.canceled"
	InternalAttr = "dagger.io/dag.internal"

	DagCallAttr = "dagger.io/dag.call"

	LLBOpAttr = "dagger.io/llb.op"

	// Hide child spans by default.
	UIEncapsulateAttr = "dagger.io/ui.encapsulate"

	// The parent span of this task. Might not need this at all, if we want to
	// just rely on span parent, but the thinking is the span parent could be
	// pretty brittle.
	TaskParentAttr = "dagger.io/task.parent"

	// Progress bars.
	ProgressCurrentAttr = "dagger.io/progress.current"
	ProgressTotalAttr   = "dagger.io/progress.total"
)

const (
	DefaultMaxQueueSize       = 2048
	DefaultScheduleDelay      = 5000
	DefaultExportTimeout      = 30000
	DefaultMaxExportBatchSize = 512
)

Defaults for BatchSpanProcessorOptions.

const NearlyImmediate = 100 * time.Millisecond

NearlyImmediate is 100ms, below which has diminishing returns in terms of visual perception vs. performance cost.

Variables

var SpanProcessors = []sdktrace.SpanProcessor{}

Functions

func Close

func Close()

Close shuts down the global OpenTelemetry providers, flushing any remaining data to the configured exporters.

func ConfiguredSpanExporter

func ConfiguredSpanExporter(ctx context.Context) (sdktrace.SpanExporter, bool)

func Encapsulate

func Encapsulate() trace.SpanStartOption

Encapsulate can be applied to a span to indicate that this span should collapse its children by default.

func End

func End(span trace.Span, fn func() error)

End is a helper to end a span with an error if the function returns an error.

It is optimized for use as a defer one-liner with a function that has a named error return value, conventionally `rerr`.

defer telemetry.End(span, func() error { return rerr })

func Flush

func Flush(ctx context.Context)

Flush drains telemetry data, and is typically called just before a client goes away.

NB: now that we wait for all spans to complete, this is less necessary, but it seems wise to keep it anyway, as the spots where it are needed are hard to find.

func Init

func Init(ctx context.Context, cfg Config) context.Context

Init sets up the global OpenTelemetry providers tracing, logging, and someday metrics providers. It is called by the CLI, the engine, and the container shim, so it needs to be versatile.

func InitEmbedded

func InitEmbedded(ctx context.Context, res *resource.Resource) context.Context

func Internal

func Internal() trace.SpanStartOption

Internal can be applied to a span to indicate that this span should not be shown to the user by default.

func NewBatchSpanProcessor

func NewBatchSpanProcessor(exporter trace.SpanExporter, options ...BatchSpanProcessorOption) *batchSpanProcessor

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.

func NewSimpleSpanProcessor

func NewSimpleSpanProcessor(exporter trace.SpanExporter) *simpleSpanProcessor

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 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 BatchSpanProcessor is recommended for production use instead.

func OtelConfigured

func OtelConfigured() bool

Types

type BatchSpanProcessorOption

type BatchSpanProcessorOption func(o *BatchSpanProcessorOptions)

BatchSpanProcessorOption configures a BatchSpanProcessor.

func WithBatchTimeout

func WithBatchTimeout(delay time.Duration) BatchSpanProcessorOption

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).

func WithBlocking

func WithBlocking() BatchSpanProcessorOption

WithBlocking returns a BatchSpanProcessorOption that configures a BatchSpanProcessor to wait for enqueue operations to succeed instead of dropping data when the queue is full.

func WithExportTimeout

func WithExportTimeout(timeout time.Duration) BatchSpanProcessorOption

WithExportTimeout returns a BatchSpanProcessorOption that configures the amount of time a BatchSpanProcessor waits for an exporter to export before abandoning the export.

func WithMaxExportBatchSize

func WithMaxExportBatchSize(size int) BatchSpanProcessorOption

WithMaxExportBatchSize returns a BatchSpanProcessorOption that configures the maximum export batch size allowed for a BatchSpanProcessor.

func WithMaxQueueSize

func WithMaxQueueSize(size int) BatchSpanProcessorOption

WithMaxQueueSize returns a BatchSpanProcessorOption that configures the maximum queue size allowed for a BatchSpanProcessor.

type BatchSpanProcessorOptions

type BatchSpanProcessorOptions struct {
	// 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.
	MaxQueueSize int

	// 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.
	BatchTimeout time.Duration

	// 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.
	ExportTimeout time.Duration

	// 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.
	MaxExportBatchSize int

	// 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.
	BlockOnQueueFull bool
}

BatchSpanProcessorOptions is configuration settings for a BatchSpanProcessor.

type Config

type Config struct {
	// Auto-detect exporters from OTEL_* env variables.
	Detect bool

	// LiveTraceExporters are exporters that can receive updates for spans at runtime,
	// rather than waiting until the span ends.
	//
	// Example: TUI, Cloud
	LiveTraceExporters []sdktrace.SpanExporter

	// BatchedTraceExporters are exporters that receive spans in batches, after the
	// spans have ended.
	//
	// Example: Honeycomb, Jaeger, etc.
	BatchedTraceExporters []sdktrace.SpanExporter

	// Resource is the resource describing this component and runtime
	// environment.
	Resource *resource.Resource
}

type LiveSpanProcessor

type LiveSpanProcessor interface {
	sdktrace.SpanProcessor

	// OnUpdate method enqueues a trace.ReadOnlySpan for later processing.
	OnUpdate(s sdktrace.ReadOnlySpan)
}

LiveSpanProcessor is a SpanProcessor that can additionally receive updates for a span at runtime, rather than waiting until the span ends.

type ProxyTraceProvider

type ProxyTraceProvider struct {
	embedded.TracerProvider
	// contains filtered or unexported fields
}

func NewProxyTraceProvider

func NewProxyTraceProvider(tp *tracesdk.TracerProvider, onUpdate func(trace.Span)) *ProxyTraceProvider

func (*ProxyTraceProvider) ForceFlush

func (tp *ProxyTraceProvider) ForceFlush(ctx context.Context) error

func (*ProxyTraceProvider) Shutdown

func (tp *ProxyTraceProvider) Shutdown(ctx context.Context) error

func (*ProxyTraceProvider) Tracer

func (tp *ProxyTraceProvider) Tracer(name string, options ...trace.TracerOption) trace.Tracer

type ProxyTracer

type ProxyTracer struct {
	embedded.Tracer
	// contains filtered or unexported fields
}

func (ProxyTracer) Start

func (t ProxyTracer) Start(ctx context.Context, spanName string, opts ...trace.SpanStartOption) (context.Context, trace.Span)

type TracerUpdater

type TracerUpdater interface {
	// contains filtered or unexported methods
}