Skip to content

feat(asap-precompute-go): SketchEnvelope MetricName/Count/Temporality + Sketch trait split - #224

Merged
zzylol merged 1 commit into
mainfrom
phase2/envelope-and-sketch-trait-split
May 2, 2026
Merged

zzylol merged 1 commit into
mainfrom
phase2/envelope-and-sketch-trait-split

Conversation

@zzylol

@zzylol zzylol commented May 2, 2026

Copy link
Copy Markdown
Contributor

Summary

Phase 2 step 2.4b — extends the host-neutral SketchEnvelope and splits the
Sketch trait so the upcoming OTel-shim refactor PRs (steps 2.5–2.9) can
delegate to the runtime without resorting to side-channel labels.

1. SketchEnvelope envelope.go — three new in-process fields

  • MetricName string — the metric name the runtime emits each envelope for.
    Lets Adapter.Encode stamp pmetric.Metric.Name() directly instead of
    fishing for the _asap_metric_name label.
  • Count uint64 — total observation count this envelope represents (sum of
    per-window samples). Used by the OTel adapter's dp.SetCount() and as a
    sanity field for downstream consumers.
  • AggregationTemporality int32 — OTel temporality enum (0 unspecified / 1
    delta / 2 cumulative), stored as int32 not pmetric.AggregationTemporality
    to keep the runtime free of the pmetric import (host-neutral invariant
    from ADR-0002).

These are in-process Go fields only — the proto wire format is unchanged
(Payload []byte is still the canonical sketch state, per ADR-0002 §"Behavior
preservation").

2. Sketch trait split — three new sub-interfaces in precompute.go

The base Sketch interface stays as the runtime's storage type
(Snapshot/ComputeDeltaAgainst/ApplyDelta/Merge/Reset — what window.go and
snapshot_cache.go need). Three sub-interfaces describe what each sketch can
answer:

  • QuantileSketchQuantile(q float64) float64 (DDSketch, KLL).
  • CardinalitySketchEstimateCardinality() float64 (HLL).
  • FrequencySketchEstimateCount(key []byte) float64 and
    TopK(k int) []FrequencyEntry (CountSketch, CountMinSketch).

The runtime never type-asserts to the sub-traits — only adapter encode code
will (e.g. s.(CardinalitySketch) for an HLL gauge).

3. Wire the new envelope fields through the emit path

  • PrecomputeConfig gains MetricName string and Temporality int32.
  • seriesEntry gains Count uint64, incremented on each scalar Observe and
    accumulated from env.Count on ObserveEnvelope.
  • precompute.serializeSeries populates MetricName / Count /
    AggregationTemporality on every emitted envelope.

4. OTel adapter encode — drop the _asap_metric_name label hack

  • otel/encode.go::metricNameFor reads env.MetricName directly; the
    lookupLabel helper is removed.
  • Doc comment on Encode notes that the labels list no longer carries
    _asap_metric_name since envelopes have a typed field.

Tests

  • envelope_test.go (new) — pin zero-value defaults and field assignability.
  • precompute_test.go — two new tests confirming envelopes carry MetricName /
    Count / Temporality (populated and zero-config cases), plus compile-time
    var _ CardinalitySketch = (*hllStub)(nil) style assertions for all three
    sub-traits and a runtime smoke test.
  • otel/encode_test.go — existing MetricSuffix / MetricName tests updated
    to use the typed MetricName field instead of the legacy label.

Test plan

  • cd asap-precompute-go && go build ./...
  • cd asap-precompute-go && go test ./...
  • cd asap-precompute-go && go test -race ./...
  • cd asap-precompute-go && go vet ./...
  • OTel-shim refactor PRs (steps 2.5–2.9) build against this without
    reverting to label-hack — verified once those PRs land.

Phase 2

Step 2.4b of the Phase 2 plan: see docs/phase-2-execution-plan.md. Unblocks
the shim refactor PRs (steps 2.5–2.9) which will delegate windowing/snapshot/
delta logic to this runtime instead of duplicating it per-processor.

… + Sketch trait split

- Add MetricName/Count/AggregationTemporality fields to in-process SketchEnvelope (wire format unchanged).
- Split queries into QuantileSketch/CardinalitySketch/FrequencySketch sub-traits over base Sketch.
- Remove _asap_metric_name label hack from OTel adapter encode.
- Tests cover envelope population and sub-trait satisfaction.

Phase 2 step 2.4b. Unblocks shim refactor PRs (steps 2.5–2.9).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@zzylol
zzylol merged commit 764fcaa into main May 2, 2026
@zzylol
zzylol deleted the phase2/envelope-and-sketch-trait-split branch May 2, 2026 13:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant