telemetry

type AttributeValue ¶

type AttributeValue = any

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

type InMemoryTelemetryContext ¶

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

InMemoryTelemetryContext records spans without an external backend. Its zero value is ready to use, so a composite literal is its constructor (stubgen:omit NewInMemoryTelemetryContext).

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

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

type RecordedTelemetryEvent ¶

type RecordedTelemetryEvent struct {
	Name       string
	Attributes SpanAttributes
}

RecordedTelemetryEvent is a detached span event snapshot.

type RecordedTelemetrySpan ¶

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

RecordedTelemetrySpan is a detached snapshot in span-start order.

type SpanAttributes ¶

type SpanAttributes map[string]AttributeValue

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

type SpanOptions ¶

type SpanOptions struct {
	Name       string
	Attributes SpanAttributes
}

SpanOptions supplies a span's name and initial attributes.

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 TelemetryContext ¶

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

TelemetryContext starts child spans and waits for their callbacks.

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 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 TelemetrySchemaDefinition ¶

type TelemetrySchemaDefinition struct {
	Version int                                `json:"version"`
	Spans   map[string]TelemetrySpanDefinition `json:"spans"`
}

TelemetrySchemaDefinition is serializable telemetry schema data.

func DefineTelemetrySchema(schema *TelemetrySchemaDefinition) *TelemetrySchemaDefinition

type TelemetrySpan ¶

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

TelemetrySpan records attributes, events and status while active.

var NoopTelemetryContext TelemetrySpan = noopTelemetrySpan{}

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 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(telemetryContext TelemetryContext, _ ...*TelemetrySchemaDefinition) TypedSpanStarter