go.opentelemetry.io/proto/otlp v1.9.0: v1.AggregationTemporality

# OpenTelemetry OTLP AggregationTemporality Semantics

A search for `go.opentelemetry.io/proto/otlp/metrics/v1.AggregationTemporality` in `pkg:golang/go.opentelemetry.io/proto/otlp@v1.9.0` returned `NO_SAFE_MATCH`.

This sample verifies the enum values, reflection mappings, metric container usage, binary protobuf serialization, and protojson serialization for `AggregationTemporality`.

## Observed Behavior

1. **Enum Values and String Mapping**:
   - `AggregationTemporality_AGGREGATION_TEMPORALITY_UNSPECIFIED` = 0 (`"AGGREGATION_TEMPORALITY_UNSPECIFIED"`)
   - `AggregationTemporality_AGGREGATION_TEMPORALITY_DELTA` = 1 (`"AGGREGATION_TEMPORALITY_DELTA"`)
   - `AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE` = 2 (`"AGGREGATION_TEMPORALITY_CUMULATIVE"`)
   - `AggregationTemporality_name` and `AggregationTemporality_value` map between string names and integer values.
   - `Enum()` returns a pointer to the value, and `Number()` returns the `protoreflect.EnumNumber`.

2. **Metric Type Integration (`Sum`, `Histogram`, `ExponentialHistogram`)**:
   - `Sum.AggregationTemporality` and `Histogram.AggregationTemporality` represent how metrics aggregate over time.
   - Getter methods (`GetAggregationTemporality()`) return the configured enum value, or `AGGREGATION_TEMPORALITY_UNSPECIFIED` when nil or uninitialized.

3. **Binary Protobuf Serialization (`proto.Marshal` / `proto.Unmarshal`)**:
   - Round-trip binary marshaling preserves exact `AggregationTemporality` values on metric types.

4. **JSON Serialization (`protojson.Marshal` / `protojson.Unmarshal`)**:
   - By default, enums are serialized as string constants (e.g. `"AGGREGATION_TEMPORALITY_CUMULATIVE"`).
   - With `protojson.MarshalOptions{UseEnumNumbers: true}`, enums are serialized as integer numbers (e.g. `2`).
   - Both formats round-trip cleanly back to the strongly-typed enum in Go.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify go.opentelemetry.io/proto/otlp/metrics/v1.AggregationTemporality in pkg:golang/go.opentelemetry.io/proto/otlp@v1.9.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.opentelemetry.io/proto/otlp@v1.9.0
Demonstrate these symbols/APIs:
  - go.opentelemetry.io/proto/otlp/metrics/v1.AggregationTemporality

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:a7134617183b6c3f4ab6662fc6c0dbded0e7d02c5e9d9ccbab79cde264dcbd24","contract":["AggregationTemporality defines UNSPECIFIED (0), DELTA (1), and CUMULATIVE (2) enum values with matching String representations and name/value mappings.","Sum and Histogram metric types store and retrieve AggregationTemporality correctly via getter methods, defaulting to UNSPECIFIED when omitted.","AggregationTemporality persists across protobuf binary marshaling and unmarshaling for Sum and Histogram metric payloads.","AggregationTemporality serializes to JSON as enum name strings by default and as integer values with UseEnumNumbers, round-tripping cleanly through protojson."],"goal":"verify go.opentelemetry.io/proto/otlp/metrics/v1.AggregationTemporality in pkg:golang/go.opentelemetry.io/proto/otlp@v1.9.0","kind":"HOW","packages":["pkg:golang/go.opentelemetry.io/proto/otlp@v1.9.0"],"schemaVersion":1,"symbols":["go.opentelemetry.io/proto/otlp/metrics/v1.AggregationTemporality"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/go.opentelemetry.io/proto/otlp@v1.9.0"],"schemaVersion":1,"subject":"pkg:golang/go.opentelemetry.io/proto/otlp@v1.9.0","symbols":["go.opentelemetry.io/proto/otlp/metrics/v1.AggregationTemporality"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require (
	go.opentelemetry.io/proto/otlp v1.9.0
	google.golang.org/protobuf v1.36.10
)

github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
go.opentelemetry.io/proto/otlp v1.9.0 h1:l706jCMITVouPOqEnii2fIAuO3IVGBRPV5ICjceRb/A=
go.opentelemetry.io/proto/otlp v1.9.0/go.mod h1:xE+Cx5E/eEHw+ISFkwPLwCZefwVjY+pqKg1qcK03+/4=
google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=

package main

import (
	"fmt"

	metricspb "go.opentelemetry.io/proto/otlp/metrics/v1"
	"google.golang.org/protobuf/encoding/protojson"
	"google.golang.org/protobuf/proto"
)

// CreateCumulativeSumMetric creates a Metric containing a Sum with CUMULATIVE temporality.
func CreateCumulativeSumMetric(name string, value int64) *metricspb.Metric {
	return &metricspb.Metric{
		Name: name,
		Data: &metricspb.Metric_Sum{
			Sum: &metricspb.Sum{
				AggregationTemporality: metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE,
				IsMonotonic:            true,
				DataPoints: []*metricspb.NumberDataPoint{
					{
						Value: &metricspb.NumberDataPoint_AsInt{
							AsInt: value,
						},
					},
				},
			},
		},
	}
}

// CreateDeltaHistogramMetric creates a Metric containing a Histogram with DELTA temporality.
func CreateDeltaHistogramMetric(name string, count uint64, sum float64) *metricspb.Metric {
	return &metricspb.Metric{
		Name: name,
		Data: &metricspb.Metric_Histogram{
			Histogram: &metricspb.Histogram{
				AggregationTemporality: metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_DELTA,
				DataPoints: []*metricspb.HistogramDataPoint{
					{
						Count: count,
						Sum:   &sum,
					},
				},
			},
		},
	}
}

// MarshalMetricProto marshals a Metric to protobuf binary format.
func MarshalMetricProto(m *metricspb.Metric) ([]byte, error) {
	return proto.Marshal(m)
}

// UnmarshalMetricProto unmarshals a Metric from protobuf binary format.
func UnmarshalMetricProto(data []byte) (*metricspb.Metric, error) {
	var m metricspb.Metric
	if err := proto.Unmarshal(data, &m); err != nil {
		return nil, err
	}
	return &m, nil
}

// MarshalMetricJSON marshals a Metric to protobuf JSON format.
func MarshalMetricJSON(m *metricspb.Metric, useEnumNumbers bool) ([]byte, error) {
	opts := protojson.MarshalOptions{
		UseEnumNumbers: useEnumNumbers,
	}
	return opts.Marshal(m)
}

// UnmarshalMetricJSON unmarshals a Metric from protobuf JSON format.
func UnmarshalMetricJSON(data []byte) (*metricspb.Metric, error) {
	var m metricspb.Metric
	if err := protojson.Unmarshal(data, &m); err != nil {
		return nil, err
	}
	return &m, nil
}

func main() {
	m := CreateCumulativeSumMetric("system.cpu.seconds", 42)
	fmt.Printf("Metric: %s, Temporality: %s\n", m.GetName(), m.GetSum().GetAggregationTemporality().String())
}

{
  "schemaVersion": 1,
  "goal": "verify go.opentelemetry.io/proto/otlp/metrics/v1.AggregationTemporality in pkg:golang/go.opentelemetry.io/proto/otlp@v1.9.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.opentelemetry.io/proto/otlp@v1.9.0"
  ],
  "symbols": [
    "go.opentelemetry.io/proto/otlp/metrics/v1.AggregationTemporality"
  ]
}

package main

import (
	"fmt"
	"os"
	"strings"

	metricspb "go.opentelemetry.io/proto/otlp/metrics/v1"
	"google.golang.org/protobuf/encoding/protojson"
	"google.golang.org/protobuf/proto"
)

func main() {
	// Assertion 1: AggregationTemporality defines UNSPECIFIED (0), DELTA (1), and CUMULATIVE (2) enum values with matching String representations and name/value mappings.
	{
		unspecified := metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_UNSPECIFIED
		delta := metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_DELTA
		cumulative := metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE

		if int32(unspecified) != 0 || unspecified.Number() != 0 {
			fmt.Fprintf(os.Stderr, "FAIL: unspecified temporality expected 0, got %d\n", int32(unspecified))
			os.Exit(1)
		}
		if int32(delta) != 1 || delta.Number() != 1 {
			fmt.Fprintf(os.Stderr, "FAIL: delta temporality expected 1, got %d\n", int32(delta))
			os.Exit(1)
		}
		if int32(cumulative) != 2 || cumulative.Number() != 2 {
			fmt.Fprintf(os.Stderr, "FAIL: cumulative temporality expected 2, got %d\n", int32(cumulative))
			os.Exit(1)
		}

		if unspecified.String() != "AGGREGATION_TEMPORALITY_UNSPECIFIED" {
			fmt.Fprintf(os.Stderr, "FAIL: unexpected String() for unspecified: %s\n", unspecified.String())
			os.Exit(1)
		}
		if delta.String() != "AGGREGATION_TEMPORALITY_DELTA" {
			fmt.Fprintf(os.Stderr, "FAIL: unexpected String() for delta: %s\n", delta.String())
			os.Exit(1)
		}
		if cumulative.String() != "AGGREGATION_TEMPORALITY_CUMULATIVE" {
			fmt.Fprintf(os.Stderr, "FAIL: unexpected String() for cumulative: %s\n", cumulative.String())
			os.Exit(1)
		}

		if metricspb.AggregationTemporality_name[1] != "AGGREGATION_TEMPORALITY_DELTA" {
			fmt.Fprintf(os.Stderr, "FAIL: name map lookup failed for DELTA\n")
			os.Exit(1)
		}
		if metricspb.AggregationTemporality_value["AGGREGATION_TEMPORALITY_CUMULATIVE"] != 2 {
			fmt.Fprintf(os.Stderr, "FAIL: value map lookup failed for CUMULATIVE\n")
			os.Exit(1)
		}
		if *cumulative.Enum() != cumulative {
			fmt.Fprintf(os.Stderr, "FAIL: Enum() pointer value mismatch\n")
			os.Exit(1)
		}
	}

	// Assertion 2: Sum and Histogram metric types store and retrieve AggregationTemporality correctly via getter methods, defaulting to UNSPECIFIED when omitted.
	{
		var emptySum *metricspb.Sum
		if emptySum.GetAggregationTemporality() != metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_UNSPECIFIED {
			fmt.Fprintf(os.Stderr, "FAIL: nil Sum expected UNSPECIFIED temporality\n")
			os.Exit(1)
		}

		sum := &metricspb.Sum{
			AggregationTemporality: metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE,
			IsMonotonic:            true,
		}
		if sum.GetAggregationTemporality() != metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE {
			fmt.Fprintf(os.Stderr, "FAIL: expected CUMULATIVE temporality on Sum, got %s\n", sum.GetAggregationTemporality())
			os.Exit(1)
		}

		var emptyHist *metricspb.Histogram
		if emptyHist.GetAggregationTemporality() != metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_UNSPECIFIED {
			fmt.Fprintf(os.Stderr, "FAIL: nil Histogram expected UNSPECIFIED temporality\n")
			os.Exit(1)
		}

		hist := &metricspb.Histogram{
			AggregationTemporality: metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_DELTA,
		}
		if hist.GetAggregationTemporality() != metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_DELTA {
			fmt.Fprintf(os.Stderr, "FAIL: expected DELTA temporality on Histogram, got %s\n", hist.GetAggregationTemporality())
			os.Exit(1)
		}

		expHist := &metricspb.ExponentialHistogram{
			AggregationTemporality: metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_DELTA,
		}
		if expHist.GetAggregationTemporality() != metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_DELTA {
			fmt.Fprintf(os.Stderr, "FAIL: expected DELTA temporality on ExponentialHistogram, got %s\n", expHist.GetAggregationTemporality())
			os.Exit(1)
		}
	}

	// Assertion 3: AggregationTemporality persists across protobuf binary marshaling and unmarshaling for Sum and Histogram metric payloads.
	{
		sumMetric := &metricspb.Metric{
			Name: "http_server_duration_seconds",
			Data: &metricspb.Metric_Sum{
				Sum: &metricspb.Sum{
					AggregationTemporality: metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE,
					IsMonotonic:            true,
					DataPoints: []*metricspb.NumberDataPoint{
						{
							Value: &metricspb.NumberDataPoint_AsInt{
								AsInt: 100,
							},
						},
					},
				},
			},
		}

		data, err := proto.Marshal(sumMetric)
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: proto.Marshal failed: %v\n", err)
			os.Exit(1)
		}

		var unmarshaledSumMetric metricspb.Metric
		if err := proto.Unmarshal(data, &unmarshaledSumMetric); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: proto.Unmarshal failed: %v\n", err)
			os.Exit(1)
		}

		if unmarshaledSumMetric.GetSum().GetAggregationTemporality() != metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE {
			fmt.Fprintf(os.Stderr, "FAIL: unmarshaled temporality mismatch: expected CUMULATIVE, got %s\n", unmarshaledSumMetric.GetSum().GetAggregationTemporality())
			os.Exit(1)
		}

		sumVal := 45.2
		histMetric := &metricspb.Metric{
			Name: "rpc_request_duration_ms",
			Data: &metricspb.Metric_Histogram{
				Histogram: &metricspb.Histogram{
					AggregationTemporality: metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_DELTA,
					DataPoints: []*metricspb.HistogramDataPoint{
						{
							Count: 5,
							Sum:   &sumVal,
						},
					},
				},
			},
		}

		histData, err := proto.Marshal(histMetric)
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: proto.Marshal histogram failed: %v\n", err)
			os.Exit(1)
		}

		var unmarshaledHistMetric metricspb.Metric
		if err := proto.Unmarshal(histData, &unmarshaledHistMetric); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: proto.Unmarshal histogram failed: %v\n", err)
			os.Exit(1)
		}

		if unmarshaledHistMetric.GetHistogram().GetAggregationTemporality() != metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_DELTA {
			fmt.Fprintf(os.Stderr, "FAIL: unmarshaled histogram temporality mismatch: expected DELTA, got %s\n", unmarshaledHistMetric.GetHistogram().GetAggregationTemporality())
			os.Exit(1)
		}
	}

	// Assertion 4: AggregationTemporality serializes to JSON as enum name strings by default and as integer values with UseEnumNumbers, round-tripping cleanly through protojson.
	{
		metric := &metricspb.Metric{
			Name: "active_workers",
			Data: &metricspb.Metric_Sum{
				Sum: &metricspb.Sum{
					AggregationTemporality: metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE,
					IsMonotonic:            false,
				},
			},
		}

		jsonDefault, err := protojson.Marshal(metric)
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: protojson.Marshal failed: %v\n", err)
			os.Exit(1)
		}
		if !strings.Contains(string(jsonDefault), `"AGGREGATION_TEMPORALITY_CUMULATIVE"`) {
			fmt.Fprintf(os.Stderr, "FAIL: expected JSON string enum 'AGGREGATION_TEMPORALITY_CUMULATIVE', got: %s\n", string(jsonDefault))
			os.Exit(1)
		}

		var roundTripDefault metricspb.Metric
		if err := protojson.Unmarshal(jsonDefault, &roundTripDefault); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: protojson.Unmarshal default failed: %v\n", err)
			os.Exit(1)
		}
		if roundTripDefault.GetSum().GetAggregationTemporality() != metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE {
			fmt.Fprintf(os.Stderr, "FAIL: round-trip default temporality mismatch\n")
			os.Exit(1)
		}

		optsNumeric := protojson.MarshalOptions{UseEnumNumbers: true}
		jsonNumeric, err := optsNumeric.Marshal(metric)
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: protojson.Marshal with UseEnumNumbers failed: %v\n", err)
			os.Exit(1)
		}
		if !strings.Contains(string(jsonNumeric), `"aggregationTemporality":2`) && !strings.Contains(string(jsonNumeric), `"aggregation_temporality":2`) {
			fmt.Fprintf(os.Stderr, "FAIL: expected JSON numeric enum '2', got: %s\n", string(jsonNumeric))
			os.Exit(1)
		}

		var roundTripNumeric metricspb.Metric
		if err := protojson.Unmarshal(jsonNumeric, &roundTripNumeric); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: protojson.Unmarshal numeric failed: %v\n", err)
			os.Exit(1)
		}
		if roundTripNumeric.GetSum().GetAggregationTemporality() != metricspb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE {
			fmt.Fprintf(os.Stderr, "FAIL: round-trip numeric temporality mismatch\n")
			os.Exit(1)
		}
	}

	fmt.Println("PASS: all AggregationTemporality contract assertions passed")
}