github.com/prometheus/client_golang v1.19.1: prometheus.Registry

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 github.com/prometheus/client_golang/prometheus.Registry in pkg:golang/github.com/prometheus/client_golang@v1.19.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/prometheus/client_golang@v1.19.1
Demonstrate these symbols/APIs:
  - github.com/prometheus/client_golang/prometheus.Registry

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:dbac26989b994145d0fb7c6794cc4963cdc5b3e492a2fc510f263f07e608bd3e","contract":["prometheus.NewRegistry creates a dedicated collector registry","prometheus.Registry.Register adds collectors and returns AlreadyRegisteredError on duplicate","prometheus.Registry.Unregister removes registered collectors","prometheus.Registry.Gather collects metric families from registered standard and custom collectors"],"goal":"verify github.com/prometheus/client_golang/prometheus.Registry in pkg:golang/github.com/prometheus/client_golang@v1.19.1","kind":"HOW","packages":["pkg:golang/github.com/prometheus/client_golang@v1.19.1"],"schemaVersion":1,"symbols":["github.com/prometheus/client_golang/prometheus.Registry"]},"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/github.com/prometheus/client_golang@v1.19.1"],"schemaVersion":1,"subject":"pkg:golang/github.com/prometheus/client_golang@v1.19.1","symbols":["github.com/prometheus/client_golang/prometheus.Registry"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require (
	github.com/prometheus/client_golang v1.19.1
	github.com/prometheus/client_model v0.5.0
)

require (
	github.com/beorn7/perks v1.0.1 // indirect
	github.com/cespare/xxhash/v2 v2.2.0 // indirect
	github.com/prometheus/common v0.48.0 // indirect
	github.com/prometheus/procfs v0.12.0 // indirect
	golang.org/x/sys v0.17.0 // indirect
	google.golang.org/protobuf v1.33.0 // indirect
)

github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44=
github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
github.com/prometheus/client_golang v1.19.1 h1:wZWJDwK+NameRJuPGDhlnFgx8e8HN3XHQeLaYJFJBOE=
github.com/prometheus/client_golang v1.19.1/go.mod h1:mP78NwGzrVks5S2H6ab8+ZZGJLZUq1hoULYBAYBw1Ho=
github.com/prometheus/client_model v0.5.0 h1:VQw1hfvPvk3Uv6Qf29VrPF32JB6rtbgI6cYPYQjL0Qw=
github.com/prometheus/client_model v0.5.0/go.mod h1:dTiFglRmd66nLR9Pv9f0mZi7B7fk5Pm3gvsjB5tr+kI=
github.com/prometheus/common v0.48.0 h1:QO8U2CdOzSn1BBsmXJXduaaW+dY/5QLjfB8svtSzKKE=
github.com/prometheus/common v0.48.0/go.mod h1:0/KsvlIEfPQCQ5I2iNSAWKPZziNCvRs5EC6ILDTlAPc=
github.com/prometheus/procfs v0.12.0 h1:jluTpSng7V9hY0O2R9DzzJHYb2xULk9VTR1V1R/k6Bo=
github.com/prometheus/procfs v0.12.0/go.mod h1:pcuDEFsWDnvcgNzo4EEweacyhjeA9Zk3cnaOZAZEfOo=
golang.org/x/sys v0.17.0 h1:25cE3gD+tdBA7lp7QfhuV+rJiE9YXTcS3VG1SqssI/Y=
golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
google.golang.org/protobuf v1.33.0 h1:uNO2rsAINq/JlFpSdYEKIZ0uKD/R9cpdv0T+yoGwGmI=
google.golang.org/protobuf v1.33.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=

package sample

import (
	"github.com/prometheus/client_golang/prometheus"
	dto "github.com/prometheus/client_model/go"
)

// CustomCollector demonstrates a custom prometheus.Collector with dynamic metric values.
type CustomCollector struct {
	desc  *prometheus.Desc
	value float64
}

// NewCustomCollector creates a new CustomCollector with a defined descriptor.
func NewCustomCollector(name, help string, value float64) *CustomCollector {
	return &CustomCollector{
		desc: prometheus.NewDesc(
			name,
			help,
			nil,
			prometheus.Labels{"source": "custom_collector"},
		),
		value: value,
	}
}

// Describe sends the super-set of all possible descriptors of metrics the Collector will collect.
func (c *CustomCollector) Describe(ch chan<- *prometheus.Desc) {
	ch <- c.desc
}

// Collect is called by the Prometheus registry when collecting metrics.
func (c *CustomCollector) Collect(ch chan<- prometheus.Metric) {
	ch <- prometheus.MustNewConstMetric(
		c.desc,
		prometheus.GaugeValue,
		c.value,
	)
}

// RegistryManager manages registration, unregistration, and gathering on a prometheus.Registry.
type RegistryManager struct {
	Registry *prometheus.Registry
}

// NewRegistryManager initializes a new prometheus.Registry instance.
func NewRegistryManager() *RegistryManager {
	return &RegistryManager{
		Registry: prometheus.NewRegistry(),
	}
}

// RegisterCollector registers a Collector and detects duplicate registrations.
func (m *RegistryManager) RegisterCollector(c prometheus.Collector) error {
	return m.Registry.Register(c)
}

// UnregisterCollector unregisters a Collector from the Registry.
func (m *RegistryManager) UnregisterCollector(c prometheus.Collector) bool {
	return m.Registry.Unregister(c)
}

// GatherMetrics collects and returns all MetricFamilies from registered collectors.
func (m *RegistryManager) GatherMetrics() ([]*dto.MetricFamily, error) {
	return m.Registry.Gather()
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/prometheus/client_golang/prometheus.Registry in pkg:golang/github.com/prometheus/client_golang@v1.19.1",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/prometheus/client_golang@v1.19.1"
  ],
  "symbols": [
    "github.com/prometheus/client_golang/prometheus.Registry"
  ]
}

package main

import (
	"errors"
	"fmt"
	"os"

	"sample"

	"github.com/prometheus/client_golang/prometheus"
	dto "github.com/prometheus/client_model/go"
)

func main() {
	mgr := sample.NewRegistryManager()
	if mgr == nil || mgr.Registry == nil {
		fmt.Fprintf(os.Stderr, "failed to initialize prometheus.Registry\n")
		os.Exit(1)
	}

	// 1. Register a standard counter metric
	counter := prometheus.NewCounter(prometheus.CounterOpts{
		Name: "sample_ops_total",
		Help: "Total number of sample operations performed.",
	})
	if err := mgr.RegisterCollector(counter); err != nil {
		fmt.Fprintf(os.Stderr, "failed to register counter: %v\n", err)
		os.Exit(1)
	}
	counter.Add(5)

	// 2. Duplicate registration should return prometheus.AlreadyRegisteredError
	dupErr := mgr.RegisterCollector(counter)
	if dupErr == nil {
		fmt.Fprintf(os.Stderr, "expected duplicate registration error, got nil\n")
		os.Exit(1)
	}
	var alreadyRegistered prometheus.AlreadyRegisteredError
	if !errors.As(dupErr, &alreadyRegistered) {
		fmt.Fprintf(os.Stderr, "expected AlreadyRegisteredError, got %T: %v\n", dupErr, dupErr)
		os.Exit(1)
	}

	// 3. Register a custom collector
	customCol := sample.NewCustomCollector("sample_custom_metric", "Custom dynamic metric value", 99.5)
	if err := mgr.RegisterCollector(customCol); err != nil {
		fmt.Fprintf(os.Stderr, "failed to register custom collector: %v\n", err)
		os.Exit(1)
	}

	// 4. Gather metrics from the registry and verify both collectors are collected
	mfs, err := mgr.GatherMetrics()
	if err != nil {
		fmt.Fprintf(os.Stderr, "GatherMetrics failed: %v\n", err)
		os.Exit(1)
	}

	famMap := make(map[string]*dto.MetricFamily)
	for _, mf := range mfs {
		famMap[mf.GetName()] = mf
	}

	counterMF, ok := famMap["sample_ops_total"]
	if !ok || counterMF.GetType() != dto.MetricType_COUNTER {
		fmt.Fprintf(os.Stderr, "sample_ops_total missing or unexpected type\n")
		os.Exit(1)
	}
	if len(counterMF.GetMetric()) != 1 || counterMF.GetMetric()[0].GetCounter().GetValue() != 5 {
		fmt.Fprintf(os.Stderr, "unexpected counter value: %v\n", counterMF.GetMetric())
		os.Exit(1)
	}

	customMF, ok := famMap["sample_custom_metric"]
	if !ok || customMF.GetType() != dto.MetricType_GAUGE {
		fmt.Fprintf(os.Stderr, "sample_custom_metric missing or unexpected type\n")
		os.Exit(1)
	}
	if len(customMF.GetMetric()) != 1 || customMF.GetMetric()[0].GetGauge().GetValue() != 99.5 {
		fmt.Fprintf(os.Stderr, "unexpected custom metric value: %v\n", customMF.GetMetric())
		os.Exit(1)
	}

	// 5. Unregister custom collector and verify it is removed from subsequent gather
	if !mgr.UnregisterCollector(customCol) {
		fmt.Fprintf(os.Stderr, "expected Unregister to return true for registered collector\n")
		os.Exit(1)
	}
	// Unregistering again should return false
	if mgr.UnregisterCollector(customCol) {
		fmt.Fprintf(os.Stderr, "expected Unregister to return false for already unregistered collector\n")
		os.Exit(1)
	}

	// Gather again to confirm custom metric is gone
	mfsAfter, err := mgr.GatherMetrics()
	if err != nil {
		fmt.Fprintf(os.Stderr, "GatherMetrics after unregister failed: %v\n", err)
		os.Exit(1)
	}
	if len(mfsAfter) != 1 || mfsAfter[0].GetName() != "sample_ops_total" {
		fmt.Fprintf(os.Stderr, "expected only 1 metric family remaining after unregister, got %d\n", len(mfsAfter))
		os.Exit(1)
	}

	fmt.Println("All prometheus.Registry contract assertions passed.")
}