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 ¶
- Variables
- func AppendKeyValueHashInput(dst, key []byte, v Value) []byte
- func AppendValue(dst []byte, v Value) []byte
- type Aggregation
- type Attributes
- type KeyValue
- type Resource
- type Scope
- type Series
- type SeriesID
- type Signal
- type TenantID
- type Value
- func BoolValue(b bool) Value
- func BytesValue(b []byte) Value
- func DecodeValue(src []byte) (Value, int, error)
- func DoubleValue(f float64) Value
- func EmptyValue() Value
- func IntValue(i int64) Value
- func LookupAttribute(src []byte, key string) (Value, bool, error)
- func MapValue(kvs ...KeyValue) Value
- func SliceValue(vs ...Value) Value
- func StringValue(s []byte) Value
- func (v Value) AppendText(dst []byte) []byte
- func (v Value) Bool() bool
- func (v Value) Bytes() []byte
- func (v Value) Clone() Value
- func (v Value) Double() float64
- func (v Value) Equal(o Value) bool
- func (v Value) Int() int64
- func (v Value) Intern(fn func([]byte) []byte) Value
- func (v Value) Kind() ValueKind
- func (v Value) Map() Attributes
- func (v Value) Slice() []Value
- func (v Value) Str() []byte
- type ValueKind
Constants ¶
This section is empty.
Variables ¶
var ErrMalformed = errors.New("signal: malformed attribute encoding")
ErrMalformed is returned when a serialized Value or Attributes fails to parse.
var ErrUnknownAggregation = errors.New("signal: unknown aggregation")
ErrUnknownAggregation is returned by ParseAggregation for an unrecognized name.
var ErrUnknownSignal = errors.New("signal: unknown signal kind")
ErrUnknownSignal is returned by ParseSignal for an unrecognized name.
Functions ¶
func AppendKeyValueHashInput ¶
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 ¶
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 Aggregation ¶ added in v0.4.0
type Aggregation uint8
Aggregation names how a set of samples collapses into one value. It is the shared vocabulary for merge-time downsampling (the engine applies it) and per-tenant downsampling policy (the tenant package configures it), so both layers agree on the rollup function without depending on each other. Values are stable.
const ( // AggLast keeps the value of the newest (largest-timestamp) sample in the group. It is // the zero value and the safe default: it preserves a gauge's most recent reading and a // cumulative counter's latest total (so rate() over downsampled data stays meaningful). AggLast Aggregation = iota // AggFirst keeps the value of the oldest (smallest-timestamp) sample. AggFirst // AggMin keeps the smallest value. AggMin // AggMax keeps the largest value. AggMax // AggSum adds the values. AggSum // AggAvg keeps the arithmetic mean of the values. AggAvg // AggCount keeps the number of samples in the group (as a float64). AggCount )
func ParseAggregation ¶ added in v0.4.0
func ParseAggregation(s string) (Aggregation, error)
ParseAggregation decodes an Aggregation from its Aggregation.String form. Unknown values yield ErrUnknownAggregation.
func (Aggregation) String ¶ added in v0.4.0
func (a Aggregation) String() string
String returns a lower-case aggregation name. It is stable.
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 AppendAttributes ¶ added in v0.11.0
func AppendAttributes(dst Attributes, src []byte) (Attributes, int, error)
AppendAttributes decodes the canonical attribute encoding into dst (reusing its capacity) and returns the extended slice with the number of bytes consumed. Keys and string/byte values alias src. Pass a reused dst[:0] to decode many blobs without the per-call slice allocation that DecodeAttributes incurs; the result is consumed before the next call (its keys/values alias src, not dst), so the same buffer can back row-by-row materialization.
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.
func (Attributes) Intern ¶ added in v0.14.0
func (a Attributes) Intern(fn func([]byte) []byte) Attributes
Intern returns a copy of the attribute set with every key and string/byte value payload replaced by fn(payload), so all byte storage is drawn from one shared pool. See Value.Intern. A nil fn yields a plain deep copy (equivalent to Clone).
type KeyValue ¶
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 ¶
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.
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 ¶
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.
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 ¶
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 ¶
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) Intern ¶ added in v0.14.0
Intern returns a copy of the identity with every string/byte payload replaced by fn(payload), so all byte storage is drawn from one shared pool (one owned copy per distinct string). It is the long-lived-storage form of Clone: a series index that interns its identities holds references to a single symbol table instead of a private clone per series. A nil fn yields a plain deep copy.
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 ¶
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 ¶
AppendBinary appends the 16-byte big-endian encoding (Hi then Lo) of the id to dst.
func (SeriesID) Compare ¶
Compare orders SeriesIDs (high word first), giving postings lists a total order.
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).
func ParseSignal ¶
ParseSignal decodes a Signal from its Signal.String form. Unknown values yield ErrUnknownSignal.
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.
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 BytesValue ¶
BytesValue returns a raw-bytes attribute value over b (not copied).
func DecodeValue ¶
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 LookupAttribute ¶ added in v0.2.0
LookupAttribute scans the canonical binary form produced by Attributes.AppendHashInput for the attribute named key and returns its value (aliasing src) and whether it was present. Unlike DecodeAttributes it materializes no slice and decodes only keys plus the one matching value, so a per-row attribute predicate over a serialized blob allocates nothing. It is bounds-checked and never panics (safe to fuzz).
func SliceValue ¶
SliceValue returns an ordered array attribute value.
func StringValue ¶
StringValue returns a string attribute value over s (not copied).
func (Value) AppendText ¶
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) Bytes ¶
Bytes returns the byte value (nil if not KindBytes). The result aliases the value.
func (Value) Clone ¶
Clone returns a deep copy of the value (including nested slices/maps and the string/ byte payload).
func (Value) Double ¶
Double returns the float64 value (0 if not KindDouble).
func (Value) Equal ¶
Equal reports whether two values are deeply equal (maps are order-independent because Attributes is kept sorted).
func (Value) Intern ¶ added in v0.14.0
Intern returns a copy of the value with every string/byte payload replaced by fn(payload), so all byte storage is drawn from one shared pool (one owned copy per distinct string, referenced by every value that interns the same bytes). Scalar payloads are copied by value. fn owns and deduplicates the returned slice; a nil fn yields a plain deep copy (equivalent to Clone). It is the allocation-free-identity form of Clone for long-lived storage like a series index.
func (Value) Map ¶
func (v Value) Map() Attributes
Map returns the map entries (nil if not KindMap).
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
Directories
¶
| Path | Synopsis |
|---|---|
|
Package log holds the logs signal's ingest model: the []byte-based, OTLP-shaped, zero-alloc batch accepted at the storage boundary (in place of OTel-Go plog.Logs), and its projection into the columnar log-record model the logs engine ingests.
|
Package log holds the logs signal's ingest model: the []byte-based, OTLP-shaped, zero-alloc batch accepted at the storage boundary (in place of OTel-Go plog.Logs), and its projection into the columnar log-record model the logs engine ingests. |
|
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: the []byte-based, OTLP-shaped batch accepted at the storage boundary (in place of OTel-Go pprofile.Profiles), and its projection into the columnar sample model the record engine ingests plus the content-addressed symbol store.
|
Package profile holds the profiles signal's ingest model: the []byte-based, OTLP-shaped batch accepted at the storage boundary (in place of OTel-Go pprofile.Profiles), and its projection into the columnar sample model the record engine ingests plus the content-addressed symbol store. |
|
Package trace holds the traces signal's ingest model: the []byte-based, OTLP-shaped, zero-alloc batch accepted at the storage boundary (in place of OTel-Go ptrace.Traces), and its projection into the columnar span model the record engine ingests.
|
Package trace holds the traces signal's ingest model: the []byte-based, OTLP-shaped, zero-alloc batch accepted at the storage boundary (in place of OTel-Go ptrace.Traces), and its projection into the columnar span model the record engine ingests. |