telemetry

package
v1.6.4 Latest Latest
Warning

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

 Go to latest Published: Feb 20, 2025 License: Apache-2.0 Imports: 33 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	TracerAttributeNameNodeID = "nodeid"
	TracerAttributeNameJobID  = "jobid"
)

Variables

View Source 
var (
	// DurationMsBuckets defines boundaries for millisecond-scale operations
	// Covers spans from 1ms to 10s with exponential growth
	// Useful for API calls, quick DB operations, network requests
	DurationMsBuckets = []float64{
		0.001,
		0.005,
		0.01,
		0.05,
		0.1,
		0.5,
		1,
		5,
		10,
	}

	// DurationSecBuckets defines boundaries for second-scale operations
	// Covers spans from 1s to 1h with exponential growth
	// Useful for long-running computations, batch jobs
	DurationSecBuckets = []float64{
		1,
		5,
		15,
		30,
		60,
		300,
		900,
		1800,
		3600,
	}

	// BytesBuckets defines boundaries for data size measurements
	// Covers spans from 1KB to 1GB with exponential growth
	// Useful for payload sizes, file operations
	BytesBuckets = []float64{
		1024,
		32768,
		1048576,
		33554432,
		134217728,
		536870912,
		1073741824,
	}

	// CountBuckets defines boundaries for count-based measurements
	// Covers spans from 1 to 10000 with exponential growth
	// Useful for batch sizes, queue lengths, connection pools
	CountBuckets = []float64{
		1,
		2,
		5,
		10,
		20,
		50,
		100,
		200,
		500,
		1000,
		2000,
		5000,
		10000,
	}
)
View Source 
var (
	SubOperationKey = attribute.Key("sub_operation")
)

Functions

func AddJobIDToBaggage added in v1.5.0 

func AddJobIDToBaggage(ctx context.Context, jobID string) context.Context

func AddNodeIDToBaggage added in v1.5.0 

func AddNodeIDToBaggage(ctx context.Context, nodeID string) context.Context

func Cleanup 

func Cleanup() error

Cleanup flushes the remaining traces and metrics in memory to the exporter and releases any telemetry resources.

func GetTraceClient added in v1.2.0 

func GetTraceClient() (client otlptrace.Client, err error)

func GetTracer added in v1.5.0 

func GetTracer() oteltrace.Tracer

func Must added in v1.0.4 

func Must[T any](val T, err error) T

func NewRootSpan added in v1.5.0 

func NewRootSpan(ctx context.Context, t oteltrace.Tracer, name string) (context.Context, oteltrace.Span)

func NewSpan added in v1.5.0 

func NewSpan(ctx context.Context, t oteltrace.Tracer, name string, opts ...oteltrace.SpanStartOption) (context.Context, oteltrace.Span)

func RecordErrorOnSpan 

func RecordErrorOnSpan(span trace.Span) func(error) error

RecordErrorOnSpan records the error returned by the function in the given span. Should be used like `return RecordErrorOnSpan(span)(c.client.NetworkRemove(ctx, networkID))`

func RecordErrorOnSpanOneChannel 

func RecordErrorOnSpanOneChannel[T any](span trace.Span) func(<-chan T, error) (<-chan T, error)

RecordErrorOnSpanOneChannel is similar to RecordErrorOnSpanTwo but one parameter is a channel.

func RecordErrorOnSpanReadCloserAndClose 

func RecordErrorOnSpanReadCloserAndClose(span trace.Span) func(io.ReadCloser, error) (io.ReadCloser, error)

RecordErrorOnSpanReadCloserAndClose is similar to RecordError but takes an additional parameter that is an io.ReadCloser. The function will end the given span when the io.ReadCloser is closed. The caller is expected to _not_ call end on the span.

func RecordErrorOnSpanReadCloserTwoAndClose 

func RecordErrorOnSpanReadCloserTwoAndClose[T any](span trace.Span) func(io.ReadCloser, T, error) (io.ReadCloser, T, error)

RecordErrorOnSpanReadCloserTwoAndClose is similar to RecordErrorOnSpanReadCloserAndClose but takes an additional parameter.

func RecordErrorOnSpanThree 

func RecordErrorOnSpanThree[T any, S any](span trace.Span) func(T, S, error) (T, S, error)

RecordErrorOnSpanThree is similar to RecordError but the function being called takes an additional parameter.

func RecordErrorOnSpanTwo 

func RecordErrorOnSpanTwo[T any](span trace.Span) func(T, error) (T, error)

RecordErrorOnSpanTwo is similar to RecordErrorOnSpan but the function being called takes an additional parameter.

func RecordErrorOnSpanTwoChannels 

func RecordErrorOnSpanTwoChannels[T any](span trace.Span) func(<-chan T, <-chan error) (<-chan T, <-chan error)

RecordErrorOnSpanTwoChannels is similar to RecordErrorOnSpanTwo but both parameters are channels.

func SetupFromEnvs 

func SetupFromEnvs()

func Span added in v1.5.0 

func Span(ctx context.Context, spanName string, opts ...oteltrace.SpanStartOption) (context.Context, oteltrace.Span)

Span creates and starts a new span, and a context containing it. For more information see the otel.Tracer.Start(...) docs: https://pkg.go.dev/go.opentelemetry.io/otel/trace#Tracer ctx: the context to use for the span tracerName: the name of the service that the span is for - will be prefixed with "tracer/". Will create a new one if one with the same name does not exist spanName: the name of the span, inside the service opts: additional options to configure the span from trace.SpanStartOption

func Timer added in v1.2.1 

func Timer(
	ctx context.Context,
	durationRecorder metric.Int64Histogram,
	attrs ...attribute.KeyValue,
) func() time.Duration

Timer is a function to record a duration. Calling it starts the timer, calling the returned function will record the duration.

Types

type Counter added in v1.2.1 

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

Counter is a synchronous Instrument which supports non-negative increments Example uses for Counter: - count the number of bytes received - count the number of requests completed - count the number of accounts created - count the number of checkpoints run - count the number of HTTP 5xx errors

func NewCounter added in v1.2.1 

func NewCounter(meter metric.Meter, name string, description string) (*Counter, error)

func (*Counter) Add added in v1.2.1 

func (c *Counter) Add(ctx context.Context, num int64, attrs ...attribute.KeyValue)

func (*Counter) Inc added in v1.2.1 

func (c *Counter) Inc(ctx context.Context, attrs ...attribute.KeyValue)

type Gauge added in v1.2.1 

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

Gauge is a synchronous Instrument which supports increments and decrements. Note: if the value is monotonically increasing, use Counter instead. Example uses for Gauge: - the number of active requests - the number of items in a queue

func NewGauge added in v1.2.1 

func NewGauge(meter metric.Meter, name string, description string) (*Gauge, error)

func (*Gauge) Dec added in v1.2.1 

func (g *Gauge) Dec(ctx context.Context, attrs ...attribute.KeyValue)

func (*Gauge) Inc added in v1.2.1 

func (g *Gauge) Inc(ctx context.Context, attrs ...attribute.KeyValue)

type MetricRecorder added in v1.0.4 

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

MetricRecorder is a helper for recording metrics. It provides methods to record latency, counters, and gauges with consistent attribute handling. The recorder aggregates metrics internally and only publishes them when Done() is called.

IMPORTANT: MetricRecorder is not thread-safe. It should only be used by a single goroutine. If you need to record metrics from multiple goroutines, create separate recorders for each.

Example usage: 

recorder := NewMetricRecorder(attribute.String("operation", "process"))
defer recorder.Done(ctx, durationHist) // Records total duration and all aggregated metrics

// In a loop:
msg := queue.Receive()
recorder.Latency(ctx, dequeueHist, "dequeue") // Aggregates dequeue time

if err := process(msg); err != nil {
    recorder.Error("processing_failed")
    return err
}
recorder.Latency(ctx, processHist, "process") // Aggregates process time
recorder.Count(ctx, successCounter) // Aggregates success count

func NewMetricRecorder added in v1.0.4 

func NewMetricRecorder(attrs ...attribute.KeyValue) *MetricRecorder

NewMetricRecorder creates a new recorder with base attributes that will be included in all metric recordings. The recorder will aggregate metrics until Done() is called.

func (*MetricRecorder) AddAttributes added in v1.6.2 

func (r *MetricRecorder) AddAttributes(attrs ...attribute.KeyValue)

AddAttributes adds attributes for all future measurements.

func (*MetricRecorder) Attributes added in v1.6.2 

func (r *MetricRecorder) Attributes() []attribute.KeyValue

Attributes returns the current attributes.

func (*MetricRecorder) AttributesOpt added in v1.6.2 

func (r *MetricRecorder) AttributesOpt() metric.MeasurementOption

AttributesOpt returns the current attributes as a slice of options.

func (*MetricRecorder) Count added in v1.6.2 

func (r *MetricRecorder) Count(ctx context.Context, c metric.Int64Counter)

Count aggregates counter increments by 1. The aggregated count will be published with base attributes when Done() is called.

func (*MetricRecorder) CountAndHistogram added in v1.6.2 

func (r *MetricRecorder) CountAndHistogram(ctx context.Context,
	counter metric.Int64Counter, histogram metric.Float64Histogram, value float64)

CountAndHistogram increments a counter and records a histogram value in one call

func (*MetricRecorder) CountN added in v1.6.2 

func (r *MetricRecorder) CountN(ctx context.Context, c metric.Int64Counter, n int64)

CountN aggregates counter increments by n. The aggregated count will be published with base attributes when Done() is called.

func (*MetricRecorder) Done added in v1.6.2 

func (r *MetricRecorder) Done(ctx context.Context, h metric.Float64Histogram, attrs ...attribute.KeyValue)

Done records the total duration since recorder creation and publishes all aggregated metrics. This should typically be deferred immediately after creating the recorder. Additional attributes can be provided and will be merged with base attributes.

func (*MetricRecorder) DoneWithoutTotalDuration added in v1.6.2 

func (r *MetricRecorder) DoneWithoutTotalDuration(ctx context.Context, attrs ...attribute.KeyValue)

DoneWithoutTotalDuration publishes all aggregated metrics without recording total duration. This should typically be deferred immediately after creating the recorder. Additional attributes can be provided and will be merged with base attributes.

func (*MetricRecorder) Duration added in v1.6.2 

func (r *MetricRecorder) Duration(ctx context.Context, h metric.Float64Histogram, duration time.Duration)

Duration records a duration for a histogram. The aggregated value will be published when Done() is called.

func (*MetricRecorder) Error added in v1.6.2 

func (r *MetricRecorder) Error(err error)

Error records an error type using OpenTelemetry semantic conventions

func (*MetricRecorder) ErrorString added in v1.6.2 

func (r *MetricRecorder) ErrorString(typ string)

ErrorString records an error type using OpenTelemetry semantic conventions

func (*MetricRecorder) Gauge added in v1.6.2 

func (r *MetricRecorder) Gauge(ctx context.Context, g metric.Float64UpDownCounter, val float64)

Gauge sets gauge value. Unlike Count and Latency, gauge values are published immediately.

func (*MetricRecorder) Histogram added in v1.6.2 

func (r *MetricRecorder) Histogram(ctx context.Context, h metric.Float64Histogram, value float64)

Histogram aggregates values for a histogram by adding them together. The total aggregated value will be published with base attributes when Done() is called.

func (*MetricRecorder) Latency added in v1.6.2 

func (r *MetricRecorder) Latency(ctx context.Context, h metric.Float64Histogram, subOperation string)

Latency aggregates the time since the last operation or start for a given sub-operation. If this is the first operation, it records the latency since start. The aggregated latencies will be published when Done() is called.

func (*MetricRecorder) ResetLastOperation added in v1.6.2 

func (r *MetricRecorder) ResetLastOperation()

ResetLastOperation resets the timestamp used for next Latency calculation

func (*MetricRecorder) WithAttributes added in v1.6.2 

func (r *MetricRecorder) WithAttributes(attrs ...attribute.KeyValue) *MetricRecorder

WithAttributes adds attributes for all future measurements.

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.