Creation Timestamp Payloads

Create helpers that produce serialized metric payloads using the dependency's Prometheus data model. Each helper must populate the dedicated creation timestamp field for counters, summaries, and histograms when a non-zero start time is provided, and omit it otherwise.

Capabilities

Counter creation timestamps

• Given a start time of 2024-01-01T00:00:00Z, metric name requests_total, value 9.5, and labels {method: "GET"}, the encoded counter payload contains the creation timestamp in milliseconds matching the start time alongside the name, labels, and value. @test
• When the start time is the zero value, the counter payload contains the name, labels, and value but no creation timestamp field. @test

Summary creation timestamps

• Provided a non-zero start time, count 3, sum 42.5, quantiles {0.5: 10.5, 0.9: 20.25}, and labels {route: "/health"}, the encoded summary payload includes the creation timestamp derived from the start time along with the supplied count, sum, quantiles, and labels. @test

Histogram creation timestamps

• With a non-zero start time, total count 7, sum 15.0, buckets [{UpperBound: 0.5, CumulativeCount: 2}, {UpperBound: 1.0, CumulativeCount: 5}, {UpperBound: +Inf, CumulativeCount: 7}], and labels {job: "api"}, the encoded histogram payload embeds the creation timestamp derived from the start time while persisting all bucket bounds, cumulative counts, and labels. @test

Implementation

@generates

API

package metrics

import "time"

type BucketInput struct {
	UpperBound       float64
	CumulativeCount  uint64
}

// Returns a serialized payload for a counter metric that includes the creation timestamp when start is non-zero.
func EncodeCounter(start time.Time, name string, value float64, labels map[string]string) ([]byte, error)

// Returns a serialized payload for a summary metric that includes the creation timestamp when start is non-zero.
func EncodeSummary(start time.Time, name string, count uint64, sum float64, quantiles map[float64]float64, labels map[string]string) ([]byte, error)

// Returns a serialized payload for a histogram metric that includes the creation timestamp when start is non-zero.
func EncodeHistogram(start time.Time, name string, count uint64, sum float64, buckets []BucketInput, labels map[string]string) ([]byte, error)

Dependencies { .dependencies }

github.com/prometheus/client_model/go { .dependency }

Provides the Prometheus metric data model used to encode counters, summaries, and histograms with optional creation timestamps.