Metrics API - Kubernetes Dashboard

Overview

The Kubernetes Dashboard Metrics API provides access to resource metrics through integration with the metrics-scraper sidecar. Metrics include CPU usage, memory usage, and custom application metrics.

Metrics Architecture

The metrics system consists of:

Metrics-Scraper Sidecar: Collects metrics from Kubernetes metrics server
Integration Manager: Manages metrics provider connections
Metric Client: Downloads and aggregates metric data
REST API: Exposes metrics through Dashboard endpoints

Configuration

Metrics Provider

--metrics-provider

string

default:"sidecar"

Metrics provider to useOptions:

sidecar: Use the metrics-scraper sidecar (default)
none: Disable metrics collection

--sidecar-host

string

Metrics-scraper sidecar host URLExample: http://dashboard-metrics-scraper:8000

--metric-client-check-period

duration

default:"30s"

Health check interval for metrics client

In-Cluster Configuration

When running in-cluster, the sidecar is accessed via Kubernetes service:

apiVersion: v1
kind: Service
metadata:
  name: dashboard-metrics-scraper
  namespace: kubernetes-dashboard
spec:
  ports:
  - port: 8000
  selector:
    app: dashboard-metrics-scraper

Metrics Integration

Sidecar Integration

The API integrates with the metrics-scraper sidecar:

integrationManager.Metric().
    ConfigureSidecar(args.SidecarHost()).
    EnableWithRetry(
        integrationapi.SidecarIntegrationID,
        time.Duration(args.MetricClientHealthCheckPeriod()),
    )

Health Check

Check metrics integration health:

GET /api/v1/integration/sidecar/health

endpoint

Health check for sidecar metrics integration

healthy

boolean

Whether the integration is healthy

message

string

Health status message

Available Metrics

CPU Metrics

metricNames=cpu/usage

metric

CPU usage in nanocores

metricNames=cpu/request

metric

CPU request in nanocores

metricNames=cpu/limit

metric

CPU limit in nanocores

Memory Metrics

metricNames=memory/usage

metric

Memory usage in bytes

metricNames=memory/request

metric

Memory request in bytes

metricNames=memory/limit

metric

Memory limit in bytes

Query Parameters

Metric Names

metricNames

string

Comma-separated list of metrics to retrieveExample: metricNames=cpu/usage,memory/usage

Aggregations

aggregations

string

default:"sum"

Aggregation method for metricsOptions:

sum: Sum all values
avg: Average of values
min: Minimum value
max: Maximum value

Resource-Specific Metrics

Many resource endpoints support the metricNames query parameter to include metrics in the response.

Pod Metrics

GET /api/v1/pod/{namespace}?metricNames=cpu/usage,memory/usage

endpoint

Get pods with CPU and memory metrics

Example Request

curl -X GET \
  'https://dashboard.example.com/api/v1/pod/default?metricNames=cpu/usage,memory/usage' \
  -H 'Authorization: Bearer <token>'

Example Response

{
  "listMeta": {
    "totalItems": 2
  },
  "items": [
    {
      "objectMeta": {
        "name": "nginx-pod",
        "namespace": "default"
      },
      "metrics": {
        "cpu/usage": {
          "metricName": "cpu/usage",
          "dataPoints": [
            {
              "x": 1709632800000,
              "y": 50000000
            }
          ],
          "metricPoints": [
            {
              "timestamp": "2026-03-05T10:00:00Z",
              "value": 50000000
            }
          ]
        },
        "memory/usage": {
          "metricName": "memory/usage",
          "dataPoints": [
            {
              "x": 1709632800000,
              "y": 104857600
            }
          ],
          "metricPoints": [
            {
              "timestamp": "2026-03-05T10:00:00Z",
              "value": 104857600
            }
          ]
        }
      }
    }
  ]
}

Deployment Metrics

GET /api/v1/deployment/{namespace}?metricNames=cpu/usage

endpoint

Get deployments with aggregated metrics from all pods

Node Metrics

GET /api/v1/node?metricNames=cpu/usage,memory/usage

endpoint

Get nodes with system metrics

Metric Data Structures

Metric Object

metricName

string

Name of the metric (e.g., cpu/usage)

dataPoints

array

Array of data points for chartingStructure:

[
  {
    "x": 1709632800000,  // timestamp in milliseconds
    "y": 50000000        // metric value
  }
]

metricPoints

array

Array of metric points with timestampsStructure:

[
  {
    "timestamp": "2026-03-05T10:00:00Z",
    "value": 50000000
  }
]

label

object

Resource labels for the metricStructure:

{
  "pod": ["nginx-pod-uid"],
  "namespace": ["default"]
}

Sidecar REST API

The metrics-scraper sidecar exposes its own REST API:

Base Path

/api/v1/dashboard/

Pod Metrics

GET /api/v1/dashboard/{namespace}/pod/{pod}/metrics/{metric}

endpoint

Get metrics for a specific pod

Batch Pod Metrics

GET /api/v1/dashboard/{namespace}/pod/{pod1},{pod2},{pod3}/metrics/{metric}

endpoint

Get metrics for multiple pods in one request

Node Metrics

GET /api/v1/dashboard/node/{node}/metrics/{metric}

endpoint

Get metrics for a specific node

Metric Client Interface

The Dashboard uses a metric client interface to download and aggregate metrics:

Download Metrics

DownloadMetrics(
    selectors []ResourceSelector,
    metricNames []string,
    cachedResources *CachedResources,
) MetricPromises

Aggregate Metrics

AggregateMetrics(
    metrics MetricPromises,
    metricName string,
    aggregations AggregationModes,
) MetricPromises

Resource Selectors

Metric downloads use resource selectors to specify target resources:

type ResourceSelector struct {
    Namespace      string
    ResourceType   string
    ResourceName   string
    UID            types.UID
}

Example

{
  "namespace": "default",
  "resourceType": "pod",
  "resourceName": "nginx-pod",
  "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Aggregation Modes

Sum Aggregation

Adds all metric values:

{
  "aggregation": "sum",
  "value": 150000000
}

Average Aggregation

Calculates the mean:

{
  "aggregation": "avg",
  "value": 50000000
}

Min/Max Aggregation

Finds minimum or maximum values:

{
  "aggregation": "max",
  "value": 75000000
}

Batch Metric Downloads

The system optimizes metric downloads by:

Compressing selectors: Combining similar requests
Batch downloads: Downloading multiple resources in one request
Parallel processing: Using goroutines for concurrent downloads

All-in-One Downloads

Supported resource types for batch downloads:

Pods
Nodes
PersistentVolumeClaims

var SidecarAllInOneDownloadConfig = map[string]bool{
    "pod":                     true,
    "node":                    true,
    "persistentvolumeclaim":   true,
}

Metric Promises

Metrics are returned as promises for asynchronous processing:

type MetricPromise struct {
    Metric chan *Metric
    Error  chan error
}

Usage Example

promise := client.DownloadMetric(selectors, "cpu/usage", nil)
metric, err := promise.GetMetric()
if err != nil {
    // handle error
}
fmt.Printf("CPU Usage: %d nanocores\n", metric.DataPoints[0].Y)

Prometheus Metrics

The Dashboard exposes its own Prometheus metrics at:

GET /metrics

endpoint

Prometheus metrics endpoint

Available Metrics

apiserver_request_count

counter

Total API requests by verb, resource, client, content type, and codeLabels: verb, resource, client, contentType, code

apiserver_request_latencies

histogram

Request latency distribution in microsecondsLabels: verb, resourceBuckets: 125ms, 250ms, 500ms, 1s, 2s, 4s, 8s

apiserver_request_latencies_summary

summary

Request latency summary with 1-hour sliding windowLabels: verb, resource

Error Handling

Metric Unavailable

When metrics are not available:

{
  "metrics": null,
  "warning": "Metrics not available"
}

Sidecar Connection Error

If the sidecar is unreachable:

{
  "status": "Failure",
  "message": "Unable to connect to metrics sidecar",
  "code": 503
}

Example: Complete Metrics Query

Request

curl -X GET \
  'https://dashboard.example.com/api/v1/deployment/production?metricNames=cpu/usage,memory/usage&aggregations=avg' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

Response

{
  "listMeta": {
    "totalItems": 1
  },
  "items": [
    {
      "objectMeta": {
        "name": "api-server",
        "namespace": "production",
        "creationTimestamp": "2026-03-01T10:00:00Z"
      },
      "typeMeta": {
        "kind": "Deployment"
      },
      "pods": {
        "current": 3,
        "desired": 3
      },
      "metrics": {
        "cpu/usage": {
          "metricName": "cpu/usage",
          "dataPoints": [
            {"x": 1709632800000, "y": 150000000},
            {"x": 1709632860000, "y": 160000000},
            {"x": 1709632920000, "y": 155000000}
          ],
          "aggregation": "avg"
        },
        "memory/usage": {
          "metricName": "memory/usage",
          "dataPoints": [
            {"x": 1709632800000, "y": 314572800},
            {"x": 1709632860000, "y": 318767104},
            {"x": 1709632920000, "y": 316669952}
          ],
          "aggregation": "avg"
        }
      }
    }
  ]
}

Best Practices

Performance

Request only needed metrics: Don’t request all metrics if you only need CPU
Use aggregations: Let the API aggregate instead of doing it client-side
Batch requests: Request metrics for multiple resources in list endpoints
Cache results: Implement client-side caching for dashboards

Metric Selection

# Good: Request specific metrics
GET /api/v1/pod/default?metricNames=cpu/usage

# Better: Request multiple related metrics
GET /api/v1/pod/default?metricNames=cpu/usage,cpu/limit

# Avoid: Making separate requests for each metric

Troubleshooting

Check sidecar health: Verify metrics-scraper is running
Verify metrics-server: Ensure metrics-server is deployed in cluster
Check RBAC: Ensure service account has metrics read permissions
Review logs: Check Dashboard and sidecar logs for errors

Developer Guide

API Reference

​Overview

​Metrics Architecture

​Configuration

​Metrics Provider

​In-Cluster Configuration

​Metrics Integration

​Sidecar Integration

​Health Check

​Available Metrics

​CPU Metrics

​Memory Metrics

​Query Parameters

​Metric Names

​Aggregations

​Resource-Specific Metrics

​Pod Metrics

​Example Request

​Example Response

​Deployment Metrics

​Node Metrics

​Metric Data Structures

​Metric Object

​Sidecar REST API

​Base Path

​Pod Metrics

​Batch Pod Metrics

​Node Metrics

​Metric Client Interface

​Download Metrics

​Aggregate Metrics

​Resource Selectors

​Example

​Aggregation Modes

​Sum Aggregation

​Average Aggregation

​Min/Max Aggregation

​Batch Metric Downloads

​All-in-One Downloads

​Metric Promises

​Usage Example

​Prometheus Metrics

​Available Metrics

​Error Handling

​Metric Unavailable

​Sidecar Connection Error

​Example: Complete Metrics Query

​Request

​Response

​Best Practices

​Performance

​Metric Selection

​Troubleshooting

Build docs developers (and LLMs) love

Overview

Metrics Architecture

Configuration

Metrics Provider

In-Cluster Configuration

Metrics Integration

Sidecar Integration

Health Check

Available Metrics

CPU Metrics

Memory Metrics

Query Parameters

Metric Names

Aggregations

Resource-Specific Metrics

Pod Metrics

Example Request

Example Response

Deployment Metrics

Node Metrics

Metric Data Structures

Metric Object

Sidecar REST API

Base Path

Pod Metrics

Batch Pod Metrics

Node Metrics

Metric Client Interface

Download Metrics

Aggregate Metrics

Resource Selectors

Example

Aggregation Modes

Sum Aggregation

Average Aggregation

Min/Max Aggregation

Batch Metric Downloads

All-in-One Downloads

Metric Promises

Usage Example

Prometheus Metrics

Available Metrics

Error Handling

Metric Unavailable

Sidecar Connection Error

Example: Complete Metrics Query

Request

Response

Best Practices

Performance

Metric Selection

Troubleshooting