telemetry

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package telemetry provides backend-neutral span carriers, propagation, links, metrics and in-memory recording. Ports packages/telemetry/src/index.ts and packages/telemetry/src/noop.ts.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func StartSpan

func StartSpan[T any](telemetryContext TelemetryContext, options SpanOptions, callback func(TelemetrySpan) (T, error)) (T, error)

StartSpan starts a span from telemetryContext and returns the callback's result, as upstream startSpan<T> resolves to it. A rejected callback returns its error and the zero value. Go interface methods cannot be generic, so the typed result travels through this function over TelemetryContext.StartSpan.

func StartTypedSpan

func StartTypedSpan[R any](starter TypedSpanStarter, name string, attributes SpanAttributes, callback func(span TelemetrySpan, startChildSpan TypedSpanStarter) (R, error)) (R, error)

StartTypedSpan starts a schema span through starter and returns the callback's result, as an upstream TypedSpanStarter call resolves to it. A rejected callback returns its error and the zero value. The child starter passed to callback is bound to the new span.

Types

type AttributeValue

type AttributeValue = any

AttributeValue is a string, number, boolean, or slice of those values.

type HistogramOptions

type HistogramOptions struct {
	InstrumentOptions
	Boundaries []float64
}

HistogramOptions describes a histogram. Boundaries are finite, strictly increasing bucket hints; a nil slice is upstream's undefined and an empty slice a defined empty boundary list.

type InMemoryTelemetryContext

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

InMemoryTelemetryContext records spans and measurements without an external backend. It implements TelemetryContext, TelemetryPropagation and TelemetryMetrics. Create a fresh instance to isolate tests or independent recording scopes (memory.ts:190-197).

func NewInMemoryTelemetryContext

func NewInMemoryTelemetryContext() *InMemoryTelemetryContext

NewInMemoryTelemetryContext is `new InMemoryTelemetryContext()`: an empty recorder; its zero value is equally ready to use.

func (*InMemoryTelemetryContext) Counter

func (recorder *InMemoryTelemetryContext) Counter(name string, options InstrumentOptions) TelemetryCounter

Counter creates a counter that records non-negative finite increments. Metadata is copied when the instrument is created, and an instrument whose metadata is invalid records nothing.

func (*InMemoryTelemetryContext) Extract

func (recorder *InMemoryTelemetryContext) Extract(carrier TelemetryCarrier) TelemetryContext

Extract returns a parent whose spans record the carrier's span as their parent context. An unrecognized or malformed carrier falls back to this recorder's root context. Only the two carrier keys are read, so a carrier with extra keys is accepted and its extras dropped.

func (*InMemoryTelemetryContext) GetMetrics

func (recorder *InMemoryTelemetryContext) GetMetrics() []RecordedTelemetryMeasurement

GetMetrics returns detached measurements in recording order, without aggregation.

func (*InMemoryTelemetryContext) GetSpans

func (recorder *InMemoryTelemetryContext) GetSpans() []RecordedTelemetrySpan

GetSpans returns detached snapshots in span-start order.

func (*InMemoryTelemetryContext) Histogram

func (recorder *InMemoryTelemetryContext) Histogram(name string, options HistogramOptions) TelemetryHistogram

Histogram creates a histogram that records finite signed values. Invalid boundaries (non-finite or not strictly increasing) leave an instrument that records nothing.

func (*InMemoryTelemetryContext) Inject

Inject returns a detached carrier for a span or extracted parent of any in-memory recorder, including a settled span, and nil for any other context: the root recorder, a no-op context or an unsupported one.

func (*InMemoryTelemetryContext) StartSpan

func (recorder *InMemoryTelemetryContext) StartSpan(options SpanOptions, callback func(TelemetrySpan) error) error

StartSpan invokes and waits for callback, recording its settlement even when it returns an error or panics.

func (*InMemoryTelemetryContext) UpDownCounter

func (recorder *InMemoryTelemetryContext) UpDownCounter(name string, options InstrumentOptions) TelemetryUpDownCounter

UpDownCounter creates a counter that records finite signed increments.

type InstrumentOptions

type InstrumentOptions struct {
	Description *string
	Unit        *string
}

InstrumentOptions describes an instrument. A nil Description or Unit is upstream's undefined, which a recorder omits; a pointer to the empty string is a defined empty string.

type RecordedTelemetryEvent

type RecordedTelemetryEvent struct {
	Name       string
	Attributes SpanAttributes
}

RecordedTelemetryEvent is a detached span event snapshot.

type RecordedTelemetryLink struct {
	Context    TelemetryCarrier
	Attributes SpanAttributes
}

RecordedTelemetryLink is a detached span link snapshot: the target's carrier and the link's copied attributes.

type RecordedTelemetryMeasurement

type RecordedTelemetryMeasurement struct {
	Kind        TelemetryMetricKind
	Name        string
	Description *string
	Unit        *string
	Boundaries  []float64
	Value       float64
	Attributes  SpanAttributes
	Context     TelemetryCarrier
}

RecordedTelemetryMeasurement is a detached measurement snapshot in recording order. Description, Unit and Boundaries are nil (upstream's absent members) when the instrument declared none; Context is the exemplar's carrier, nil (upstream's null) when the measurement had no recognized exemplar.

type RecordedTelemetrySpan

type RecordedTelemetrySpan struct {
	ID            int
	ParentID      *int
	Context       TelemetryCarrier
	ParentContext TelemetryCarrier
	Links         []RecordedTelemetryLink
	Name          string
	Attributes    SpanAttributes
	Events        []RecordedTelemetryEvent
	Status        SpanStatus
	Settled       bool
	EndSequence   *int
}

RecordedTelemetrySpan is a detached snapshot in span-start order. ParentID is the local parent's ID, nil for roots and for parents owned by another recorder. Context is the span's carrier; ParentContext is the parent's carrier, nil (upstream's null) for a root.

type SpanAttributes

type SpanAttributes map[string]AttributeValue

SpanAttributes carries named telemetry values. A nil value is upstream's undefined: recorders omit it.

type SpanLink struct {
	Context    TelemetryContext
	Attributes SpanAttributes
}

SpanLink relates a span to the work Context names without changing the span's parent. A nil Attributes is upstream's absent attributes.

type SpanOptions

type SpanOptions struct {
	Name       string
	Attributes SpanAttributes
	Links      []SpanLink
}

SpanOptions supplies a span's name, initial attributes and initial links.

type SpanStatus

type SpanStatus struct {
	Status SpanStatusCode
	Error  *SpanStatusError
}

SpanStatus records success or failure and optional error details.

type SpanStatusCode

type SpanStatusCode string

SpanStatusCode is the final status of a span.

const (
	SpanStatusCodeOK    SpanStatusCode = "ok"
	SpanStatusCodeError SpanStatusCode = "error"
)

type SpanStatusError

type SpanStatusError struct{ Name, Message string }

SpanStatusError describes an optional error status.

type TelemetryAttributeCardinality

type TelemetryAttributeCardinality string

TelemetryAttributeCardinality classifies how many distinct values an attribute takes.

const (
	TelemetryAttributeCardinalityLow  TelemetryAttributeCardinality = "low"
	TelemetryAttributeCardinalityHigh TelemetryAttributeCardinality = "high"
)

type TelemetryAttributeDefinition

type TelemetryAttributeDefinition struct {
	TelemetryAttributeMetadata
	Type          TelemetryAttributeType `json:"type"`
	Values        []AttributeValue       `json:"values,omitzero"`
	ElementValues []AttributeValue       `json:"elementValues,omitzero"`
	Examples      []AttributeValue       `json:"examples,omitzero"`
}

TelemetryAttributeDefinition declares one attribute's type and optional closed value set.

Values applies to scalar types and ElementValues to array types; Examples holds values of Type. A nil slice is an absent member and an empty slice serializes as [], as JSON.stringify writes the schema object.

type TelemetryAttributeMetadata

type TelemetryAttributeMetadata struct {
	Description string                        `json:"description"`
	Sensitive   *bool                         `json:"sensitive,omitempty"`
	Cardinality TelemetryAttributeCardinality `json:"cardinality,omitempty"`
}

TelemetryAttributeMetadata documents one schema attribute.

type TelemetryAttributeType

type TelemetryAttributeType string

TelemetryAttributeType names the value type of a schema attribute.

const (
	TelemetryAttributeTypeString       TelemetryAttributeType = "string"
	TelemetryAttributeTypeNumber       TelemetryAttributeType = "number"
	TelemetryAttributeTypeBoolean      TelemetryAttributeType = "boolean"
	TelemetryAttributeTypeStringArray  TelemetryAttributeType = "string[]"
	TelemetryAttributeTypeNumberArray  TelemetryAttributeType = "number[]"
	TelemetryAttributeTypeBooleanArray TelemetryAttributeType = "boolean[]"
)

type TelemetryCarrier

type TelemetryCarrier map[string]string

TelemetryCarrier is opaque, JSON-serializable, adapter-owned propagation data. A nil carrier is upstream's undefined: Inject returns it for a context with nothing to propagate and Extract accepts it as an absent carrier.

type TelemetryContext

type TelemetryContext interface {
	StartSpan(SpanOptions, func(TelemetrySpan) error) error
}

TelemetryContext starts child spans and waits for their callbacks.

type TelemetryCounter

type TelemetryCounter interface {
	Add(value float64, attributes SpanAttributes)
}

TelemetryCounter is a monotonic instrument: it accepts non-negative finite increments.

type TelemetryEventAttributeDefinition

type TelemetryEventAttributeDefinition = TelemetryStartAttributeDefinition

TelemetryEventAttributeDefinition is an attribute of a span event; it has the start-attribute shape.

type TelemetryEventDefinition

type TelemetryEventDefinition struct {
	Description string                                       `json:"description"`
	Attributes  map[string]TelemetryEventAttributeDefinition `json:"attributes"`
}

TelemetryEventDefinition declares one span event.

type TelemetryHistogram

type TelemetryHistogram interface {
	Record(value float64, attributes SpanAttributes, context TelemetryContext)
}

TelemetryHistogram records finite signed values. A nil context is upstream's omitted context; otherwise the measurement is correlated with that context, called an exemplar.

type TelemetryMetricAttributeDefinition

type TelemetryMetricAttributeDefinition = TelemetryStartAttributeDefinition

TelemetryMetricAttributeDefinition is a start-attribute definition whose cardinality, when annotated, is low.

type TelemetryMetricDefinition

type TelemetryMetricDefinition struct {
	Description string                                        `json:"description"`
	Unit        *string                                       `json:"unit,omitempty"`
	Attributes  map[string]TelemetryMetricAttributeDefinition `json:"attributes"`
	Kind        TelemetryMetricKind                           `json:"kind"`
	Boundaries  []float64                                     `json:"boundaries,omitzero"`
}

TelemetryMetricDefinition is serializable instrument metadata: its kind, description, optional unit and required/optional low-cardinality attributes. Only histograms may declare Boundaries; a nil slice is absent and an empty slice serializes as [].

type TelemetryMetricKind

type TelemetryMetricKind string

TelemetryMetricKind names the instrument a metric definition declares.

const (
	TelemetryMetricKindCounter       TelemetryMetricKind = "counter"
	TelemetryMetricKindUpDownCounter TelemetryMetricKind = "upDownCounter"
	TelemetryMetricKindHistogram     TelemetryMetricKind = "histogram"
)

type TelemetryMetrics

type TelemetryMetrics interface {
	Counter(name string, options InstrumentOptions) TelemetryCounter
	UpDownCounter(name string, options InstrumentOptions) TelemetryUpDownCounter
	Histogram(name string, options HistogramOptions) TelemetryHistogram
}

TelemetryMetrics is the optional adapter capability that creates instruments. Factories and recording methods are synchronous, passive and never panic.

var NoopTelemetryMetrics TelemetryMetrics = noopTelemetryMetrics{}

NoopTelemetryMetrics is the shared metric capability whose instruments never inspect or retain metadata, measurements or contexts. Each factory returns the same shared instrument.

type TelemetryParentDefinition

type TelemetryParentDefinition struct {
	Kind  TelemetryParentKind `json:"kind"`
	Spans []string            `json:"spans,omitzero"`
}

TelemetryParentDefinition declares a span's allowed parents. Spans applies to TelemetryParentKindSpans; a nil slice is absent and an empty slice serializes as [].

type TelemetryParentKind

type TelemetryParentKind string

TelemetryParentKind selects which parents a span accepts.

const (
	TelemetryParentKindAny            TelemetryParentKind = "any"
	TelemetryParentKindRootOrExternal TelemetryParentKind = "root_or_external"
	TelemetryParentKindSpans          TelemetryParentKind = "spans"
)

type TelemetryPropagation

type TelemetryPropagation interface {
	Inject(TelemetryContext) TelemetryCarrier
	Extract(TelemetryCarrier) TelemetryContext
}

TelemetryPropagation is the optional transport capability implemented by the application's telemetry adapter. Both methods are synchronous, passive and never panic. Inject returns a detached carrier, or nil for roots, no-op contexts and contexts the adapter does not recognize. Extract returns a receiver-owned parent and falls back to the adapter's root for an absent, invalid, unknown or unreadable carrier.

var NoopTelemetryPropagation TelemetryPropagation = noopTelemetryPropagation{}

NoopTelemetryPropagation is the shared propagation capability that neither inspects nor retains its inputs: Inject returns nil and Extract returns NoopTelemetryContext.

type TelemetrySchemaDefinition

type TelemetrySchemaDefinition struct {
	Version int                                  `json:"version"`
	Spans   map[string]TelemetrySpanDefinition   `json:"spans"`
	Metrics map[string]TelemetryMetricDefinition `json:"metrics,omitzero"`
}

TelemetrySchemaDefinition is serializable telemetry schema data. A nil Metrics is absent and an empty map serializes as {}.

func DefineTelemetrySchema

func DefineTelemetrySchema(schema *TelemetrySchemaDefinition) *TelemetrySchemaDefinition

DefineTelemetrySchema returns schema unchanged. It is the identity helper for serializable telemetry schema data.

type TelemetrySpan

type TelemetrySpan interface {
	TelemetryContext
	AddLink(SpanLink)
	AddEvent(string, SpanAttributes)
	SetAttributes(SpanAttributes)
	SetStatus(SpanStatus)
}

TelemetrySpan records attributes, events and status while active.

var NoopTelemetryContext TelemetrySpan = noopTelemetrySpan{}

NoopTelemetryContext is the shared parent used without a recording backend.

type TelemetrySpanDefinition

type TelemetrySpanDefinition struct {
	Description     string                                       `json:"description"`
	Parents         TelemetryParentDefinition                    `json:"parents"`
	StartAttributes map[string]TelemetryStartAttributeDefinition `json:"startAttributes"`
	EndAttributes   map[string]TelemetryAttributeDefinition      `json:"endAttributes"`
	Events          map[string]TelemetryEventDefinition          `json:"events,omitzero"`
	Status          TelemetrySpanStatusDefinition                `json:"status"`
}

TelemetrySpanDefinition declares one span name. A nil Events is absent and an empty map serializes as {}.

type TelemetrySpanStatusDefinition

type TelemetrySpanStatusDefinition struct {
	Default   SpanStatusCode `json:"default"`
	ErrorWhen string         `json:"errorWhen"`
}

TelemetrySpanStatusDefinition documents a span's default status and when it reports an error.

type TelemetryStartAttributeDefinition

type TelemetryStartAttributeDefinition struct {
	TelemetryAttributeDefinition
	Required bool `json:"required"`
}

TelemetryStartAttributeDefinition is an attribute supplied when a span starts.

type TelemetryUpDownCounter

type TelemetryUpDownCounter = TelemetryCounter

TelemetryUpDownCounter is an instrument that accepts finite signed increments. Upstream declares it structurally identical to TelemetryCounter, so Go names the same method set instead of declaring a duplicate interface.

type TypedSpanStarter

type TypedSpanStarter func(name string, attributes SpanAttributes, callback func(span TelemetrySpan, startChildSpan TypedSpanStarter) error) error

TypedSpanStarter starts a span by schema span name under one explicit parent context. The callback receives the span and a starter bound to that span for its children.

func CreateTypedSpanStarter

func CreateTypedSpanStarter(telemetryContext TelemetryContext, _ *TelemetrySchemaDefinition, _ ...*TelemetrySchemaDefinition) TypedSpanStarter

CreateTypedSpanStarter binds an explicit parent context to the combined span vocabulary of one or more schemas. The schemas are not read: as upstream, no runtime schema validation is performed. At least one schema is required, as upstream's non-empty TelemetrySchemaTuple.

type TypedTelemetryMetrics

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

TypedTelemetryMetrics creates the instruments of one or more schemas, passing each instrument its schema metadata.

func CreateTypedMetrics

func CreateTypedMetrics(metrics TelemetryMetrics, schema *TelemetrySchemaDefinition, schemas ...*TelemetrySchemaDefinition) *TypedTelemetryMetrics

CreateTypedMetrics binds instrument names, kinds and metadata to one or more schemas. The schemas' metric definitions are read and retained, as upstream does; no attribute validation is performed. At least one schema is required, as upstream's non-empty tuple.

func (*TypedTelemetryMetrics) Counter

func (typed *TypedTelemetryMetrics) Counter(name string) TelemetryCounter

Counter returns the adapter's counter for name with the schema's description and unit.

func (*TypedTelemetryMetrics) Histogram

func (typed *TypedTelemetryMetrics) Histogram(name string) TelemetryHistogram

Histogram returns the adapter's histogram for name with the schema's description, unit and boundaries.

func (*TypedTelemetryMetrics) UpDownCounter

func (typed *TypedTelemetryMetrics) UpDownCounter(name string) TelemetryUpDownCounter

UpDownCounter returns the adapter's up-down counter for name with the schema's description and unit.

Directories

Path Synopsis
Package telemetrytest holds runner-independent conformance cases for telemetry.TelemetryContext adapters.
Package telemetrytest holds runner-independent conformance cases for telemetry.TelemetryContext adapters.

Jump to

Keyboard shortcuts

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