Merge pull request #1815 from bitoku/list-metric-descriptors

Add metricdescs subcommand for ListMetricDescriptors API

Author: k8s-ci-robot

cmd/crictl/main.go

@@ -222,6 +222,7 @@ func main() {
 		statsCommand,
 		podStatsCommand,
 		podMetricsCommand,
+		metricDescriptorsCommand,
 		completionCommand,
 		checkpointContainerCommand,
 		runtimeConfigCommand,

cmd/crictl/metric_descs.go

@@ -0,0 +1,119 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/sirupsen/logrus"
+	"github.com/urfave/cli/v2"
+	cri "k8s.io/cri-api/pkg/apis"
+	pb "k8s.io/cri-api/pkg/apis/runtime/v1"
+)
+
+type metricDescriptorsOptions struct {
+	// output format
+	output string
+}
+
+var metricDescriptorsCommand = &cli.Command{
+	Name:                   "metricdescs",
+	Usage:                  "List metric descriptors. Returns information about the metrics available through the CRI.",
+	UseShortOptionHandling: true,
+	Flags: []cli.Flag{
+		&cli.StringFlag{
+			Name:    "output",
+			Aliases: []string{"o"},
+			Usage:   "Output format, One of: json|yaml",
+		},
+	},
+	Action: func(c *cli.Context) error {
+		if c.NArg() > 0 {
+			return cli.ShowSubcommandHelp(c)
+		}
+
+		client, err := getRuntimeService(c, 0)
+		if err != nil {
+			return fmt.Errorf("get runtime service: %w", err)
+		}
+
+		opts := metricDescriptorsOptions{
+			output: c.String("output"),
+		}
+
+		switch opts.output {
+		case outputTypeJSON, outputTypeYAML, "":
+		default:
+			return cli.ShowSubcommandHelp(c)
+		}
+
+		if err := metricDescriptors(c.Context, client, opts); err != nil {
+			return fmt.Errorf("get metric descriptors: %w", err)
+		}
+
+		return nil
+	},
+}
+
+func metricDescriptors(
+	c context.Context,
+	client cri.RuntimeService,
+	opts metricDescriptorsOptions,
+) error {
+	d := metricDescriptorsDisplayer{opts}
+
+	return d.displayMetricDescriptors(c, client)
+}
+
+type metricDescriptorsDisplayer struct {
+	opts metricDescriptorsOptions
+}
+
+func (m *metricDescriptorsDisplayer) displayMetricDescriptors(
+	c context.Context,
+	client cri.RuntimeService,
+) error {
+	descriptors, err := listMetricDescriptors(c, client)
+	if err != nil {
+		return err
+	}
+
+	response := &pb.ListMetricDescriptorsResponse{Descriptors: descriptors}
+
+	switch m.opts.output {
+	case outputTypeJSON, "":
+		return outputProtobufObjAsJSON(response)
+	case outputTypeYAML:
+		return outputProtobufObjAsYAML(response)
+	}
+
+	return nil
+}
+
+func listMetricDescriptors(ctx context.Context, client cri.RuntimeService) ([]*pb.MetricDescriptor, error) {
+	descriptors, err := InterruptableRPC(ctx, func(ctx context.Context) ([]*pb.MetricDescriptor, error) {
+		return client.ListMetricDescriptors(ctx)
+	})
+	if err != nil {
+		return nil, fmt.Errorf("list metric descriptors: %w", err)
+	}
+
+	logrus.Debugf("MetricDescriptors: %v", descriptors)
+
+	return descriptors, nil
+}

docs/crictl.1

@@ -72,6 +72,10 @@ COMMANDS:
 .IP \(bu 2
 \fBlogs\fR: Fetch the logs of a container
 .IP \(bu 2
+\fBmetricsp\fR: List pod metrics. Metrics are unstructured key/value pairs gathered by CRI meant to replace cAdvisor's /metrics/cadvisor endpoint.
+.IP \(bu 2
+\fBmetricdescs\fR: List metric descriptors. Returns information about the metrics available through the CRI.
+.IP \(bu 2
 \fBport-forward\fR: Forward local port to a pod
 .IP \(bu 2
 \fBps\fR: List containers

docs/crictl.md

@@ -49,6 +49,8 @@ COMMANDS:
 - `imagefsinfo`: Return image filesystem info
 - `inspectp`: Display the status of one or more pods
 - `logs`: Fetch the logs of a container
+- `metricsp`: List pod metrics. Metrics are unstructured key/value pairs gathered by CRI meant to replace cAdvisor's /metrics/cadvisor endpoint.
+- `metricdescs`: List metric descriptors. Returns information about the metrics available through the CRI.
 - `port-forward`: Forward local port to a pod
 - `ps`: List containers
 - `pull`: Pull an image from a registry

test/e2e/metricdescs_test.go

@@ -0,0 +1,49 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"encoding/json"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	. "github.com/onsi/gomega/gexec"
+)
+
+// The actual test suite.
+var _ = t.Describe("metricdescs", func() {
+	It("should list metric descriptors", func() {
+		if t.IsContainerd() {
+			Skip("ListMetricDescriptors is not supported by containerd")
+		}
+		// Run the command with JSON output format
+		res := t.Crictl("metricdescs")
+		Expect(res).To(Exit(0))
+		contents := res.Out.Contents()
+
+		// Verify JSON output is valid
+		var response map[string]any
+		Expect(json.Unmarshal(contents, &response)).NotTo(HaveOccurred())
+
+		// Verify response has expected structure
+		Expect(response).To(HaveKey("descriptors"))
+
+		// Validate descriptors are an array (even if empty)
+		_, ok := response["descriptors"].([]any)
+		Expect(ok).To(BeTrue())
+	})
+})

test/framework/framework.go

@@ -158,3 +158,7 @@ func (t *TestFramework) CrictlRemovePauseImages() {
 		t.CrictlExpectSuccess("rmi "+strings.TrimSpace(strings.Join(output, " ")), "Deleted")
 	}
 }
+
+func (t *TestFramework) IsContainerd() bool {
+	return strings.Contains(crictlRuntimeEndpoint, "containerd")
+}