or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/golang-github-com-prometheus--client-model

Data model artifacts for Prometheus

Workspace: tessl
Visibility: Public
Created: about 11 hours ago
Last updated: about 11 hours ago
Describes: pkg:golang/github.com/prometheus/client_model@0.6.x

To install, run

npx @tessl/cli install tessl/golang-github-com-prometheus--client-model@0.6.0

Prometheus Client Model

Prometheus Client Model provides the Protocol Buffer data model definitions for Prometheus metrics. It defines the core data structures used to represent all Prometheus metric types in protobuf format, including Counter, Gauge, Summary, Histogram (including native/sparse histograms), and supporting structures like labels and exemplars.

Package Information

Package Name: github.com/prometheus/client_model
Package Type: golang
Language: Go
Version: 0.6.2
Installation: go get github.com/prometheus/client_model/go@v0.6.2
Go Import Package: github.com/prometheus/client_model/go
Go Package Name: io_prometheus_client

Core Imports

import (
    dto "github.com/prometheus/client_model/go"
    "google.golang.org/protobuf/types/known/timestamppb"
)

Basic Usage

import (
    dto "github.com/prometheus/client_model/go"
    "google.golang.org/protobuf/proto"
)

// Create a MetricFamily with a counter
metricFamily := &dto.MetricFamily{
    Name: proto.String("http_requests_total"),
    Help: proto.String("Total number of HTTP requests"),
    Type: dto.MetricType_COUNTER.Enum(),
    Metric: []*dto.Metric{
        {
            Label: []*dto.LabelPair{
                {
                    Name:  proto.String("method"),
                    Value: proto.String("GET"),
                },
                {
                    Name:  proto.String("status"),
                    Value: proto.String("200"),
                },
            },
            Counter: &dto.Counter{
                Value: proto.Float64(42.0),
            },
        },
    },
}

// Serialize to protobuf
data, err := proto.Marshal(metricFamily)
if err != nil {
    // handle error
}

// Deserialize from protobuf
var mf dto.MetricFamily
err = proto.Unmarshal(data, &mf)
if err != nil {
    // handle error
}

Architecture

This package is generated from Protocol Buffer definitions and follows the standard protobuf structure:

MetricFamily - Top-level container for a family of related metrics
Metric - Individual metric with labels and type-specific data
Metric Types - Counter, Gauge, Summary, Histogram, Untyped
Supporting Types - LabelPair, Exemplar, Bucket, BucketSpan, Quantile

All struct fields are pointers to support optional protobuf semantics. Native histogram features are experimental and subject to change.

Capabilities

MetricType Enum

Defines the type of a metric.

type MetricType int32

const (
    MetricType_COUNTER         MetricType = 0  // Counter metric type
    MetricType_GAUGE           MetricType = 1  // Gauge metric type
    MetricType_SUMMARY         MetricType = 2  // Summary metric type
    MetricType_UNTYPED         MetricType = 3  // Untyped metric type
    MetricType_HISTOGRAM       MetricType = 4  // Histogram metric type
    MetricType_GAUGE_HISTOGRAM MetricType = 5  // Gauge histogram metric type
)

func (MetricType) Descriptor() protoreflect.EnumDescriptor
func (x MetricType) Enum() *MetricType
func (x MetricType) Number() protoreflect.EnumNumber
func (x MetricType) String() string
func (MetricType) Type() protoreflect.EnumType

Usage Example:

metricType := dto.MetricType_COUNTER
fmt.Println(metricType.String()) // "COUNTER"

// Convert from string
if val, ok := dto.MetricType_value["GAUGE"]; ok {
    gaugeType := dto.MetricType(val)
    fmt.Println(gaugeType) // 1
}

MetricFamily

Top-level container representing a family of metrics with the same name and type.

type MetricFamily struct {
    Name   *string
    Help   *string
    Type   *MetricType
    Metric []*Metric
    Unit   *string
}

func (x *MetricFamily) GetName() string
func (x *MetricFamily) GetHelp() string
func (x *MetricFamily) GetType() MetricType
func (x *MetricFamily) GetMetric() []*Metric
func (x *MetricFamily) GetUnit() string
func (*MetricFamily) ProtoMessage()
func (x *MetricFamily) ProtoReflect() protoreflect.Message
func (x *MetricFamily) Reset()
func (x *MetricFamily) String() string

Usage Example:

import "google.golang.org/protobuf/proto"

mf := &dto.MetricFamily{
    Name: proto.String("process_cpu_seconds_total"),
    Help: proto.String("Total user and system CPU time spent in seconds"),
    Type: dto.MetricType_COUNTER.Enum(),
    Unit: proto.String("seconds"),
    Metric: []*dto.Metric{
        {
            Counter: &dto.Counter{Value: proto.Float64(123.45)},
        },
    },
}

fmt.Println(mf.GetName()) // "process_cpu_seconds_total"
fmt.Println(mf.GetType()) // COUNTER

Metric

Represents an individual metric with labels and type-specific data.

type Metric struct {
    Label       []*LabelPair
    Gauge       *Gauge
    Counter     *Counter
    Summary     *Summary
    Untyped     *Untyped
    Histogram   *Histogram
    TimestampMs *int64
}

func (x *Metric) GetLabel() []*LabelPair
func (x *Metric) GetGauge() *Gauge
func (x *Metric) GetCounter() *Counter
func (x *Metric) GetSummary() *Summary
func (x *Metric) GetUntyped() *Untyped
func (x *Metric) GetHistogram() *Histogram
func (x *Metric) GetTimestampMs() int64
func (*Metric) ProtoMessage()
func (x *Metric) ProtoReflect() protoreflect.Message
func (x *Metric) Reset()
func (x *Metric) String() string

Usage Example:

import "google.golang.org/protobuf/proto"

metric := &dto.Metric{
    Label: []*dto.LabelPair{
        {Name: proto.String("instance"), Value: proto.String("localhost:8080")},
        {Name: proto.String("job"), Value: proto.String("api")},
    },
    Counter: &dto.Counter{
        Value: proto.Float64(100.0),
    },
    TimestampMs: proto.Int64(1234567890000),
}

for _, label := range metric.GetLabel() {
    fmt.Printf("%s=%s\n", label.GetName(), label.GetValue())
}

LabelPair

Represents a name-value label pair for metric dimensions.

type LabelPair struct {
    Name  *string
    Value *string
}

func (x *LabelPair) GetName() string
func (x *LabelPair) GetValue() string
func (*LabelPair) ProtoMessage()
func (x *LabelPair) ProtoReflect() protoreflect.Message
func (x *LabelPair) Reset()
func (x *LabelPair) String() string

Usage Example:

import "google.golang.org/protobuf/proto"

label := &dto.LabelPair{
    Name:  proto.String("method"),
    Value: proto.String("POST"),
}

fmt.Printf("%s=%s\n", label.GetName(), label.GetValue()) // "method=POST"

Counter

Represents a counter metric - a monotonically increasing value.

type Counter struct {
    Value            *float64
    Exemplar         *Exemplar
    CreatedTimestamp *timestamppb.Timestamp
}

func (x *Counter) GetValue() float64
func (x *Counter) GetExemplar() *Exemplar
func (x *Counter) GetCreatedTimestamp() *timestamppb.Timestamp
func (*Counter) ProtoMessage()
func (x *Counter) ProtoReflect() protoreflect.Message
func (x *Counter) Reset()
func (x *Counter) String() string

Usage Example:

import (
    "google.golang.org/protobuf/proto"
    "google.golang.org/protobuf/types/known/timestamppb"
    "time"
)

counter := &dto.Counter{
    Value:            proto.Float64(1234.0),
    CreatedTimestamp: timestamppb.New(time.Now()),
}

fmt.Println(counter.GetValue()) // 1234.0

Gauge

Represents a gauge metric - a value that can go up or down.

type Gauge struct {
    Value *float64
}

func (x *Gauge) GetValue() float64
func (*Gauge) ProtoMessage()
func (x *Gauge) ProtoReflect() protoreflect.Message
func (x *Gauge) Reset()
func (x *Gauge) String() string

Usage Example:

import "google.golang.org/protobuf/proto"

gauge := &dto.Gauge{
    Value: proto.Float64(42.7),
}

fmt.Println(gauge.GetValue()) // 42.7

Summary

Represents a summary metric with sample count, sum, and quantiles.

type Summary struct {
    SampleCount      *uint64
    SampleSum        *float64
    Quantile         []*Quantile
    CreatedTimestamp *timestamppb.Timestamp
}

func (x *Summary) GetSampleCount() uint64
func (x *Summary) GetSampleSum() float64
func (x *Summary) GetQuantile() []*Quantile
func (x *Summary) GetCreatedTimestamp() *timestamppb.Timestamp
func (*Summary) ProtoMessage()
func (x *Summary) ProtoReflect() protoreflect.Message
func (x *Summary) Reset()
func (x *Summary) String() string

Usage Example:

import "google.golang.org/protobuf/proto"

summary := &dto.Summary{
    SampleCount: proto.Uint64(1000),
    SampleSum:   proto.Float64(5000.0),
    Quantile: []*dto.Quantile{
        {Quantile: proto.Float64(0.5), Value: proto.Float64(4.5)},
        {Quantile: proto.Float64(0.9), Value: proto.Float64(9.2)},
        {Quantile: proto.Float64(0.99), Value: proto.Float64(12.7)},
    },
}

fmt.Println(summary.GetSampleCount()) // 1000
for _, q := range summary.GetQuantile() {
    fmt.Printf("p%v: %v\n", q.GetQuantile()*100, q.GetValue())
}

Quantile

Represents a quantile value in a summary metric.

type Quantile struct {
    Quantile *float64
    Value    *float64
}

func (x *Quantile) GetQuantile() float64
func (x *Quantile) GetValue() float64
func (*Quantile) ProtoMessage()
func (x *Quantile) ProtoReflect() protoreflect.Message
func (x *Quantile) Reset()
func (x *Quantile) String() string

Histogram

Represents a histogram metric supporting both conventional bucketed histograms and native (sparse) histograms.

type Histogram struct {
    // Conventional histogram fields
    SampleCount      *uint64
    SampleCountFloat *float64
    SampleSum        *float64
    Bucket           []*Bucket
    CreatedTimestamp *timestamppb.Timestamp

    // Native histogram fields (experimental)
    Schema         *int32
    ZeroThreshold  *float64
    ZeroCount      *uint64
    ZeroCountFloat *float64
    NegativeSpan   []*BucketSpan
    NegativeDelta  []int64
    NegativeCount  []float64
    PositiveSpan   []*BucketSpan
    PositiveDelta  []int64
    PositiveCount  []float64
    Exemplars      []*Exemplar
}

func (x *Histogram) GetSampleCount() uint64
func (x *Histogram) GetSampleCountFloat() float64
func (x *Histogram) GetSampleSum() float64
func (x *Histogram) GetBucket() []*Bucket
func (x *Histogram) GetCreatedTimestamp() *timestamppb.Timestamp
func (x *Histogram) GetSchema() int32
func (x *Histogram) GetZeroThreshold() float64
func (x *Histogram) GetZeroCount() uint64
func (x *Histogram) GetZeroCountFloat() float64
func (x *Histogram) GetNegativeSpan() []*BucketSpan
func (x *Histogram) GetNegativeDelta() []int64
func (x *Histogram) GetNegativeCount() []float64
func (x *Histogram) GetPositiveSpan() []*BucketSpan
func (x *Histogram) GetPositiveDelta() []int64
func (x *Histogram) GetPositiveCount() []float64
func (x *Histogram) GetExemplars() []*Exemplar
func (*Histogram) ProtoMessage()
func (x *Histogram) ProtoReflect() protoreflect.Message
func (x *Histogram) Reset()
func (x *Histogram) String() string

Conventional Histogram Usage Example:

import "google.golang.org/protobuf/proto"

histogram := &dto.Histogram{
    SampleCount: proto.Uint64(1000),
    SampleSum:   proto.Float64(5000.0),
    Bucket: []*dto.Bucket{
        {
            CumulativeCount: proto.Uint64(100),
            UpperBound:      proto.Float64(1.0),
        },
        {
            CumulativeCount: proto.Uint64(500),
            UpperBound:      proto.Float64(5.0),
        },
        {
            CumulativeCount: proto.Uint64(900),
            UpperBound:      proto.Float64(10.0),
        },
        {
            CumulativeCount: proto.Uint64(1000),
            UpperBound:      proto.Float64(math.Inf(1)),
        },
    },
}

fmt.Println(histogram.GetSampleCount()) // 1000
for _, bucket := range histogram.GetBucket() {
    fmt.Printf("le=%v: %v\n", bucket.GetUpperBound(), bucket.GetCumulativeCount())
}

Native Histogram Usage Example:

import "google.golang.org/protobuf/proto"

// Native histogram with schema 0 (base-2 bucket boundaries)
nativeHist := &dto.Histogram{
    SampleCount:   proto.Uint64(1000),
    SampleSum:     proto.Float64(5000.0),
    Schema:        proto.Int32(0),
    ZeroThreshold: proto.Float64(0.001),
    ZeroCount:     proto.Uint64(10),
    PositiveSpan: []*dto.BucketSpan{
        {Offset: proto.Int32(0), Length: proto.Uint32(5)},
    },
    PositiveDelta: []int64{100, 50, 30, 20, 10},
}

fmt.Printf("Schema: %d, Zero count: %d\n",
    nativeHist.GetSchema(), nativeHist.GetZeroCount())

Bucket

Represents a bucket in a conventional histogram.

type Bucket struct {
    CumulativeCount      *uint64
    CumulativeCountFloat *float64
    UpperBound           *float64
    Exemplar             *Exemplar
}

func (x *Bucket) GetCumulativeCount() uint64
func (x *Bucket) GetCumulativeCountFloat() float64
func (x *Bucket) GetUpperBound() float64
func (x *Bucket) GetExemplar() *Exemplar
func (*Bucket) ProtoMessage()
func (x *Bucket) ProtoReflect() protoreflect.Message
func (x *Bucket) Reset()
func (x *Bucket) String() string

BucketSpan

Defines consecutive buckets in a native histogram with their offset.

type BucketSpan struct {
    Offset *int32
    Length *uint32
}

func (x *BucketSpan) GetOffset() int32
func (x *BucketSpan) GetLength() uint32
func (*BucketSpan) ProtoMessage()
func (x *BucketSpan) ProtoReflect() protoreflect.Message
func (x *BucketSpan) Reset()
func (x *BucketSpan) String() string

Untyped

Represents an untyped metric.

type Untyped struct {
    Value *float64
}

func (x *Untyped) GetValue() float64
func (*Untyped) ProtoMessage()
func (x *Untyped) ProtoReflect() protoreflect.Message
func (x *Untyped) Reset()
func (x *Untyped) String() string

Exemplar

Represents an exemplar - a specific trace representative of a measurement.

type Exemplar struct {
    Label     []*LabelPair
    Value     *float64
    Timestamp *timestamppb.Timestamp
}

func (x *Exemplar) GetLabel() []*LabelPair
func (x *Exemplar) GetValue() float64
func (x *Exemplar) GetTimestamp() *timestamppb.Timestamp
func (*Exemplar) ProtoMessage()
func (x *Exemplar) ProtoReflect() protoreflect.Message
func (x *Exemplar) Reset()
func (x *Exemplar) String() string

Usage Example:

import (
    "google.golang.org/protobuf/proto"
    "google.golang.org/protobuf/types/known/timestamppb"
    "time"
)

exemplar := &dto.Exemplar{
    Label: []*dto.LabelPair{
        {Name: proto.String("trace_id"), Value: proto.String("abc123")},
    },
    Value:     proto.Float64(42.0),
    Timestamp: timestamppb.New(time.Now()),
}

// Use with Counter
counter := &dto.Counter{
    Value:    proto.Float64(1000.0),
    Exemplar: exemplar,
}

Package-Level Variables

MetricType Enum Maps

var MetricType_name = map[int32]string{
    0: "COUNTER",
    1: "GAUGE",
    2: "SUMMARY",
    3: "UNTYPED",
    4: "HISTOGRAM",
    5: "GAUGE_HISTOGRAM",
}

var MetricType_value = map[string]int32{
    "COUNTER":         0,
    "GAUGE":           1,
    "SUMMARY":         2,
    "UNTYPED":         3,
    "HISTOGRAM":       4,
    "GAUGE_HISTOGRAM": 5,
}

Usage Example:

// Convert MetricType to string
typeName := dto.MetricType_name[int32(dto.MetricType_COUNTER)]
fmt.Println(typeName) // "COUNTER"

// Convert string to MetricType
typeValue := dto.MetricType_value["HISTOGRAM"]
metricType := dto.MetricType(typeValue)
fmt.Println(metricType) // 4

File Descriptor

var File_io_prometheus_client_metrics_proto protoreflect.FileDescriptor

The file descriptor for the metrics.proto file, used for protobuf reflection.

Common Patterns

Creating a Complete MetricFamily

import (
    dto "github.com/prometheus/client_model/go"
    "google.golang.org/protobuf/proto"
)

func createMetricFamily() *dto.MetricFamily {
    return &dto.MetricFamily{
        Name: proto.String("http_request_duration_seconds"),
        Help: proto.String("HTTP request latencies in seconds"),
        Type: dto.MetricType_HISTOGRAM.Enum(),
        Metric: []*dto.Metric{
            {
                Label: []*dto.LabelPair{
                    {Name: proto.String("method"), Value: proto.String("GET")},
                    {Name: proto.String("handler"), Value: proto.String("/api/users")},
                },
                Histogram: &dto.Histogram{
                    SampleCount: proto.Uint64(100),
                    SampleSum:   proto.Float64(0.45),
                    Bucket: []*dto.Bucket{
                        {CumulativeCount: proto.Uint64(20), UpperBound: proto.Float64(0.001)},
                        {CumulativeCount: proto.Uint64(50), UpperBound: proto.Float64(0.01)},
                        {CumulativeCount: proto.Uint64(90), UpperBound: proto.Float64(0.1)},
                        {CumulativeCount: proto.Uint64(100), UpperBound: proto.Float64(1.0)},
                    },
                },
            },
        },
    }
}

Serialization and Deserialization

import (
    dto "github.com/prometheus/client_model/go"
    "google.golang.org/protobuf/proto"
)

// Serialize
mf := &dto.MetricFamily{/* ... */}
data, err := proto.Marshal(mf)
if err != nil {
    // handle error
}

// Deserialize
var mf2 dto.MetricFamily
err = proto.Unmarshal(data, &mf2)
if err != nil {
    // handle error
}

Working with Optional Fields

Since all fields are pointers to support protobuf optional semantics:

import (
    dto "github.com/prometheus/client_model/go"
    "google.golang.org/protobuf/proto"
)

metric := &dto.Metric{}

// Safe access using Get methods (returns zero value if nil)
value := metric.GetTimestampMs() // Returns 0 if TimestampMs is nil

// Setting values using proto helpers
metric.TimestampMs = proto.Int64(1234567890000)

// Checking if a field is set
if metric.TimestampMs != nil {
    fmt.Println("Timestamp is set:", *metric.TimestampMs)
}

Notes

This package is generated code from Protocol Buffer definitions
All struct fields are pointers to support optional protobuf semantics
Use proto.String(), proto.Float64(), proto.Int64(), proto.Uint64(), etc. to create pointer values
Get* methods return zero values if the field is nil
Native histogram features (Schema, ZeroThreshold, etc.) are experimental and subject to change
The protobuf-based exposition format was revived in Prometheus v2.40.0 to support native histograms
Several deprecated methods exist for backward compatibility with older protobuf implementations

Version

Tile

Files

tessl/golang-github-com-prometheus--client-model

To install, run

index.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Prometheus Client Model

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

MetricType Enum

MetricFamily

Metric

LabelPair

Counter

Gauge

Summary

Quantile

Histogram

Bucket

BucketSpan

Untyped

Exemplar

Package-Level Variables

MetricType Enum Maps

File Descriptor

Common Patterns

Creating a Complete MetricFamily

Serialization and Deserialization

Working with Optional Fields

Notes

index.mddocs/