chore(docs): generate docs/monitoring/metrics.md file

Makefile

@@ -47,7 +47,7 @@ golangci-lint-verify: golangci-lint
 .PHONY: go-lint
 go-lint: golangci-lint
 	gofmt -l -s -w .
-	golangci-lint run --timeout=30m ./...
+	golangci-lint run --timeout=30m --fix ./...
 
 #? licensecheck: Run the to check for license headers
 .PHONY: licensecheck
@@ -149,7 +149,6 @@ clean:
 	@rm -rf build
 	@go clean -cache
 
-
 .PHONY: release.staging
 #? release.staging: Builds and push container images to the staging bucket.
 release.staging: test
@@ -167,6 +166,11 @@ ko:
 generate-flags-documentation:
 	go run internal/gen/docs/flags/main.go
 
+.PHONY: generate-metrics-documentation
+#? generate-metrics-documentation: Generate documentation (docs/monitoring/metrics.md)
+generate-metrics-documentation:
+	go run internal/gen/docs/metrics/main.go
+
 #? pre-commit-install: Install pre-commit hooks
 pre-commit-install:
 	@pre-commit install

controller/controller.go

@@ -27,124 +27,125 @@ import (
 	log "github.com/sirupsen/logrus"
 
 	"sigs.k8s.io/external-dns/endpoint"
+	"sigs.k8s.io/external-dns/pkg/metrics"
 	"sigs.k8s.io/external-dns/plan"
 	"sigs.k8s.io/external-dns/provider"
 	"sigs.k8s.io/external-dns/registry"
 	"sigs.k8s.io/external-dns/source"
 )
 
 var (
-	registryErrorsTotal = prometheus.NewCounter(
+	registryErrorsTotal = metrics.NewCounterWithOpts(
 		prometheus.CounterOpts{
 			Namespace: "external_dns",
 			Subsystem: "registry",
 			Name:      "errors_total",
 			Help:      "Number of Registry errors.",
 		},
 	)
-	sourceErrorsTotal = prometheus.NewCounter(
+	sourceErrorsTotal = metrics.NewCounterWithOpts(
 		prometheus.CounterOpts{
 			Namespace: "external_dns",
 			Subsystem: "source",
 			Name:      "errors_total",
 			Help:      "Number of Source errors.",
 		},
 	)
-	sourceEndpointsTotal = prometheus.NewGauge(
+	sourceEndpointsTotal = metrics.NewGaugeWithOpts(
 		prometheus.GaugeOpts{
 			Namespace: "external_dns",
 			Subsystem: "source",
 			Name:      "endpoints_total",
 			Help:      "Number of Endpoints in all sources",
 		},
 	)
-	registryEndpointsTotal = prometheus.NewGauge(
+	registryEndpointsTotal = metrics.NewGaugeWithOpts(
 		prometheus.GaugeOpts{
 			Namespace: "external_dns",
 			Subsystem: "registry",
 			Name:      "endpoints_total",
 			Help:      "Number of Endpoints in the registry",
 		},
 	)
-	lastSyncTimestamp = prometheus.NewGauge(
+	lastSyncTimestamp = metrics.NewGaugeWithOpts(
 		prometheus.GaugeOpts{
 			Namespace: "external_dns",
 			Subsystem: "controller",
 			Name:      "last_sync_timestamp_seconds",
 			Help:      "Timestamp of last successful sync with the DNS provider",
 		},
 	)
-	lastReconcileTimestamp = prometheus.NewGauge(
+	lastReconcileTimestamp = metrics.NewGaugeWithOpts(
 		prometheus.GaugeOpts{
 			Namespace: "external_dns",
 			Subsystem: "controller",
 			Name:      "last_reconcile_timestamp_seconds",
 			Help:      "Timestamp of last attempted sync with the DNS provider",
 		},
 	)
-	controllerNoChangesTotal = prometheus.NewCounter(
+	controllerNoChangesTotal = metrics.NewCounterWithOpts(
 		prometheus.CounterOpts{
 			Namespace: "external_dns",
 			Subsystem: "controller",
 			Name:      "no_op_runs_total",
 			Help:      "Number of reconcile loops ending up with no changes on the DNS provider side.",
 		},
 	)
-	deprecatedRegistryErrors = prometheus.NewCounter(
+	deprecatedRegistryErrors = metrics.NewCounterWithOpts(
 		prometheus.CounterOpts{
 			Subsystem: "registry",
 			Name:      "errors_total",
 			Help:      "Number of Registry errors.",
 		},
 	)
-	deprecatedSourceErrors = prometheus.NewCounter(
+	deprecatedSourceErrors = metrics.NewCounterWithOpts(
 		prometheus.CounterOpts{
 			Subsystem: "source",
 			Name:      "errors_total",
 			Help:      "Number of Source errors.",
 		},
 	)
-	registryARecords = prometheus.NewGauge(
+	registryARecords = metrics.NewGaugeWithOpts(
 		prometheus.GaugeOpts{
 			Namespace: "external_dns",
 			Subsystem: "registry",
 			Name:      "a_records",
 			Help:      "Number of Registry A records.",
 		},
 	)
-	registryAAAARecords = prometheus.NewGauge(
+	registryAAAARecords = metrics.NewGaugeWithOpts(
 		prometheus.GaugeOpts{
 			Namespace: "external_dns",
 			Subsystem: "registry",
 			Name:      "aaaa_records",
 			Help:      "Number of Registry AAAA records.",
 		},
 	)
-	sourceARecords = prometheus.NewGauge(
+	sourceARecords = metrics.NewGaugeWithOpts(
 		prometheus.GaugeOpts{
 			Namespace: "external_dns",
 			Subsystem: "source",
 			Name:      "a_records",
 			Help:      "Number of Source A records.",
 		},
 	)
-	sourceAAAARecords = prometheus.NewGauge(
+	sourceAAAARecords = metrics.NewGaugeWithOpts(
 		prometheus.GaugeOpts{
 			Namespace: "external_dns",
 			Subsystem: "source",
 			Name:      "aaaa_records",
 			Help:      "Number of Source AAAA records.",
 		},
 	)
-	verifiedARecords = prometheus.NewGauge(
+	verifiedARecords = metrics.NewGaugeWithOpts(
 		prometheus.GaugeOpts{
 			Namespace: "external_dns",
 			Subsystem: "controller",
 			Name:      "verified_a_records",
 			Help:      "Number of DNS A-records that exists both in source and registry.",
 		},
 	)
-	verifiedAAAARecords = prometheus.NewGauge(
+	verifiedAAAARecords = metrics.NewGaugeWithOpts(
 		prometheus.GaugeOpts{
 			Namespace: "external_dns",
 			Subsystem: "controller",
@@ -155,21 +156,21 @@ var (
 )
 
 func init() {
-	prometheus.MustRegister(registryErrorsTotal)
-	prometheus.MustRegister(sourceErrorsTotal)
-	prometheus.MustRegister(sourceEndpointsTotal)
-	prometheus.MustRegister(registryEndpointsTotal)
-	prometheus.MustRegister(lastSyncTimestamp)
-	prometheus.MustRegister(lastReconcileTimestamp)
-	prometheus.MustRegister(deprecatedRegistryErrors)
-	prometheus.MustRegister(deprecatedSourceErrors)
-	prometheus.MustRegister(controllerNoChangesTotal)
-	prometheus.MustRegister(registryARecords)
-	prometheus.MustRegister(registryAAAARecords)
-	prometheus.MustRegister(sourceARecords)
-	prometheus.MustRegister(sourceAAAARecords)
-	prometheus.MustRegister(verifiedARecords)
-	prometheus.MustRegister(verifiedAAAARecords)
+	metrics.RegisterMetric.MustRegister(registryErrorsTotal)
+	metrics.RegisterMetric.MustRegister(sourceErrorsTotal)
+	metrics.RegisterMetric.MustRegister(sourceEndpointsTotal)
+	metrics.RegisterMetric.MustRegister(registryEndpointsTotal)
+	metrics.RegisterMetric.MustRegister(lastSyncTimestamp)
+	metrics.RegisterMetric.MustRegister(lastReconcileTimestamp)
+	metrics.RegisterMetric.MustRegister(deprecatedRegistryErrors)
+	metrics.RegisterMetric.MustRegister(deprecatedSourceErrors)
+	metrics.RegisterMetric.MustRegister(controllerNoChangesTotal)
+	metrics.RegisterMetric.MustRegister(registryARecords)
+	metrics.RegisterMetric.MustRegister(registryAAAARecords)
+	metrics.RegisterMetric.MustRegister(sourceARecords)
+	metrics.RegisterMetric.MustRegister(sourceAAAARecords)
+	metrics.RegisterMetric.MustRegister(verifiedARecords)
+	metrics.RegisterMetric.MustRegister(verifiedAAAARecords)
 }
 
 // Controller is responsible for orchestrating the different components.
@@ -203,38 +204,38 @@ type Controller struct {
 
 // RunOnce runs a single iteration of a reconciliation loop.
 func (c *Controller) RunOnce(ctx context.Context) error {
-	lastReconcileTimestamp.SetToCurrentTime()
+	lastReconcileTimestamp.Gauge.SetToCurrentTime()
 
 	c.runAtMutex.Lock()
 	c.lastRunAt = time.Now()
 	c.runAtMutex.Unlock()
 
 	records, err := c.Registry.Records(ctx)
 	if err != nil {
-		registryErrorsTotal.Inc()
-		deprecatedRegistryErrors.Inc()
+		registryErrorsTotal.Counter.Inc()
+		deprecatedRegistryErrors.Counter.Inc()
 		return err
 	}
 
-	registryEndpointsTotal.Set(float64(len(records)))
+	registryEndpointsTotal.Gauge.Set(float64(len(records)))
 	regARecords, regAAAARecords := countAddressRecords(records)
-	registryARecords.Set(float64(regARecords))
-	registryAAAARecords.Set(float64(regAAAARecords))
+	registryARecords.Gauge.Set(float64(regARecords))
+	registryAAAARecords.Gauge.Set(float64(regAAAARecords))
 	ctx = context.WithValue(ctx, provider.RecordsContextKey, records)
 
 	endpoints, err := c.Source.Endpoints(ctx)
 	if err != nil {
-		sourceErrorsTotal.Inc()
-		deprecatedSourceErrors.Inc()
+		sourceErrorsTotal.Counter.Inc()
+		deprecatedSourceErrors.Counter.Inc()
 		return err
 	}
-	sourceEndpointsTotal.Set(float64(len(endpoints)))
+	sourceEndpointsTotal.Gauge.Set(float64(len(endpoints)))
 	srcARecords, srcAAAARecords := countAddressRecords(endpoints)
-	sourceARecords.Set(float64(srcARecords))
-	sourceAAAARecords.Set(float64(srcAAAARecords))
+	sourceARecords.Gauge.Set(float64(srcARecords))
+	sourceAAAARecords.Gauge.Set(float64(srcAAAARecords))
 	vARecords, vAAAARecords := countMatchingAddressRecords(endpoints, records)
-	verifiedARecords.Set(float64(vARecords))
-	verifiedAAAARecords.Set(float64(vAAAARecords))
+	verifiedARecords.Gauge.Set(float64(vARecords))
+	verifiedAAAARecords.Gauge.Set(float64(vAAAARecords))
 	endpoints, err = c.Registry.AdjustEndpoints(endpoints)
 	if err != nil {
 		return fmt.Errorf("adjusting endpoints: %w", err)
@@ -256,16 +257,16 @@ func (c *Controller) RunOnce(ctx context.Context) error {
 	if plan.Changes.HasChanges() {
 		err = c.Registry.ApplyChanges(ctx, plan.Changes)
 		if err != nil {
-			registryErrorsTotal.Inc()
-			deprecatedRegistryErrors.Inc()
+			registryErrorsTotal.Counter.Inc()
+			deprecatedRegistryErrors.Counter.Inc()
 			return err
 		}
 	} else {
-		controllerNoChangesTotal.Inc()
+		controllerNoChangesTotal.Counter.Inc()
 		log.Info("All records are already up to date")
 	}
 
-	lastSyncTimestamp.SetToCurrentTime()
+	lastSyncTimestamp.Gauge.SetToCurrentTime()
 
 	return nil
 }

controller/controller_test.go

@@ -234,8 +234,8 @@ func TestRunOnce(t *testing.T) {
 	// Validate that the mock source was called.
 	source.AssertExpectations(t)
 	// check the verified records
-	assert.Equal(t, math.Float64bits(1), valueFromMetric(verifiedARecords))
-	assert.Equal(t, math.Float64bits(1), valueFromMetric(verifiedAAAARecords))
+	assert.Equal(t, math.Float64bits(1), valueFromMetric(verifiedARecords.Gauge))
+	assert.Equal(t, math.Float64bits(1), valueFromMetric(verifiedAAAARecords.Gauge))
 }
 
 // TestRun tests that Run correctly starts and stops
@@ -268,8 +268,8 @@ func TestRun(t *testing.T) {
 	// Validate that the mock source was called.
 	source.AssertExpectations(t)
 	// check the verified records
-	assert.Equal(t, math.Float64bits(1), valueFromMetric(verifiedARecords))
-	assert.Equal(t, math.Float64bits(1), valueFromMetric(verifiedAAAARecords))
+	assert.Equal(t, math.Float64bits(1), valueFromMetric(verifiedARecords.Gauge))
+	assert.Equal(t, math.Float64bits(1), valueFromMetric(verifiedAAAARecords.Gauge))
 }
 
 func valueFromMetric(metric prometheus.Gauge) uint64 {
@@ -520,7 +520,7 @@ func TestVerifyARecords(t *testing.T) {
 		},
 		[]*plan.Changes{},
 	)
-	assert.Equal(t, math.Float64bits(2), valueFromMetric(verifiedARecords))
+	assert.Equal(t, math.Float64bits(2), valueFromMetric(verifiedARecords.Gauge))
 
 	testControllerFiltersDomains(
 		t,
@@ -564,8 +564,8 @@ func TestVerifyARecords(t *testing.T) {
 			},
 		}},
 	)
-	assert.Equal(t, math.Float64bits(2), valueFromMetric(verifiedARecords))
-	assert.Equal(t, math.Float64bits(0), valueFromMetric(verifiedAAAARecords))
+	assert.Equal(t, math.Float64bits(2), valueFromMetric(verifiedARecords.Gauge))
+	assert.Equal(t, math.Float64bits(0), valueFromMetric(verifiedAAAARecords.Gauge))
 }
 
 func TestVerifyAAAARecords(t *testing.T) {
@@ -598,7 +598,7 @@ func TestVerifyAAAARecords(t *testing.T) {
 		},
 		[]*plan.Changes{},
 	)
-	assert.Equal(t, math.Float64bits(2), valueFromMetric(verifiedAAAARecords))
+	assert.Equal(t, math.Float64bits(2), valueFromMetric(verifiedAAAARecords.Gauge))
 
 	testControllerFiltersDomains(
 		t,
@@ -642,8 +642,8 @@ func TestVerifyAAAARecords(t *testing.T) {
 			},
 		}},
 	)
-	assert.Equal(t, math.Float64bits(0), valueFromMetric(verifiedARecords))
-	assert.Equal(t, math.Float64bits(2), valueFromMetric(verifiedAAAARecords))
+	assert.Equal(t, math.Float64bits(0), valueFromMetric(verifiedARecords.Gauge))
+	assert.Equal(t, math.Float64bits(2), valueFromMetric(verifiedAAAARecords.Gauge))
 }
 
 func TestARecords(t *testing.T) {
@@ -689,8 +689,8 @@ func TestARecords(t *testing.T) {
 			},
 		}},
 	)
-	assert.Equal(t, math.Float64bits(2), valueFromMetric(sourceARecords))
-	assert.Equal(t, math.Float64bits(1), valueFromMetric(registryARecords))
+	assert.Equal(t, math.Float64bits(2), valueFromMetric(sourceARecords.Gauge))
+	assert.Equal(t, math.Float64bits(1), valueFromMetric(registryARecords.Gauge))
 }
 
 func TestAAAARecords(t *testing.T) {
@@ -736,6 +736,6 @@ func TestAAAARecords(t *testing.T) {
 			},
 		}},
 	)
-	assert.Equal(t, math.Float64bits(2), valueFromMetric(sourceAAAARecords))
-	assert.Equal(t, math.Float64bits(1), valueFromMetric(registryAAAARecords))
+	assert.Equal(t, math.Float64bits(2), valueFromMetric(sourceAAAARecords.Gauge))
+	assert.Equal(t, math.Float64bits(1), valueFromMetric(registryAAAARecords.Gauge))
 }

docs/contributing/dev-guide.md

@@ -38,10 +38,11 @@ make test
 make cover-html
 ```
 
-If added any flags, re-generate flags documentation
+If added any flags or metrics, re-generate documentation
 
 ```shell
 make generate-flags-documentation
+make generate-metrics-documentation
 ```
 
 We require all changes to be covered by acceptance tests and/or unit tests, depending on the situation.