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 ¶
- func StartSpan[T any](telemetryContext TelemetryContext, options SpanOptions, ...) (T, error)
- func StartTypedSpan[R any](starter TypedSpanStarter, name string, attributes SpanAttributes, ...) (R, error)
- type AttributeValue
- type HistogramOptions
- type InMemoryTelemetryContext
- func (recorder *InMemoryTelemetryContext) Counter(name string, options InstrumentOptions) TelemetryCounter
- func (recorder *InMemoryTelemetryContext) Extract(carrier TelemetryCarrier) TelemetryContext
- func (recorder *InMemoryTelemetryContext) GetMetrics() []RecordedTelemetryMeasurement
- func (recorder *InMemoryTelemetryContext) GetSpans() []RecordedTelemetrySpan
- func (recorder *InMemoryTelemetryContext) Histogram(name string, options HistogramOptions) TelemetryHistogram
- func (recorder *InMemoryTelemetryContext) Inject(context TelemetryContext) TelemetryCarrier
- func (recorder *InMemoryTelemetryContext) StartSpan(options SpanOptions, callback func(TelemetrySpan) error) error
- func (recorder *InMemoryTelemetryContext) UpDownCounter(name string, options InstrumentOptions) TelemetryUpDownCounter
- type InstrumentOptions
- type RecordedTelemetryEvent
- type RecordedTelemetryLink
- type RecordedTelemetryMeasurement
- type RecordedTelemetrySpan
- type SpanAttributes
- type SpanLink
- type SpanOptions
- type SpanStatus
- type SpanStatusCode
- type SpanStatusError
- type TelemetryAttributeCardinality
- type TelemetryAttributeDefinition
- type TelemetryAttributeMetadata
- type TelemetryAttributeType
- type TelemetryCarrier
- type TelemetryContext
- type TelemetryCounter
- type TelemetryEventAttributeDefinition
- type TelemetryEventDefinition
- type TelemetryHistogram
- type TelemetryMetricAttributeDefinition
- type TelemetryMetricDefinition
- type TelemetryMetricKind
- type TelemetryMetrics
- type TelemetryParentDefinition
- type TelemetryParentKind
- type TelemetryPropagation
- type TelemetrySchemaDefinition
- type TelemetrySpan
- type TelemetrySpanDefinition
- type TelemetrySpanStatusDefinition
- type TelemetryStartAttributeDefinition
- type TelemetryUpDownCounter
- type TypedSpanStarter
- type TypedTelemetryMetrics
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 ¶
func (recorder *InMemoryTelemetryContext) Inject(context TelemetryContext) TelemetryCarrier
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 ¶
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 ¶
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 ¶
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 ¶
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. |