signal

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jun 26, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package signal holds the OTel data model, signal-neutral types shared across metrics, logs, traces, and profiles: the Signal enum, TenantID, and the typed attribute identity primitives (Value, KeyValue, Attributes, SeriesID).

Per-signal point types live under sub-packages: signal/metric (the first vertical), and signal/log, signal/trace, signal/profile (later verticals).

Index

Constants

This section is empty.

Variables

View Source 
var ErrMalformed = errors.New("signal: malformed attribute encoding")

ErrMalformed is returned when a serialized Value or Attributes fails to parse.

View Source 
var ErrUnknownSignal = errors.New("signal: unknown signal kind")

ErrUnknownSignal is returned by ParseSignal for an unrecognized name.

Functions

func AppendKeyValueHashInput 

func AppendKeyValueHashInput(dst, key []byte, v Value) []byte

AppendKeyValueHashInput appends the canonical hash pre-image of a single attribute — a length-prefixed key followed by the type-tagged value — to dst. It is the per-entry unit of Attributes.AppendHashInput, exposed so an ingest path can build a series' hash by merging several already-sorted attribute sources in one pass, without first materializing the combined sorted slice. Entries must be appended in sorted-by-key order and prefixed with their count (see Attributes.AppendHashInput) for the result to match.

func AppendValue 

func AppendValue(dst []byte, v Value) []byte

AppendValue appends the canonical, type-tagged binary encoding of v to dst and returns it. The encoding is the same one used in the identity hash pre-image, so it preserves type (int 5, "5" and 5.0 encode differently) and round-trips through DecodeValue. Engines intern AppendValue(nil, v) to get a value's symbol id.

Types

type Attributes 

type Attributes []KeyValue

Attributes is an OTel attribute set, kept **sorted by key**. It models a Resource, Scope, or data-point attribute set; its Attributes.Hash is the series identity. Construct one with NewAttributes.

func DecodeAttributes 

func DecodeAttributes(src []byte) (Attributes, int, error)

DecodeAttributes parses the canonical binary form produced by Attributes.AppendHashInput. Keys and string/byte values alias src.

func NewAttributes 

func NewAttributes(kvs ...KeyValue) Attributes

NewAttributes returns the attributes sorted by key (sorted in place, stable). Keys are assumed unique; the stable sort makes even malformed duplicate-key input hash deterministically.

func (Attributes) AppendHashInput 

func (a Attributes) AppendHashInput(dst []byte) []byte

AppendHashInput appends the canonical, type-tagged hash pre-image of the (sorted) attribute set to dst and returns it. Callers that hash many series reuse one buffer to stay zero-alloc. The encoding is unambiguous: each key is length-prefixed and each value carries its kind tag, so no two distinct attribute sets share a pre-image.

func (Attributes) Clone 

func (a Attributes) Clone() Attributes

Clone returns a deep copy of the attribute set (including keys and nested values).

func (Attributes) Equal 

func (a Attributes) Equal(other Attributes) bool

Equal reports whether two sorted attribute sets are deeply equal.

func (Attributes) Get 

func (a Attributes) Get(key []byte) (Value, bool)

Get returns the value for key and whether it is present.

func (Attributes) Hash 

func (a Attributes) Hash() SeriesID

Hash returns the content-addressed SeriesID of the sorted attribute set.

type KeyValue 

type KeyValue struct {
	Key   []byte
	Value Value
}

KeyValue is one attribute: a key and its typed value. Keys are unique within an Attributes set and case-sensitive. The key is held as []byte to keep interning and projection allocation-free.

type Resource 

type Resource struct {
	SchemaURL  []byte
	Attributes Attributes
}

Resource is an OTel Resource: the entity (service instance, host, …) that produced the telemetry. Its attributes are identifying — any differing key/value is a different resource — and schema_url is part of its identity.

func (Resource) AppendHashInput 

func (r Resource) AppendHashInput(dst []byte) []byte

AppendHashInput appends the canonical, length-delimited hash pre-image of the resource (schema_url ‖ attributes) to dst. It is the resource segment of Series.AppendHashInput, exposed so ingest paths can build a series hash from hoisted, per-group prefixes without rebuilding the resource segment per point.

func (Resource) Clone 

func (r Resource) Clone() Resource

Clone returns a deep copy of the resource.

func (Resource) Equal 

func (r Resource) Equal(o Resource) bool

Equal reports whether two resources are deeply equal.

type Scope 

type Scope struct {
	Name       []byte
	Version    []byte
	SchemaURL  []byte
	Attributes Attributes
}

Scope is an OTel InstrumentationScope: the logical instrumentation unit (name, version, schema_url, attributes) that produced the telemetry. A distinct tuple is a distinct grouping, so all four fields are identifying.

func (Scope) AppendHashInput 

func (s Scope) AppendHashInput(dst []byte) []byte

AppendHashInput appends the canonical, length-delimited hash pre-image of the scope (name ‖ version ‖ schema_url ‖ attributes) to dst. It is the scope segment of Series.AppendHashInput, exposed so ingest paths can hoist it per scope group.

func (Scope) Clone 

func (s Scope) Clone() Scope

Clone returns a deep copy of the scope.

func (Scope) Equal 

func (s Scope) Equal(o Scope) bool

Equal reports whether two scopes are deeply equal.

type Series 

type Series struct {
	Resource   Resource
	Scope      Scope
	Attributes Attributes
}

Series is the signal-neutral identity of a time series: the OTel three-level identity backbone — its Resource, the Scope that produced it, and its data-point Attributes. Equal Series have equal Series.Hash.

Signal-specific packages extend this with their own identifying fields: a metric series adds name, unit, temporality and monotonicity to the hash pre-image (via Series.AppendHashInput then their own fields) before computing the final id.

func DecodeSeries 

func DecodeSeries(src []byte) (Series, int, error)

DecodeSeries parses the canonical binary form produced by Series.AppendHashInput: resource, then scope, then data-point attributes. All byte fields alias src.

func (Series) AppendHashInput 

func (s Series) AppendHashInput(dst []byte) []byte

AppendHashInput appends the canonical, unambiguous hash pre-image of the whole identity (resource ‖ scope ‖ attributes) to dst. Each component is length-delimited, so no two distinct identities share a pre-image. It is the reversible wire form decoded by DecodeSeries.

func (Series) Clone 

func (s Series) Clone() Series

Clone returns a deep copy of the identity.

func (Series) Equal 

func (s Series) Equal(o Series) bool

Equal reports whether two identities are deeply equal.

func (Series) Hash 

func (s Series) Hash() SeriesID

Hash returns the content-addressed SeriesID of the full identity.

type SeriesID 

type SeriesID struct {
	Hi, Lo uint64
}

SeriesID is the content-addressed identity of a time series: a 128-bit hash of its sorted attribute set. Equal attribute sets yield equal SeriesID on every node, which makes placement and dedup deterministic without a central id allocator.

It is 128-bit, not 64-bit, on purpose: identity is content-addressed, so there is no allocator to detect or resolve a hash collision. At this system's scale (~1e9 series over retention) a 64-bit content hash collides with a few-percent probability — a silent merge of two distinct series. 128 bits makes that negligible for any realistic cardinality. SeriesID is comparable, so it is usable directly as a map key.

func HashBytes 

func HashBytes(preimage []byte) SeriesID

HashBytes returns the SeriesID of a canonical hash pre-image (see Attributes.AppendHashInput). Callers that already built the pre-image use this to stay zero-alloc.

func (SeriesID) AppendBinary 

func (s SeriesID) AppendBinary(dst []byte) []byte

AppendBinary appends the 16-byte big-endian encoding (Hi then Lo) of the id to dst.

func (SeriesID) Compare 

func (s SeriesID) Compare(o SeriesID) int

Compare orders SeriesIDs (high word first), giving postings lists a total order.

func (SeriesID) Less 

func (s SeriesID) Less(o SeriesID) bool

Less reports whether s sorts before o.

func (SeriesID) String 

func (s SeriesID) String() string

String returns the 32-hex-digit form of the id.

type Signal 

type Signal uint8

Signal is the OTel signal kind. It is part of the [fetch.Request] identity and the top-level [storage.Query] routing. Values are stable (persisted/wire-stable). 

const (
	// Metric is the metrics signal (the first vertical).
	Metric Signal = iota + 1
	// Log is the logs signal (later vertical).
	Log
	// Trace is the traces signal (later vertical).
	Trace
	// Profile is the profiles signal (later vertical).
	Profile
)

func ParseSignal 

func ParseSignal(s string) (Signal, error)

ParseSignal decodes a Signal from its Signal.String form. Unknown values yield ErrUnknownSignal.

func (Signal) String 

func (s Signal) String() string

String returns a lower-case signal name. It is stable.

type TenantID 

type TenantID string

TenantID identifies a tenant. It is the leading key/path prefix for all data and the argument to [tenant.Resolver] policy lookups. The zero value is the default tenant; callers may use any non-empty string.

TenantID is compared by value (it is a string) and is safe to use as a map key.

func (TenantID) String 

func (t TenantID) String() string

String returns the tenant id as a string, or "default" for the zero value.

type Value 

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

Value is an OTel attribute value: the typed AnyValue sum. String and byte values are held as []byte (never string) so projecting from an OTLP decode buffer and interning stay allocation-free — keys and values are compared and hashed as bytes. Scalars are stored inline; bytes/slice/map hold a reference the caller must not mutate. The zero Value is KindEmpty. Treat values as immutable.

func BoolValue 

func BoolValue(b bool) Value

BoolValue returns a boolean attribute value.

func BytesValue 

func BytesValue(b []byte) Value

BytesValue returns a raw-bytes attribute value over b (not copied).

func DecodeValue 

func DecodeValue(src []byte) (Value, int, error)

DecodeValue parses one value from the front of src and returns it with the number of bytes consumed. String/byte values alias src. It bounds-checks every field and never panics, so it is safe to fuzz on arbitrary input.

func DoubleValue 

func DoubleValue(f float64) Value

DoubleValue returns a float64 attribute value.

func EmptyValue 

func EmptyValue() Value

EmptyValue returns the unset/null value.

func IntValue 

func IntValue(i int64) Value

IntValue returns an int64 attribute value.

func MapValue 

func MapValue(kvs ...KeyValue) Value

MapValue returns a map (kvlist) attribute value; the entries are sorted by key.

func SliceValue 

func SliceValue(vs ...Value) Value

SliceValue returns an ordered array attribute value.

func StringValue 

func StringValue(s []byte) Value

StringValue returns a string attribute value over s (not copied).

func (Value) AppendText 

func (v Value) AppendText(dst []byte) []byte

AppendText appends a canonical text projection of the value to dst (append-style, so callers reuse one buffer). It is used by the string-keyed matching layer and for display; it is not the identity (that is the typed Attributes.Hash).

func (Value) Bool 

func (v Value) Bool() bool

Bool returns the boolean value (false if not KindBool).

func (Value) Bytes 

func (v Value) Bytes() []byte

Bytes returns the byte value (nil if not KindBytes). The result aliases the value.

func (Value) Clone 

func (v Value) Clone() Value

Clone returns a deep copy of the value (including nested slices/maps and the string/ byte payload).

func (Value) Double 

func (v Value) Double() float64

Double returns the float64 value (0 if not KindDouble).

func (Value) Equal 

func (v Value) Equal(o Value) bool

Equal reports whether two values are deeply equal (maps are order-independent because Attributes is kept sorted).

func (Value) Int 

func (v Value) Int() int64

Int returns the int64 value (0 if not KindInt).

func (Value) Kind 

func (v Value) Kind() ValueKind

Kind reports the value's dynamic type.

func (Value) Map 

func (v Value) Map() Attributes

Map returns the map entries (nil if not KindMap).

func (Value) Slice 

func (v Value) Slice() []Value

Slice returns the array elements (nil if not KindSlice).

func (Value) Str 

func (v Value) Str() []byte

Str returns the string bytes (nil if not KindStr). The result aliases the value.

type ValueKind 

type ValueKind uint8

ValueKind is the dynamic type of an OTel attribute Value — the OTLP AnyValue oneof. Values are persisted in the canonical hash pre-image and the symbol/series formats; never reorder. 

const (
	// KindEmpty is an unset/null value (distinct from an empty string or zero).
	KindEmpty ValueKind = iota
	// KindStr is a UTF-8 string, held as raw bytes.
	KindStr
	// KindBool is a boolean.
	KindBool
	// KindInt is a signed 64-bit integer.
	KindInt
	// KindDouble is an IEEE-754 float64.
	KindDouble
	// KindBytes is a raw byte string.
	KindBytes
	// KindSlice is an ordered array of values (ArrayValue).
	KindSlice
	// KindMap is an unordered map of key→value (KeyValueList); compared and hashed
	// irrespective of order, per the OTel spec.
	KindMap
)

Source Files

View all Source files

Directories

Path Synopsis
Package log holds the logs signal's ingest model.
 Package log holds the logs signal's ingest model.
Package metric implements the metrics signal: OTLP metric point types, temporality, series identity, and the OTLP → internal projection.
 Package metric implements the metrics signal: OTLP metric point types, temporality, series identity, and the OTLP → internal projection.
Package profile holds the profiles signal's ingest model.
 Package profile holds the profiles signal's ingest model.
Package trace holds the traces signal's ingest model.
 Package trace holds the traces signal's ingest model.

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.