telemetry

package
v0.0.0-...-3c9a48d Latest Latest
Warning

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

 Go to latest Published: Dec 4, 2024 License: Apache-2.0 Imports: 39 Imported by: 0

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"

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

	// The base64-encoded, protobuf-marshalled Buildkit LLB op payload that this
	// span represents.
	LLBOpAttr = "dagger.io/llb.op"

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

	// 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{}
View Source 
var Propagator = propagation.NewCompositeTextMapPropagator(
	propagation.Baggage{},
	propagation.TraceContext{},
)

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 

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 

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

func ConfiguredMetricExporter 

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

func ConfiguredSpanExporter 

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

func DataPointsToPB 

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 

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 

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

ExemplarsToPB returns a slice of OTLP ExemplarsToPB generated from exemplars.

func ExponentialHistogramDataPointBucketsToPB 

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

ExponentialHistogramDataPointBucketsToPB returns an OTLP ExponentialHistogramDataPoint_Buckets generated from bucket.

func ExponentialHistogramDataPointsToPB 

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

ExponentialHistogramDataPointsToPB returns a slice of OTLP ExponentialHistogramDataPoint generated from dPts.

func ExponentialHistogramToPB 

func ExponentialHistogramToPB[N int64 | float64](h metricdata.ExponentialHistogram[N]) (*otlpmetricsv1.Metric_ExponentialHistogram, error)

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

func GaugeToPB 

func GaugeToPB[N int64 | float64](g metricdata.Gauge[N]) *otlpmetricsv1.Metric_Gauge

GaugeToPB returns an OTLP Metric_Gauge generated from g.

func HistogramDataPointsToPB 

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

HistogramDataPointsToPB returns a slice of OTLP HistogramDataPoint generated from dPts.

func HistogramToPB 

func HistogramToPB[N int64 | float64](h metricdata.Histogram[N]) (*otlpmetricsv1.Metric_Histogram, error)

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 

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

func InstrumentationScopeToPB 

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 

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

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

func LogKeyValuesFromPB 

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

func LogValueFromPB 

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

func LogValueToPB 

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

Value transforms an attribute Value into an OTLP AnyValue.

func Logger 

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

Logger returns a logger with the given name.

func LoggerProvider 

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

LoggerProvider returns the LoggerProvider from the context.

func LogsFromPB 

func LogsFromPB(resLogs []*otlplogsv1.ResourceLogs) []sdklog.Record

func LogsToPB 

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

func Meter 

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

func MeterProvider 

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

func MetricsFromPB 

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

func MetricsToPB 

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 

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 

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 

func PropagationEnv(ctx context.Context) []string

func QuantileValuesToPB 

func QuantileValuesToPB(quantiles []metricdata.QuantileValue) []*otlpmetricsv1.SummaryDataPoint_ValueAtQuantile

QuantileValuesToPB returns a slice of OTLP SummaryDataPoint_ValueAtQuantile generated from quantiles.

func ResourceFromPB 

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

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

func ResourceMetricsFromPB 

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

func ResourceMetricsToPB 

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 

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

ResourcePtrToPB transforms a *Resource into an OTLP Resource.

func ResourceToPB 

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

ResourceToPB transforms a Resource into an OTLP Resource.

func ScopeMetricsFromPB 

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

func ScopeMetricsToPB 

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 

func SnapshotSpan(span sdktrace.ReadOnlySpan) sdktrace.ReadOnlySpan

func SpanEventsFromPB 

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

SpanEventsFromPB transforms OTLP span events to span Events.

func SpanEventsToPB 

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

SpanEventsToPB transforms span Events to an OTLP span events.

func SpanLinksFromPB 

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

SpanLinksFromPB transforms OTLP span links to span Links.

func SpanLinksToPB 

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

linksFromPB transforms span Links to OTLP span linksFromPB.

func SpansFromPB 

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

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

func SpansToPB 

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

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

func StatusCodeFromPB 

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

status transform a OTLP span status into span code.

func SumToPB 

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 

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

SummaryDataPointsToPB returns a slice of OTLP SummaryDataPoint generated from dPts.

func SummaryToPB 

func SummaryToPB(s metricdata.Summary) *otlpmetricsv1.Metric_Summary

SummaryToPB returns an OTLP Metric_Summary generated from s.

func TemporalityToPB 

func TemporalityToPB(t metricdata.Temporality) (otlpmetricsv1.AggregationTemporality, error)

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 

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 

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

WithLoggerProvider returns a new context with the given LoggerProvider.

func WithMeterProvider 

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 

type EnvCarrier struct {
	System bool
	Env    []string
}

func NewEnvCarrier 

func NewEnvCarrier(system bool) *EnvCarrier

func (*EnvCarrier) Get 

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

func (*EnvCarrier) Keys 

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

func (*EnvCarrier) Set 

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

type FilterLiveSpansExporter 

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 

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 

func NewLiveSpanProcessor(exp sdktrace.SpanExporter) *LiveSpanProcessor

func (*LiveSpanProcessor) OnStart 

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

type LogForwarder 

type LogForwarder struct {
	Processors []sdklog.Processor
}

func (LogForwarder) Export 

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

func (LogForwarder) ForceFlush 

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

func (LogForwarder) Shutdown 

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

type SpanForwarder 

type SpanForwarder struct {
	Processors []sdktrace.SpanProcessor
}

func (SpanForwarder) ExportSpans 

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

func (SpanForwarder) Shutdown 

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

type SpanStreams 

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

SpanStreams contains the stdout and stderr for a span.

func SpanStdio 

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 

func (sl SpanStreams) Close() error

Calling Close closes both streams.

type Writer 

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

Writer is an io.Writer that emits log records.

func (*Writer) Emit 

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 

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

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.