Metrics API

The metrics backend exposes a JSON HTTP API consumed by the UI extension via ArgoCD’s proxy at /extensions/metrics/.

All requests receive ArgoCD identity headers (Argocd-Username, Argocd-User-Id, Argocd-User-Groups, Argocd-Target-Cluster-URL).

Authorization

Every data endpoint requires the Argocd-Application-Name header (namespace:name format, set automatically by ArgoCD’s proxy). The backend returns 403 if the header is missing or if the requested namespace is not managed by that Application (its destination namespace plus namespaces in status.resources). The backend needs get on applications.argoproj.io for this lookup; the Helm chart grants it by default.

Config-driven dashboard endpoints

These are the primary endpoints used by the config-driven dashboard system.

Get dashboard config

GET /api/v1/dashboards?application={name}&groupKind={kind}

Returns the dashboard layout (tabs, rows, graphs metadata) for the UI to render.

Parameters:

Response:

{
  "groupKind": "deployment",
  "tabs": ["Resource Usage", "Container Breakdown"],
  "intervals": ["1h", "6h", "24h", "7d"],
  "rows": [
    {
      "name": "cpu-memory",
      "title": "CPU & Memory",
      "tab": "Resource Usage",
      "graphs": [
        {
          "name": "cpu-by-pod",
          "title": "CPU Usage by Pod",
          "graphType": "line",
          "metricName": "pod",
          "queryExpression": "sum by (pod) (rate(...))",
          "yAxisUnit": "millicores"
        }
      ]
    }
  ]
}

Get graph data

GET /api/v1/graph?application={name}&groupKind={kind}&row={row}&graph={graph}&namespace={ns}&name={name}&duration={dur}

Executes a PromQL template for a specific graph and returns time series data.

Parameters:

PromQL templates support the variables {{.namespace}}, {{.name}}, and {{.podFilter}} (built from pods or name). Values are escaped before substitution to prevent PromQL injection.

Response:

{
  "series": [
    {
      "label": "guestbook-ui-abc123",
      "values": [
        { "time": "2025-03-16T10:00:00Z", "value": 12.5 },
        { "time": "2025-03-16T10:00:30Z", "value": null }
      ]
    }
  ]
}

Values are converted based on yAxisUnit: bytes to MiB, bytes/s to KB/s, millicores and count passed through. null values indicate gaps in the data.

Legacy endpoints

These endpoints are still used by the summary cards, pod breakdown table, and per-pod charts.

Resource metrics

GET /api/v1/resource-metrics?namespace={ns}&name={name}&kind={kind}&range={range}

Returns instant summary or time series metrics for a specific workload or pod.

Parameters:

Instant response (no range):

[
  { "name": "CPU", "value": "12.5", "unit": "millicores" },
  { "name": "Memory", "value": "45.2", "unit": "MiB" },
  { "name": "Network RX", "value": "1.2", "unit": "KB/s" },
  { "name": "Network TX", "value": "0.8", "unit": "KB/s" },
  { "name": "Restarts", "value": "0", "unit": "" }
]

Range response (with range):

[
  {
    "name": "CPU",
    "unit": "millicores",
    "series": [
      { "time": "2025-03-16T10:00:00Z", "value": 12.5 }
    ]
  }
]

App metrics

GET /api/v1/app-metrics?namespace={ns}&range={range}

Returns namespace-wide aggregate metrics (all pods in a namespace).

Parameters:

Response:

{
  "summary": [
    { "name": "CPU", "value": "45.2", "unit": "millicores" },
    { "name": "Memory", "value": "128.5", "unit": "MiB" }
  ],
  "timeSeries": [
    {
      "name": "CPU",
      "unit": "millicores",
      "series": [{ "time": "...", "value": 45.2 }]
    }
  ]
}

Pod breakdown

GET /api/v1/pod-breakdown?namespace={ns}&name={name}&kind={kind}&pods={pods}

Returns per-pod instant metrics for the pod details table.

Parameters:

Response:

[
  {
    "pod": "guestbook-ui-abc123",
    "cpu": "12.5 m",
    "memory": "45.2 MiB",
    "netRx": "1.2 KB/s",
    "netTx": "0.8 KB/s",
    "restarts": "0"
  }
]

Per-pod time series

GET /api/v1/per-pod-series?namespace={ns}&name={name}&kind={kind}&range={range}&pods={pods}

Returns per-pod time series for multi-line charts (CPU, Memory, Network RX, Network TX).

Parameters:

Response:

[
  {
    "metric": "CPU Usage",
    "unit": "millicores",
    "timestamps": ["2025-03-16T10:00:00Z", "..."],
    "pods": [
      {
        "pod": "guestbook-ui-abc123",
        "values": [12.5, null, 13.0]
      }
    ]
  }
]

Health check

GET /healthz

Returns 200 OK. No body.

Error responses

All endpoints return errors as JSON:

{ "error": "description of what went wrong" }

HTTP status codes: 400 for missing parameters, 403 when namespace authorization fails, 404 for config lookups that fail, 500 for internal errors.