Merge remote-tracking branch 'prometheus/main' into add-unit

Author: vesari

api/prometheus/v1/example_test.go

@@ -135,7 +135,7 @@ func ExampleAPI_queryRangeWithBasicAuth() {
 	client, err := api.NewClient(api.Config{
 		Address: "http://demo.robustperception.io:9090",
 		// We can use amazing github.com/prometheus/common/config helper!
-		RoundTripper: config.NewBasicAuthRoundTripper("me", "definitely_me", "", api.DefaultRoundTripper),
+		RoundTripper: config.NewBasicAuthRoundTripper("me", "definitely_me", "", "", api.DefaultRoundTripper),
 	})
 	if err != nil {
 		fmt.Printf("Error creating client: %v\n", err)

go.mod

@@ -8,7 +8,7 @@ require (
 	github.com/davecgh/go-spew v1.1.1
 	github.com/json-iterator/go v1.1.12
 	github.com/prometheus/client_model v0.5.0
-	github.com/prometheus/common v0.44.0
+	github.com/prometheus/common v0.45.0
 	github.com/prometheus/procfs v0.12.0
 	golang.org/x/sys v0.13.0
 	google.golang.org/protobuf v1.31.0

prometheus/examples_test.go

@@ -655,3 +655,27 @@ func ExampleNewMetricWithTimestamp() {
 	// Output:
 	// {"gauge":{"value":298.15},"timestampMs":"1257894000012"}
 }
+
+func ExampleNewConstMetricWithCreatedTimestamp() {
+	// Here we have a metric that is reported by an external system.
+	// Besides providing the value, the external system also provides the
+	// timestamp when the metric was created.
+	desc := prometheus.NewDesc(
+		"time_since_epoch_seconds",
+		"Current epoch time in seconds.",
+		nil, nil,
+	)
+
+	timeSinceEpochReportedByExternalSystem := time.Date(2009, time.November, 10, 23, 0, 0, 12345678, time.UTC)
+	epoch := time.Unix(0, 0).UTC()
+	s := prometheus.MustNewConstMetricWithCreatedTimestamp(
+		desc, prometheus.CounterValue, float64(timeSinceEpochReportedByExternalSystem.Unix()), epoch,
+	)
+
+	metric := &dto.Metric{}
+	s.Write(metric)
+	fmt.Println(toNormalizedJSON(metric))
+
+	// Output:
+	// {"counter":{"value":1257894000,"createdTimestamp":"1970-01-01T00:00:00Z"}}
+}

prometheus/gen_go_collector_metrics_set.go

@@ -31,7 +31,7 @@ import (
 	"github.com/prometheus/client_golang/prometheus"
 	"github.com/prometheus/client_golang/prometheus/internal"
 
-	"github.com/hashicorp/go-version"
+	version "github.com/hashicorp/go-version"
 )
 
 func main() {

prometheus/testutil/testutil.go

@@ -47,6 +47,7 @@ import (
 	"github.com/davecgh/go-spew/spew"
 	dto "github.com/prometheus/client_model/go"
 	"github.com/prometheus/common/expfmt"
+	"google.golang.org/protobuf/proto"
 
 	"github.com/prometheus/client_golang/prometheus"
 	"github.com/prometheus/client_golang/prometheus/internal"
@@ -230,6 +231,20 @@ func convertReaderToMetricFamily(reader io.Reader) ([]*dto.MetricFamily, error)
 		return nil, fmt.Errorf("converting reader to metric families failed: %w", err)
 	}
 
+	// The text protocol handles empty help fields inconsistently. When
+	// encoding, any non-nil value, include the empty string, produces a
+	// "# HELP" line. But when decoding, the help field is only set to a
+	// non-nil value if the "# HELP" line contains a non-empty value.
+	//
+	// Because metrics in a registry always have non-nil help fields, populate
+	// any nil help fields in the parsed metrics with the empty string so that
+	// when we compare text encodings, the results are consistent.
+	for _, metric := range notNormalized {
+		if metric.Help == nil {
+			metric.Help = proto.String("")
+		}
+	}
+
 	return internal.NormalizeMetricFamilies(notNormalized), nil
 }
 

prometheus/testutil/testutil_test.go

@@ -168,6 +168,26 @@ func TestCollectAndCompareNoLabel(t *testing.T) {
 	}
 }
 
+func TestCollectAndCompareNoHelp(t *testing.T) {
+	const metadata = `
+		# TYPE some_total counter
+	`
+
+	c := prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "some_total",
+	})
+	c.Inc()
+
+	expected := `
+
+		some_total 1
+	`
+
+	if err := CollectAndCompare(c, strings.NewReader(metadata+expected), "some_total"); err != nil {
+		t.Errorf("unexpected collecting result:\n%s", err)
+	}
+}
+
 func TestCollectAndCompareHistogram(t *testing.T) {
 	inputs := []struct {
 		name        string