telemetry

package
v0.15.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 29, 2025 License: Apache-2.0 Imports: 40 Imported by: 21

Documentation

Index

Constants

View Source
const (
	// The base64-encoded, protobuf-marshalled callpbv1.Call that this span
	// represents.
	DagCallAttr = "dagger.io/dag.call"

	// The digest of the protobuf-marshalled Call that this span represents.
	//
	// This value acts as a node ID in the conceptual DAG.
	DagDigestAttr = "dagger.io/dag.digest"

	// The list of DAG digests that the span depends on.
	//
	// This is not currently used by the UI, but it could be used to drive higher
	// level DAG walking processes without having to unmarshal the full call.
	DagInputsAttr = "dagger.io/dag.inputs"

	// The DAG call digest that the call returned, if the call returned an
	// Object.
	//
	// This information is used to simplify values in the UI by showing their
	// highest-level creator. For example, if foo().bar() returns a().b().c(), we
	// will show foo().bar() instead of a().b().c() as it will be a more
	// recognizable value to the user.
	DagOutputAttr = "dagger.io/dag.output"

	// Indicates that this span is "internal" and can be hidden by default.
	//
	// Internal spans may typically be revealed with a toggle.
	UIInternalAttr = "dagger.io/ui.internal"

	// Hide child spans by default.
	//
	// Encapsulated child spans may typically be revealed if the parent span errors.
	UIEncapsulateAttr = "dagger.io/ui.encapsulate"

	// Hide span by default.
	//
	// This is functionally the same as UIEncapsulateAttr, but is instead set
	// on a child instead of a parent.
	UIEncapsulatedAttr = "dagger.io/ui.encapsulated"

	// Substitute the span for its children and move its logs to its parent.
	UIPassthroughAttr = "dagger.io/ui.passthrough" //nolint: gosec // lol

	// Indicates that this span was a cache hit and did nothing.
	CachedAttr = "dagger.io/dag.cached"

	// A list of completed effect IDs.
	//
	// This is primarily used for cached ops - since we don't see a span for a
	// cached op's inputs, we'll just say they completed by listing all of them
	// in this attribute.
	EffectsCompletedAttr = "dagger.io/effects.completed"

	// Indicates that this span was interrupted.
	CanceledAttr = "dagger.io/dag.canceled"

	// The IDs of effects which will be correlated to this span.
	//
	// This is typically a list of LLB operation digests, but can be any string.
	EffectIDsAttr = "dagger.io/effect.ids"

	// The ID of the effect that this span represents.
	EffectIDAttr = "dagger.io/effect.id"

	// The amount of progress that needs to be reached.
	ProgressTotalAttr = "dagger.io/progress.total"

	// Current value for the progress.
	ProgressCurrentAttr = "dagger.io/progress.current"

	// Indicates the units for the progress numbers.
	ProgressUnitsAttr = "dagger.io/progress.units"

	// The stdio stream a log corresponds to (1 for stdout, 2 for stderr).
	StdioStreamAttr = "stdio.stream"

	// Indicates whether the log stream has ended.
	StdioEOFAttr = "stdio.eof"

	// Indicates whether the log should be shown globally.
	LogsGlobalAttr = "dagger.io/logs.global"

	// OTel metric attribute so we can correlate metrics with spans
	MetricsSpanIDAttr = "dagger.io/metrics.span"

	// OTel metric attribute so we can correlate metrics with traces
	MetricsTraceIDAttr = "dagger.io/metrics.trace"
)

The following attributes are used by the UI to interpret spans and control their behavior in the UI.

View Source
const (
	// OTel metric for number of bytes read from disk by a container, as parsed from its cgroup
	IOStatDiskReadBytes = "dagger.io/metrics.iostat.disk.readbytes"

	// OTel metric for number of bytes written to disk by a container, as parsed from its cgroup
	IOStatDiskWriteBytes = "dagger.io/metrics.iostat.disk.writebytes"

	// OTel metric for number of microseconds SOME tasks in a cgroup were stalled on IO due to resource contention
	IOStatPressureSomeTotal = "dagger.io/metrics.iostat.pressure.some.total"

	// OTel metric for number of microseconds of all CPU usage of a container, as parsed from its cgroup
	CPUStatUsage = "dagger.io/metrics.cpustat.usage"

	// OTel metric for number of microseconds of CPU time spent in user mode by a container, as parsed from its cgroup
	CPUStatUser = "dagger.io/metrics.cpustat.user"

	// OTel metric for number of microseconds of CPU time spent in system mode by a container, as parsed from its cgroup
	CPUStatSystem = "dagger.io/metrics.cpustat.system"

	// OTel metric for number of microseconds SOME tasks in a cgroup were stalled on CPU due to resource contention
	CPUStatPressureSomeTotal = "dagger.io/metrics.cpustat.pressure.some.total"

	// OTel metric for number of microseconds ALL tasks in a cgroup were stalled on CPU due to resource contention
	CPUStatPressureFullTotal = "dagger.io/metrics.cpustat.pressure.full.total"

	// OTel metric for bytes of memory currently consumed by this cgroup and its descendents
	MemoryCurrentBytes = "dagger.io/metrics.memory.current"

	// OTel metric for peak memory bytes consumed by this cgroup and its descendents
	MemoryPeakBytes = "dagger.io/metrics.memory.peak"

	// OTel metric for number of bytes received by a container, pulled from buildkit's network namespace representation
	NetstatRxBytes = "dagger.io/metrics.netstat.rx.bytes"

	// OTel metric for number of packets received by a container, pulled from buildkit's network namespace representation
	NetstatRxPackets = "dagger.io/metrics.netstat.rx.packets"

	// OTel metric for number of received packets dropped by a container, pulled from buildkit's network namespace representation
	NetstatRxDropped = "dagger.io/metrics.netstat.rx.dropped"

	// OTel metric for number of bytes transmitted by a container, pulled from buildkit's network namespace representation
	NetstatTxBytes = "dagger.io/metrics.netstat.tx.bytes"

	// OTel metric for number of packets transmitted by a container, pulled from buildkit's network namespace representation
	NetstatTxPackets = "dagger.io/metrics.netstat.tx.packets"

	// OTel metric for number of transmitted packets dropped by a container, pulled from buildkit's network namespace representation
	NetstatTxDropped = "dagger.io/metrics.netstat.tx.dropped"

	// Bytes unit for OTel metrics
	ByteUnitName = "byte"

	// Microseconds unit for OTel metrics
	MicrosecondUnitName = "us"
)
View Source
const NearlyImmediate = 100 * time.Millisecond

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

Variables

View Source
var LiveTracesEnabled = os.Getenv("OTEL_EXPORTER_OTLP_TRACES_LIVE") != ""

LiveTracesEnabled indicates that the configured OTEL_* exporter should be sent live span telemetry.

View Source
var LogProcessors = []sdklog.Processor{}
View Source
var MetricExporters = []sdkmetric.Exporter{}

Propagator is a composite propagator of everything we could possibly want.

Do not rely on otel.GetTextMapPropagator() - it's prone to change from a random import.

View Source
var Resource *resource.Resource
View Source
var SpanProcessors = []sdktrace.SpanProcessor{}

Functions

func AttributesFromProto added in v0.11.8

func AttributesFromProto(attrs []*otlpcommonv1.KeyValue) []attribute.KeyValue

AttributesFromProto transforms a slice of OTLP attribute key-values into a slice of KeyValues

func Close

func Close()

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

func ConfiguredLogExporter added in v0.11.8

func ConfiguredLogExporter(ctx context.Context) (sdklog.Exporter, bool)

func ConfiguredMetricExporter added in v0.13.6

func ConfiguredMetricExporter(ctx context.Context) (sdkmetric.Exporter, bool)

func ConfiguredSpanExporter

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

func DataPointsToPB added in v0.13.6

func DataPointsToPB[N int64 | float64](dPts []metricdata.DataPoint[N]) []*otlpmetricsv1.NumberDataPoint

DataPointsToPB returns a slice of OTLP NumberDataPoint generated from dPts.

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 Encapsulated added in v0.11.8

func Encapsulated() trace.SpanStartOption

Encapsulated can be applied to a child span to indicate that it should be collapsed 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 ExemplarsToPB added in v0.13.6

func ExemplarsToPB[N int64 | float64](exemplars []metricdata.Exemplar[N]) []*otlpmetricsv1.Exemplar

ExemplarsToPB returns a slice of OTLP ExemplarsToPB generated from exemplars.

func ExponentialHistogramDataPointBucketsToPB added in v0.13.6

func ExponentialHistogramDataPointBucketsToPB(bucket metricdata.ExponentialBucket) *otlpmetricsv1.ExponentialHistogramDataPoint_Buckets

ExponentialHistogramDataPointBucketsToPB returns an OTLP ExponentialHistogramDataPoint_Buckets generated from bucket.

func ExponentialHistogramDataPointsToPB added in v0.13.6

func ExponentialHistogramDataPointsToPB[N int64 | float64](dPts []metricdata.ExponentialHistogramDataPoint[N]) []*otlpmetricsv1.ExponentialHistogramDataPoint

ExponentialHistogramDataPointsToPB returns a slice of OTLP ExponentialHistogramDataPoint generated from dPts.

func ExponentialHistogramToPB added in v0.13.6

ExponentialHistogramToPB returns an OTLP Metric_ExponentialHistogram generated from h. An error is returned if the temporality of h is unknown.

func GaugeToPB added in v0.13.6

GaugeToPB returns an OTLP Metric_Gauge generated from g.

func HistogramDataPointsToPB added in v0.13.6

func HistogramDataPointsToPB[N int64 | float64](dPts []metricdata.HistogramDataPoint[N]) []*otlpmetricsv1.HistogramDataPoint

HistogramDataPointsToPB returns a slice of OTLP HistogramDataPoint generated from dPts.

func HistogramToPB added in v0.13.6

HistogramToPB returns an OTLP Metric_Histogram generated from h. An error is returned if the temporality of h is unknown.

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 InstrumentationScopeFromPB added in v0.12.5

func InstrumentationScopeFromPB(is *otlpcommonv1.InstrumentationScope) instrumentation.Scope

func InstrumentationScopeToPB added in v0.13.1

func InstrumentationScopeToPB(il instrumentation.Scope) *otlpcommonv1.InstrumentationScope

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 KeyValues added in v0.11.8

func KeyValues(attrs []attribute.KeyValue) []*otlpcommonv1.KeyValue

KeyValues transforms a slice of attribute KeyValues into OTLP key-values.

func LogKeyValuesFromPB added in v0.12.5

func LogKeyValuesFromPB(kvs []*otlpcommonv1.KeyValue) []log.KeyValue

func LogValueFromPB added in v0.12.5

func LogValueFromPB(v *otlpcommonv1.AnyValue) log.Value

func LogValueToPB added in v0.12.5

func LogValueToPB(v log.Value) *otlpcommonv1.AnyValue

Value transforms an attribute Value into an OTLP AnyValue.

func Logger added in v0.11.8

func Logger(ctx context.Context, name string) log.Logger

Logger returns a logger with the given name.

func LoggerProvider added in v0.12.5

func LoggerProvider(ctx context.Context) *sdklog.LoggerProvider

LoggerProvider returns the LoggerProvider from the context.

func LogsToPB added in v0.11.8

func LogsToPB(sdl []sdklog.Record) []*otlplogsv1.ResourceLogs

func Meter added in v0.13.6

func Meter(ctx context.Context, name string) metric.Meter

func MeterProvider added in v0.13.6

func MeterProvider(ctx context.Context) *sdkmetric.MeterProvider

func MetricsFromPB added in v0.13.6

func MetricsFromPB(pbMetrics []*otlpmetricsv1.Metric) ([]metricdata.Metrics, error)

func MetricsToPB added in v0.13.6

func MetricsToPB(ms []metricdata.Metrics) ([]*otlpmetricsv1.Metric, error)

Metrics returns a slice of OTLP Metric generated from ms. If ms contains invalid metric values, an error will be returned along with a slice that contains partial OTLP Metrics.

func NewWriter added in v0.11.8

func NewWriter(ctx context.Context, name string, attrs ...log.KeyValue) io.Writer

NewWriter returns a new Writer that emits log records with the given logger name and attributes.

func Passthrough added in v0.11.8

func Passthrough() trace.SpanStartOption

Passthrough can be applied to a span to cause the UI to skip over it and show its children instead.

func PropagationEnv added in v0.11.8

func PropagationEnv(ctx context.Context) []string

func QuantileValuesToPB added in v0.13.6

QuantileValuesToPB returns a slice of OTLP SummaryDataPoint_ValueAtQuantile generated from quantiles.

func ReexportLogsFromPB added in v0.15.0

func ReexportLogsFromPB(ctx context.Context, exp sdklog.Exporter, req *collogspb.ExportLogsServiceRequest) error

func ResourceFromPB added in v0.13.1

func ResourceFromPB(schemaURL string, pb *otlpresourcev1.Resource) *resource.Resource

ResourceFromPB creates a *resource.Resource from a schema URL and protobuf encoded attributes.

func ResourceMetricsFromPB added in v0.13.6

func ResourceMetricsFromPB(pbResourceMetrics *otlpmetricsv1.ResourceMetrics) (*metricdata.ResourceMetrics, error)

func ResourceMetricsToPB added in v0.13.6

func ResourceMetricsToPB(rm *metricdata.ResourceMetrics) (*otlpmetricsv1.ResourceMetrics, error)

ResourceMetrics returns an OTLP ResourceMetrics generated from rm. If rm contains invalid ScopeMetrics, an error will be returned along with an OTLP ResourceMetrics that contains partial OTLP ScopeMetrics.

func ResourcePtrToPB added in v0.13.1

func ResourcePtrToPB(r *resource.Resource) *otlpresourcev1.Resource

ResourcePtrToPB transforms a *Resource into an OTLP Resource.

func ResourceToPB added in v0.13.1

func ResourceToPB(r resource.Resource) *otlpresourcev1.Resource

ResourceToPB transforms a Resource into an OTLP Resource.

func Resume added in v0.15.0

func ScopeMetricsFromPB added in v0.13.6

func ScopeMetricsFromPB(pbScopeMetrics []*otlpmetricsv1.ScopeMetrics) ([]metricdata.ScopeMetrics, error)

func ScopeMetricsToPB added in v0.13.6

func ScopeMetricsToPB(sms []metricdata.ScopeMetrics) ([]*otlpmetricsv1.ScopeMetrics, error)

ScopeMetrics returns a slice of OTLP ScopeMetrics generated from sms. If sms contains invalid metric values, an error will be returned along with a slice that contains partial OTLP ScopeMetrics.

func SnapshotSpan added in v0.11.8

func SnapshotSpan(span sdktrace.ReadOnlySpan) sdktrace.ReadOnlySpan

func SpanEventsFromPB added in v0.12.5

func SpanEventsFromPB(es []*otlptracev1.Span_Event) []sdktrace.Event

SpanEventsFromPB transforms OTLP span events to span Events.

func SpanEventsToPB added in v0.12.5

func SpanEventsToPB(es []sdktrace.Event) []*otlptracev1.Span_Event

SpanEventsToPB transforms span Events to an OTLP span events.

func SpanLinksFromPB added in v0.12.5

func SpanLinksFromPB(links []*otlptracev1.Span_Link) []sdktrace.Link

SpanLinksFromPB transforms OTLP span links to span Links.

func SpanLinksToPB added in v0.12.5

func SpanLinksToPB(links []sdktrace.Link) []*otlptracev1.Span_Link

linksFromPB transforms span Links to OTLP span linksFromPB.

func SpansFromPB added in v0.11.8

func SpansFromPB(sdl []*otlptracev1.ResourceSpans) []sdktrace.ReadOnlySpan

SpansFromPB transforms a slice of OTLP ResourceSpans into a slice of ReadOnlySpans.

func SpansToPB added in v0.11.8

func SpansToPB(sdl []sdktrace.ReadOnlySpan) []*otlptracev1.ResourceSpans

SpansToPB transforms a slice of OpenTelemetry spans into a slice of OTLP ResourceSpans.

func StatusCodeFromPB added in v0.12.5

func StatusCodeFromPB(st *otlptracev1.Status) codes.Code

status transform a OTLP span status into span code.

func SumToPB added in v0.13.6

func SumToPB[N int64 | float64](s metricdata.Sum[N]) (*otlpmetricsv1.Metric_Sum, error)

SumToPB returns an OTLP Metric_Sum generated from s. An error is returned if the temporality of s is unknown.

func SummaryDataPointsToPB added in v0.13.6

func SummaryDataPointsToPB(dPts []metricdata.SummaryDataPoint) []*otlpmetricsv1.SummaryDataPoint

SummaryDataPointsToPB returns a slice of OTLP SummaryDataPoint generated from dPts.

func SummaryToPB added in v0.13.6

SummaryToPB returns an OTLP Metric_Summary generated from s.

func TemporalityToPB added in v0.13.6

TemporalityToPB returns an OTLP AggregationTemporality generated from t. If t is unknown, an error is returned along with the invalid AggregationTemporality_AGGREGATION_TEMPORALITY_UNSPECIFIED.

func Tracer added in v0.12.5

func Tracer(ctx context.Context, lib string) trace.Tracer

Tracer returns a Tracer for the given library using the provider from the current span.

func WithLoggerProvider added in v0.12.5

func WithLoggerProvider(ctx context.Context, provider *sdklog.LoggerProvider) context.Context

WithLoggerProvider returns a new context with the given LoggerProvider.

func WithMeterProvider added in v0.13.6

func WithMeterProvider(ctx context.Context, provider *sdkmetric.MeterProvider) context.Context

Types

type Config

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

	// SpanProcessors are processors to prepend to the telemetry pipeline.
	SpanProcessors []sdktrace.SpanProcessor

	// 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

	// LiveLogExporters are exporters that receive logs in batches of ~100ms.
	LiveLogExporters []sdklog.Exporter

	// LiveMetricExporters are exporters that receive metrics in batches of ~1s.
	LiveMetricExporters []sdkmetric.Exporter

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

type EnvCarrier added in v0.11.8

type EnvCarrier struct {
	System bool
	Env    []string
}

func NewEnvCarrier added in v0.11.8

func NewEnvCarrier(system bool) *EnvCarrier

func (*EnvCarrier) Get added in v0.11.8

func (c *EnvCarrier) Get(key string) string

func (*EnvCarrier) Keys added in v0.11.8

func (c *EnvCarrier) Keys() []string

func (*EnvCarrier) Set added in v0.11.8

func (c *EnvCarrier) Set(key, val string)

type FilterLiveSpansExporter added in v0.11.8

type FilterLiveSpansExporter struct {
	sdktrace.SpanExporter
}

FilterLiveSpansExporter is a SpanExporter that filters out spans that are currently running, as indicated by an end time older than its start time (typically year 1753).

func (FilterLiveSpansExporter) ExportSpans added in v0.11.8

func (exp FilterLiveSpansExporter) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error

ExportSpans passes each span to the span processor's OnEnd hook so that it can be batched and emitted more efficiently.

type LiveSpanProcessor

type LiveSpanProcessor struct {
	sdktrace.SpanProcessor
}

LiveSpanProcessor is a SpanProcessor whose OnStart calls OnEnd on the underlying SpanProcessor in order to send live telemetry.

func NewLiveSpanProcessor added in v0.11.8

func NewLiveSpanProcessor(exp sdktrace.SpanExporter) *LiveSpanProcessor

func (*LiveSpanProcessor) OnStart added in v0.11.8

func (p *LiveSpanProcessor) OnStart(ctx context.Context, span sdktrace.ReadWriteSpan)

type LogForwarder added in v0.11.8

type LogForwarder struct {
	Processors []sdklog.Processor
}

func (LogForwarder) Export added in v0.11.8

func (m LogForwarder) Export(ctx context.Context, logs []sdklog.Record) error

func (LogForwarder) ForceFlush added in v0.11.8

func (m LogForwarder) ForceFlush(ctx context.Context) error

func (LogForwarder) Shutdown added in v0.11.8

func (m LogForwarder) Shutdown(ctx context.Context) error

type SpanForwarder added in v0.11.8

type SpanForwarder struct {
	Processors []sdktrace.SpanProcessor
}

func (SpanForwarder) ExportSpans added in v0.11.8

func (m SpanForwarder) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error

func (SpanForwarder) Shutdown added in v0.11.8

func (m SpanForwarder) Shutdown(ctx context.Context) error

type SpanStreams added in v0.11.8

type SpanStreams struct {
	Stdout io.WriteCloser
	Stderr io.WriteCloser
}

SpanStreams contains the stdout and stderr for a span.

func SpanStdio added in v0.11.8

func SpanStdio(ctx context.Context, name string, attrs ...log.KeyValue) SpanStreams

SpanStdio returns a pair of io.WriteClosers which will send log records with stdio.stream=1 for stdout and stdio.stream=2 for stderr. Closing either of them will send a log record for that stream with an empty body and stdio.eof=true.

SpanStdio should be used when a span represents a process that writes to stdout/stderr and terminates them with an EOF, to confirm that all data has been received. It should not be used for general-purpose logging.

Both streams must be closed to ensure that draining completes.

func (SpanStreams) Close added in v0.11.8

func (sl SpanStreams) Close() error

Calling Close closes both streams.

type Writer added in v0.11.8

type Writer struct {
	// contains filtered or unexported fields
}

Writer is an io.Writer that emits log records.

func (*Writer) Emit added in v0.11.8

func (w *Writer) Emit(body log.Value, attrs ...log.KeyValue)

Emit sends a log record with the given body and additional attributes.

func (*Writer) Write added in v0.11.8

func (w *Writer) Write(p []byte) (int, error)

Write emits a log record with the given payload as a string body.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL