Generate metrics reference docs

.gitattributes

@@ -7,4 +7,5 @@
 # docs
 /docs/content/en/docs/reference/helm-chart.md linguist-generated
 /docs/content/en/docs/reference/grpc-api.md linguist-generated
+/docs/content/en/docs/reference/metrics.md linguist-generated
 /docs/data/tetragon_flags.yaml linguist-generated

.github/workflows/generated-files.yaml

@@ -43,3 +43,6 @@ jobs:
             git status --porcelain
             echo "Please run 'make generate-flags' and submit your changes'"; exit 1
           fi
+      - name: Check metrics docs
+        run: |
+          make lint-metrics-md

Makefile

@@ -118,8 +118,10 @@ help:
 	@echo '        clang-format      - run code formatter on BPF code'
 	@echo '        go-format         - run code formatter on Go code'
 	@echo '        format            - convenience alias for clang-format and go-format'
+	@echo '        lint-metrics-md   - check if metrics documentation is up to date'
 	@echo '    Documentation:'
 	@echo '        docs              - preview documentation website'
+	@echo '        metrics-docs      - generate metrics reference documentation page'
 	@echo 'Options:'
 	@echo '    TARGET_ARCH            - target architecture to build for (e.g. amd64 or arm64)'
 	@echo '    BPF_TARGET_ARCH        - target architecture for BPF progs, set by TARGET_ARCH'
@@ -419,3 +421,28 @@ kind-install-tetragon:
 
 .PHONY: kind-setup
 kind-setup: images kind kind-install-tetragon
+
+METRICS_DOCS_PATH := docs/content/en/docs/reference/metrics.md
+
+.PHONY: metrics-docs
+metrics-docs: tetra
+	echo '---' > $(METRICS_DOCS_PATH)
+	echo 'title: "Metrics"' >> $(METRICS_DOCS_PATH)
+	echo 'description: >' >> $(METRICS_DOCS_PATH)
+	echo '  This reference is autogenerated from the Tetragon Prometheus metrics registry' >> $(METRICS_DOCS_PATH)
+	echo '  using github.com/isovalent/metricstool' >> $(METRICS_DOCS_PATH)
+	echo 'weight: 4' >> $(METRICS_DOCS_PATH)
+	echo '---' >> $(METRICS_DOCS_PATH)
+	echo '{{< comment >}}' >> $(METRICS_DOCS_PATH)
+	echo 'This page is autogenerated via `make metrics-doc` please do not edit directly.' >> $(METRICS_DOCS_PATH)
+	echo '{{< /comment >}}' >> $(METRICS_DOCS_PATH)
+	$(CONTAINER_ENGINE) run --rm -v $(PWD):$(PWD) -w $(PWD) $(GO_IMAGE) ./tetra metrics-docs health >> $(METRICS_DOCS_PATH)
+	$(CONTAINER_ENGINE) run --rm -v $(PWD):$(PWD) -w $(PWD) $(GO_IMAGE) ./tetra metrics-docs resources >> $(METRICS_DOCS_PATH)
+	$(CONTAINER_ENGINE) run --rm -v $(PWD):$(PWD) -w $(PWD) $(GO_IMAGE) ./tetra metrics-docs events >> $(METRICS_DOCS_PATH)
+
+.PHONY: lint-metrics-md
+lint-metrics-md: metrics-docs
+	@if [ -n "$$(git status --porcelain $(METRICS_DOCS_PATH))" ]; then \
+		echo "metrics doc out of sync; please run 'make metrics-docs'" > /dev/stderr; \
+		false; \
+	fi

cmd/tetra/commands_linux.go

@@ -6,6 +6,7 @@ package main
 import (
 	"github.com/cilium/tetragon/cmd/tetra/bugtool"
 	"github.com/cilium/tetragon/cmd/tetra/dump"
+	"github.com/cilium/tetragon/cmd/tetra/metrics"
 	"github.com/cilium/tetragon/cmd/tetra/policyfilter"
 	"github.com/cilium/tetragon/cmd/tetra/probe"
 	"github.com/cilium/tetragon/cmd/tetra/tracingpolicy"
@@ -19,4 +20,5 @@ func addCommands(rootCmd *cobra.Command) {
 	rootCmd.AddCommand(dump.New())
 	rootCmd.AddCommand(policyfilter.New())
 	rootCmd.AddCommand(probe.New())
+	rootCmd.AddCommand(metrics.New())
 }

cmd/tetra/metrics/print.go

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Authors of Tetragon
+
+package metrics
+
+import (
+	"log/slog"
+
+	"github.com/isovalent/metricstool/pkg/metricsmd"
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/spf13/cobra"
+
+	"github.com/cilium/tetragon/pkg/metrics/metricsconfig"
+)
+
+func New() *cobra.Command {
+	targets := map[string]string{
+		"health":    "Tetragon Health",
+		"resources": "Tetragon Resources",
+		"events":    "Tetragon Events",
+	}
+
+	overrides := []metricsmd.LabelOverrides{
+		// Theses metrics takes VCS info into account supplied at build
+		// time, which changes every build, so override those.
+		{
+			Metric: "go_info",
+			Overrides: []metricsmd.LabelValues{
+				{
+					Label:  "version",
+					Values: []string{"go1.22.0"},
+				},
+			},
+		},
+		{
+			Metric: "tetragon_build_info",
+			Overrides: []metricsmd.LabelValues{
+				{
+					Label:  "commit",
+					Values: []string{"931b70f2c9878ba985ba6b589827bea17da6ec33"},
+				},
+				{
+					Label:  "go_version",
+					Values: []string{"go1.22.0"},
+				},
+				{
+					Label:  "modified",
+					Values: []string{"false"},
+				},
+				{
+					Label:  "time",
+					Values: []string{"2022-05-13T15:54:45Z"},
+				},
+			},
+		},
+	}
+
+	config := &metricsmd.Config{
+		Targets:        targets,
+		LabelOverrides: overrides,
+		InitMetrics:    initMetrics,
+		HeadingLevel:   1,
+	}
+
+	cmd, err := metricsmd.NewCmd(nil, nil, config)
+	if err != nil {
+		slog.Error("failed to create metrics-docs command", "error", err)
+	}
+	return cmd
+}
+
+func initMetrics(target string, reg *prometheus.Registry, _ *slog.Logger) error {
+	switch target {
+	case "health":
+		metricsconfig.InitHealthMetricsForDocs(reg)
+	case "resources":
+		metricsconfig.InitResourcesMetricsForDocs(reg)
+	case "events":
+		metricsconfig.InitEventsMetricsForDocs(reg)
+	}
+	return nil
+}