@skyhook-io/radar-app 1.13.5 → 1.14.0

package/src/components/resource/PrometheusChartsGrid.render.test.tsx

@@ -0,0 +1,99 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { renderToString } from 'react-dom/server'
+import { MemoryRouter } from 'react-router-dom'
+import { NavCustomizationProvider } from '../../context/NavCustomization'
+import type { WorkloadMetrics } from '../../api/workloadMetrics'
+
+let connected = false
+const ranges: string[] = []
+const charts: { seriesLabels?: string[]; referenceLines?: unknown[] }[] = []
+let workload: WorkloadMetrics
+
+vi.mock('../../api/client', async (importActual) => ({
+  ...(await importActual<typeof import('../../api/client')>()),
+  useAutoPromConnect: () => undefined,
+  usePrometheusStatus: () => ({ data: { connected, error: 'Backend query failed' } }),
+  usePrometheusConnect: () => ({ mutate: vi.fn(), isPending: false }),
+  usePrometheusResourceMetrics: (_kind: string, _ns: string, _name: string, _category: string, range: string) => {
+    ranges.push(range)
+    return { data: { unit: 'cores', result: { series: [{ labels: { pod: 'web-0' }, dataPoints: [{ timestamp: 100, value: 1 }, { timestamp: 160, value: 2 }] }] } } }
+  },
+}))
+vi.mock('../../api/workloadMetrics', () => ({ useWorkloadMetrics: () => ({ data: workload }) }))
+vi.mock('./RestartChart', () => ({ RestartEventLane: () => null }))
+vi.mock('./RightsizingStrip', () => ({ RightsizingStrip: () => null }))
+vi.mock('@skyhook-io/k8s-ui/components/charts', async (importActual) => ({
+  ...(await importActual<typeof import('@skyhook-io/k8s-ui/components/charts')>()),
+  AreaChart: (props: typeof charts[number]) => { charts.push(props); return <span>Chart</span> },
+}))
+
+const { PrometheusChartsGrid } = await import('./PrometheusChartsGrid')
+const resource = { spec: { template: { spec: { containers: [{ resources: { requests: { cpu: '100m' }, limits: { cpu: '200m' } } }] } } } }
+const render = (url = '/workloads/Deployment/demo/web?tab=metrics', embedded = false) => renderToString(
+  <MemoryRouter initialEntries={[url]}><NavCustomizationProvider value={embedded ? { embedded: true, rightExtras: null } : {}}>
+    <PrometheusChartsGrid kind="Deployment" namespace="demo" name="web" resource={resource} />
+  </NavCustomizationProvider></MemoryRouter>,
+)
+
+beforeEach(() => {
+  connected = false
+  ranges.length = 0
+  charts.length = 0
+  workload = { state: 'available', sources: [], pods: 1, podsTotal: 1, start: 100, end: 160, stepSeconds: 60, rateWindowSeconds: 300, history: {}, comparison: {}, panels: {} }
+})
+
+describe('Expanded metrics recovery and scope', () => {
+  it('offers standalone setup without losing the backend error or retry', () => {
+    const html = render()
+    expect(html).toContain('Backend query failed')
+    expect(html).toContain('Discover Prometheus')
+    expect(html).toContain('Configure metrics')
+    expect(html).toContain('workload-metrics.md#what-each-chart-needs')
+  })
+  it('uses operator guidance instead of standalone settings when embedded', () => {
+    const html = render(undefined, true)
+    expect(html).toContain('Ask your operator')
+    expect(html).not.toContain('Configure metrics')
+    expect(html).toContain('Discover Prometheus')
+  })
+  it.each([
+    ['/workloads/Deployment/demo/web?tab=metrics&metricsRange=3h', '3h'],
+    ['/applications?app=demo&workload=Deployment%2Fdemo%2Fweb&tab=metrics&metricsRange=6h', '6h'],
+    ['/applications?tab=metrics&metricsRange=invalid', '1h'],
+    ['/applications?tab=metrics', '1h'],
+  ])('reads and validates the URL range: %s', (url, expected) => {
+    connected = true
+    const html = render(url)
+    expect(html).toContain(`value="${expected}" selected=""`)
+    expect(ranges.length).toBeGreaterThan(0)
+    expect(ranges.every((range) => range === expected)).toBe(true)
+  })
+  it('leaves unverified charts accessible without template overlays or saturation', () => {
+    connected = true
+    const html = render()
+    expect(html).toContain('<details aria-label="Name-matched resource metrics">')
+    expect(html).toContain('Network and storage')
+    expect(html).not.toContain('% of limit')
+    expect(charts.length).toBeGreaterThan(0)
+    expect(charts.every((chart) => !chart.referenceLines?.length)).toBe(true)
+  })
+  it('labels unlabeled request totals without changing aggregate and quantile labels', () => {
+    connected = true
+    const series = [{ labels: {}, dataPoints: [{ timestamp: 160, value: 1 }] }]
+    workload.panels.requests = { state: 'available', unit: 'requests/s', series }
+    workload.panels.p50 = { state: 'available', unit: 'seconds', series }
+    workload.panels.p95 = { state: 'available', unit: 'seconds', series }
+    workload.panels.cpu = { state: 'available', unit: 'cores', series: [{ ...series[0], labels: { aggregation: 'Workload' } }, { ...series[0], labels: { aggregation: 'Maximum Pod' } }] }
+    render()
+    expect(charts.map((chart) => chart.seriesLabels)).toContainEqual(['Requests / sec'])
+    expect(charts.map((chart) => chart.seriesLabels)).toContainEqual(['p50', 'p95'])
+    expect(charts.map((chart) => chart.seriesLabels)).toContainEqual(['Workload', 'Maximum Pod'])
+  })
+  it('retains template references on verified current-Pod charts', () => {
+    connected = true
+    workload.history.cpu = { mode: 'current-pods' }
+    workload.panels.cpu = { state: 'available', unit: 'cores', series: [{ labels: { pod: 'web-0' }, dataPoints: [{ timestamp: 160, value: 0.1 }] }] }
+    render()
+    expect(charts.some((chart) => chart.referenceLines?.some((line) => (line as { label: string }).label === 'Template request 100m'))).toBe(true)
+  })
+})

package/src/components/resource/PrometheusChartsGrid.tsx

@@ -1,4 +1,5 @@
-import { useMemo, useState } from "react";
+import { useMemo } from "react";
+import { useSearchParams } from "react-router-dom";
 import { Loader2, Wifi, WifiOff } from "lucide-react";
 import {
   AreaChart,
@@ -30,6 +31,9 @@ import {
 } from "./PrometheusCharts";
 import { RestartEventLane } from "./RestartChart";
 import { Tooltip } from "../ui/Tooltip";
+import { WorkloadMetricsSection } from "./WorkloadMetricsSection";
+import { RightsizingStrip } from "./RightsizingStrip";
+import { useNavCustomization } from "../../context/NavCustomization";
 
 // Used when MetricsTabContent is in expanded (full-screen) mode. Drawer mode
 // uses the single-chart tabbed `PrometheusCharts` instead — drawer width
@@ -64,9 +68,12 @@ export function PrometheusChartsGrid({
   const connectMutation = usePrometheusConnect();
   const isConnected = status?.connected === true;
   const isSupported = SUPPORTED_KINDS.has(kind);
+  const isWorkload = ["Deployment", "StatefulSet", "DaemonSet"].includes(kind);
   const showRestartLane = isSupported && kind !== "Node";
 
-  const [timeRange, setTimeRange] = useState<PrometheusTimeRange>("1h");
+  const settingsAvailable = !useNavCustomization().embedded;
+  const [searchParams, setSearchParams] = useSearchParams();
+  const timeRange = TIME_RANGES.find((range) => range.value === searchParams.get("metricsRange"))?.value ?? "1h";
 
   const categories = kind === "Node" ? NODE_CATEGORIES : WORKLOAD_CATEGORIES;
 
@@ -94,6 +101,15 @@ export function PrometheusChartsGrid({
     );
   }
 
+  if (!isConnected && status?.discovering) {
+    return (
+      <div className="flex items-center justify-center py-12 text-theme-text-tertiary">
+        <Loader2 className="w-5 h-5 animate-spin mr-2" />
+        Discovering Prometheus…
+      </div>
+    );
+  }
+
   if (!isConnected) {
     return (
       <div className="flex flex-col items-center justify-center py-12 gap-4">
@@ -106,6 +122,7 @@ export function PrometheusChartsGrid({
             {status?.error ||
               "Connect to view historical CPU, memory, and network metrics"}
           </p>
+          <div className="flex flex-wrap items-center justify-center gap-3">
           <button
             onClick={() => connectMutation.mutate()}
             disabled={connectMutation.isPending}
@@ -118,6 +135,14 @@ export function PrometheusChartsGrid({
             )}
             Discover Prometheus
           </button>
+          {settingsAvailable && <button
+            type="button"
+            className="text-sm text-accent hover:underline"
+            onClick={() => window.dispatchEvent(new CustomEvent('radar:open-settings', { detail: { section: 'prometheus' } }))}
+          >Configure metrics</button>}
+          </div>
+          {!settingsAvailable && <p className="mt-3 text-xs text-theme-text-tertiary">Ask your operator to configure the metrics connection for this cluster.</p>}
+          {isWorkload && <a className="mt-3 inline-block text-xs text-accent hover:underline" href="https://github.com/skyhook-io/radar/blob/main/docs/workload-metrics.md#what-each-chart-needs" target="_blank" rel="noopener noreferrer">What each chart needs</a>}
         </div>
       </div>
     );
@@ -140,27 +165,42 @@ export function PrometheusChartsGrid({
   }
   const disk = findCategory("filesystem");
   const chartPanels = disk ? [...primaryCats, { def: disk }] : primaryCats;
+  const renderPanel = ({ def, refLines }: { def: CategoryDef; refLines?: ReferenceLine[] }) => (
+    <MetricsPanel key={def.key} category={def} kind={kind} namespace={namespace} name={name} timeRange={timeRange} referenceLines={refLines} />
+  );
 
-  return (
-    <div className="flex flex-col h-full overflow-auto">
-      <div className="flex shrink-0 justify-end px-4 pt-3">
-        <select
+  const rangeControl = <select
           aria-label="Metrics time range"
           value={timeRange}
-          onChange={(e) => setTimeRange(e.target.value as PrometheusTimeRange)}
-          className="rounded-md border border-theme-border bg-theme-elevated px-2 py-1 text-xs text-theme-text-secondary shadow-theme-sm focus:outline-none focus:ring-1 focus:ring-accent/50"
+          onChange={(e) => {
+            const next = new URLSearchParams(searchParams);
+            next.set("metricsRange", e.target.value);
+            setSearchParams(next, { replace: true });
+          }}
+          className="ml-auto rounded-md border border-theme-border bg-theme-elevated px-2 py-1 text-xs text-theme-text-secondary shadow-theme-sm focus:outline-none focus:ring-1 focus:ring-accent/50"
         >
           {TIME_RANGES.map((tr) => (
             <option key={tr.value} value={tr.value}>
               {tr.label}
             </option>
           ))}
-        </select>
-      </div>
+        </select>;
+
+  return (
+    <div className="flex flex-col min-w-0 w-full h-full overflow-auto">
+      {!isWorkload && <div className="flex shrink-0 items-center justify-between gap-3 px-4 pt-3">{rangeControl}</div>}
+
+      {isWorkload && (
+        <WorkloadMetricsSection key={`${kind}/${namespace}/${name}`} kind={kind} namespace={namespace} name={name} range={timeRange}
+          controls={rangeControl}
+          cpuReferenceLines={cpuRefLines} memoryReferenceLines={memRefLines}
+          nameMatchedCharts={{ cpu: cpu && renderPanel({ def: cpu }), memory: mem && renderPanel({ def: mem }) }}
+          restartLane={showRestartLane && <div className="mb-3"><RestartEventLane kind={kind} namespace={namespace} name={name} range={timeRange} /></div>} />
+      )}
 
       {/* Restart lane sits above the grid so its markers visually align with
           the time axis of the charts below. */}
-      {showRestartLane && (
+      {showRestartLane && !isWorkload && (
         <div className="px-4 pt-3">
           <RestartEventLane
             kind={kind}
@@ -171,28 +211,27 @@ export function PrometheusChartsGrid({
         </div>
       )}
 
-      <div className="grid grid-cols-1 md:grid-cols-2 gap-3 px-4 pt-4">
-        {chartPanels.map(({ def, refLines }) => (
-          <MetricsPanel
-            key={def.key}
-            category={def}
-            kind={kind}
-            namespace={namespace}
-            name={name}
-            timeRange={timeRange}
-            referenceLines={refLines}
-          />
-        ))}
+      <div className="metrics-layout min-w-0 px-4 pt-4">
+        {isWorkload && <h3 className="mb-2 text-sm font-semibold text-theme-text-primary">Network and storage</h3>}
+        {isWorkload && <details className="mb-2 text-xs text-theme-text-secondary">
+          <summary className="cursor-pointer">Pod-name matched · identity unverified</summary>
+          <p className="mt-2 max-w-2xl text-sm leading-relaxed">These charts match current Pod names, independently of the identity-checked charts above. Matching names in a shared backend may include another cluster.</p>
+        </details>}
+        <div className="metrics-chart-grid">
+          {chartPanels.filter(({ def }) => !isWorkload || (def.key !== "cpu" && def.key !== "memory")).map(renderPanel)}
+        </div>
       </div>
 
-      {/* Every chart here covers the same pods, so which pods those are is
-          stated once for the grid rather than repeated under each one. */}
       <PodCoverageNote
         kind={kind}
         namespace={namespace}
         name={name}
         timeRange={timeRange}
+        category={isWorkload ? "network_rx" : "cpu"}
       />
+      {["Deployment", "StatefulSet", "DaemonSet"].includes(kind) && (
+        <div className="px-4 pb-4"><RightsizingStrip kind={kind} namespace={namespace} name={name} /></div>
+      )}
     </div>
   );
 }
@@ -202,19 +241,19 @@ function PodCoverageNote({
   namespace,
   name,
   timeRange,
+  category,
 }: {
   kind: string;
   namespace: string;
   name: string;
   timeRange: PrometheusTimeRange;
+  category: PrometheusMetricCategory;
 }) {
-  // Any category answers this: the pod scope is per workload, not per metric.
-  // This is the same query key the CPU panel uses, so it is already cached.
   const { data } = usePrometheusResourceMetrics(
     kind,
     namespace,
     name,
-    "cpu",
+    category,
     timeRange,
     true,
   );
@@ -265,9 +304,9 @@ function MetricsPanel({
       : undefined;
 
   return (
-    <section className="rounded-lg border border-theme-border bg-theme-surface/30 p-3 flex flex-col min-h-[260px]">
-      <header className="flex items-center justify-between mb-2 gap-3">
-        <div className="flex items-center gap-2">
+    <section className="metrics-chart rounded-lg border border-theme-border bg-theme-surface/30 p-3 flex flex-col min-w-0">
+      <header className="flex flex-wrap items-center justify-between mb-2 gap-3">
+        <div className="flex flex-wrap items-center gap-2">
           <h3 className="text-xs font-medium text-theme-text-secondary uppercase tracking-wide">
             {category.label}
           </h3>
@@ -282,7 +321,7 @@ function MetricsPanel({
         )}
       </header>
 
-      <div className="flex-1 min-h-[200px]">
+      <div className="min-w-0">
         {isLoading ? (
           <PanelLoading />
         ) : error ? (
@@ -295,6 +334,7 @@ function MetricsPanel({
               fillColor={category.fillColor}
               unit={metrics!.unit}
               referenceLines={referenceLines}
+              layout="dashboard"
             />
             {series.length > 1 && (
               <div className="mt-1.5">
@@ -336,7 +376,7 @@ function SaturationChip({
 
 function PanelLoading() {
   return (
-    <div className="flex items-center justify-center h-full min-h-[160px] text-theme-text-tertiary text-xs">
+    <div className="flex items-center justify-center h-[240px] text-theme-text-tertiary text-xs">
       <Loader2 className="w-4 h-4 animate-spin mr-2" />
       Loading…
     </div>
@@ -346,7 +386,7 @@ function PanelLoading() {
 function PanelError({ message }: { message: string }) {
   return (
     <div
-      className={`flex flex-col items-center justify-center h-full min-h-[160px] ${SEVERITY_TEXT.warning} text-xs px-3 text-center`}
+      className={`flex flex-col items-center justify-center h-[240px] ${SEVERITY_TEXT.warning} text-xs px-3 text-center`}
     >
       Query failed
       <Tooltip content={message} wrapperClassName="!block w-full">
@@ -360,7 +400,7 @@ function PanelError({ message }: { message: string }) {
 
 function PanelNoData({ hint }: { hint?: string }) {
   return (
-    <div className="flex flex-col items-center justify-center h-full min-h-[160px] text-theme-text-tertiary text-xs px-3 text-center">
+    <div className="flex flex-col items-center justify-center h-[240px] text-theme-text-tertiary text-xs px-3 text-center">
       No data
       {hint && (
         <span className="text-theme-text-quaternary mt-1 max-w-xs">{hint}</span>

package/src/components/resource/RightsizingStrip.test.ts

@@ -107,3 +107,41 @@ describe('rightsizing presentation', () => {
     expect(RIGHTSIZING_DOCS_URL).toContain('/features/rightsizing')
   })
 })
+
+describe('live pod inventory', () => {
+  it('qualifies a memory row when the pod list could not be read', () => {
+    const explanation = getRightsizingExplanation(
+      row({ resource: 'memory', liveInventoryUnavailable: true }),
+    )
+    expect(explanation).toContain('could not read')
+    expect(explanation).toContain('out-of-memory restarts')
+  })
+
+  it('adds the caveat to a suppression reason instead of replacing it', () => {
+    const explanation = getRightsizingExplanation(
+      row({ resource: 'memory', recommendationReason: 'oom_evidence', liveInventoryUnavailable: true }),
+    )
+    expect(explanation).toContain('OOM evidence exists')
+    expect(explanation).toContain('could not read')
+  })
+
+  it('keeps the caveat on a staged reduction, where an unchecked pod matters most', () => {
+    const explanation = getRightsizingExplanation(
+      row({
+        resource: 'memory',
+        liveInventoryUnavailable: true,
+        reductionLimited: true,
+        calculatedRequest: '256Mi',
+        recommendedRequest: '384Mi',
+      }),
+    )
+    expect(explanation).toContain('conservative next step')
+    expect(explanation).toContain('could not read')
+  })
+
+  it('says nothing when the pods were read', () => {
+    expect(getRightsizingExplanation(row({ resource: 'memory' })) ?? '').not.toContain(
+      'could not read',
+    )
+  })
+})

package/src/components/resource/RightsizingStrip.tsx

@@ -328,16 +328,28 @@ export function getRightsizingExplanation(row: RightsizingRow): string | undefin
     recommended_request_exceeds_limit:
       'The evidence-based request would exceed the current limit; review the limit first.',
   }
+  // A denied pod read leaves currentPodOOM unknown rather than false, so it
+  // qualifies whatever else is said instead of replacing it — including a
+  // staged reduction, which is exactly where an unchecked pod matters most.
+  const inventoryNote =
+    row.liveInventoryUnavailable && row.resource === 'memory'
+      ? "Radar could not read this workload's pods, so it could not check them for out-of-memory restarts."
+      : undefined
+  const qualified = (base: string) => (inventoryNote ? `${base} ${inventoryNote}` : base)
   if (row.reductionLimited && row.calculatedRequest && row.recommendedRequest) {
     const burstNote = row.bursty && row.peak ? ` CPU P99 reached ${row.peak.formatted}.` : ''
-    return `Demand-based target: ${row.calculatedRequest}. Radar suggests ${row.recommendedRequest} as a conservative next step; observe another full window before reducing further.${burstNote}`
+    return qualified(
+      `Demand-based target: ${row.calculatedRequest}. Radar suggests ${row.recommendedRequest} as a conservative next step; observe another full window before reducing further.${burstNote}`,
+    )
   }
   const message = row.queryError
     ? `Partial result: ${row.queryError}.`
     : messages[row.recommendationReason ?? '']
   const throttleUnavailable = row.resource === 'cpu' && !row.throttleAvailable
-  if (!message && !throttleUnavailable) return undefined
-  return message ?? 'CPU throttling metrics are unavailable; no throttling conclusion was drawn.'
+  if (!message && !throttleUnavailable) return inventoryNote
+  return qualified(
+    message ?? 'CPU throttling metrics are unavailable; no throttling conclusion was drawn.',
+  )
 }
 
 function confidenceLabel(row: RightsizingRow) {

package/src/components/resource/WorkloadMetricsHelpDialog.test.tsx

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { WorkloadMetricsHelpContent } from './WorkloadMetricsHelpDialog'
+import type { WorkloadMetrics } from '../../api/workloadMetrics'
+
+const data = (attribution: Record<string, string>): WorkloadMetrics => ({
+  attribution, state: 'available', sources: [], history: {}, comparison: {}, panels: {},
+  pods: 2, podsTotal: 2, start: 100, end: 160, stepSeconds: 60, rateWindowSeconds: 300,
+})
+
+describe('Metrics help', () => {
+  it('groups only identical resource evidence, not HTTP observers or different methods', () => {
+    const html = renderToStaticMarkup(<WorkloadMetricsHelpContent pending={false} data={data({
+      cpu: 'UID match', memory: 'UID match', throttling: 'Label match', beyla: 'UID match', istio: 'No observations',
+    })} />)
+    expect(html).toContain('CPU / Memory')
+    expect(html).not.toContain('CPU / Memory / Throttling')
+    expect(html).toContain('Beyla · HTTP requests')
+    expect(html).toContain('Istio · HTTP requests')
+    expect(html.match(/UID match/g)).toHaveLength(2)
+    expect(html).toContain('Label match')
+    expect(html).toContain('No observations')
+  })
+  it('separates asserted scope and history from current-Pod matching', () => {
+    const html = renderToStaticMarkup(<WorkloadMetricsHelpContent pending={false} data={data({ scope: 'Operator assertion', history: 'Retained ownership' })} />)
+    expect(html).toContain('Operator-asserted scope')
+    expect(html).toContain('Historical ownership')
+    expect(html).not.toContain('<table')
+    expect(html).not.toContain('No current-Pod matching evidence')
+    expect(html).toContain('Each chart’s history label')
+  })
+  it('keeps operator overrides collapsed and explains their limits', () => {
+    const html = renderToStaticMarkup(<WorkloadMetricsHelpContent pending={false} data={data({})} />)
+    expect(html).toContain('Troubleshooting identity matching')
+    expect(html).toContain('--prometheus-single-cluster')
+    expect(html).toContain('they do not add missing metrics')
+    expect(html).toContain('Leave both unset for automatic matching')
+    expect(html).toContain('it does not scope rightsizing')
+    expect(html).toContain('Standalone CLI:')
+    expect(html).toContain('when starting Radar')
+    expect(html).toContain('traffic.prometheusSingleCluster')
+    expect(html).toContain('traffic.prometheusClusterLabels')
+    expect(html).toContain('In-cluster OSS or Radar Cloud:')
+    expect(html).toContain('not viewer preferences')
+    expect(html).toContain('Desktop does not expose these overrides yet')
+    expect(html).toContain('only alongside a verified scope override')
+    expect(html).not.toMatch(/<details[^>]*\bopen[=> ]/)
+  })
+  it('distinguishes loading, failed refresh and absent evidence', () => {
+    const pending = renderToStaticMarkup(<WorkloadMetricsHelpContent pending />)
+    expect(pending).toContain('Checking the selected metrics')
+    expect(pending).not.toContain('No current-Pod matching evidence')
+    const failed = renderToStaticMarkup(<WorkloadMetricsHelpContent pending={false} error={new Error('Query failed')} data={data({ cpu: 'Previous evidence' })} />)
+    expect(failed).toContain('Query failed')
+    expect(failed).toContain('Evidence below is from the previous response')
+    const empty = renderToStaticMarkup(<WorkloadMetricsHelpContent pending={false} />)
+    expect(empty).toContain('No current-Pod matching evidence is available yet')
+  })
+  it('does not deny historical evidence when there are no current-Pod matches', () => {
+    const html = renderToStaticMarkup(<WorkloadMetricsHelpContent pending={false} data={data({ history: 'Retained ownership is available' })} />)
+    expect(html).toContain('No current-Pod matching evidence')
+    expect(html).toContain('Retained ownership is available')
+  })
+  it.each(['detecting', 'error'] as const)('shows %s comparison independently of usable history', (state) => {
+    const response = data({ history: 'Historical ownership is available' })
+    response.reason = 'History follows retained workload ownership'
+    response.comparison = { cpu: { state, reason: 'Current identity status', unit: 'cores', series: [] } }
+    const html = renderToStaticMarkup(<WorkloadMetricsHelpContent pending={false} data={response} />)
+    expect(html).toContain('Current identity status')
+    expect(html).toContain('Historical ownership is available')
+    expect(html).not.toContain(response.reason)
+    expect(html).not.toContain('No current-Pod matching evidence')
+  })
+  it('describes a first-load failure without implying previous evidence', () => {
+    const html = renderToStaticMarkup(<WorkloadMetricsHelpContent pending={false} error={new Error('Query failed')} />)
+    expect(html).toContain('could not be loaded')
+    expect(html).not.toContain('refreshed')
+  })
+})

package/src/components/resource/WorkloadMetricsHelpDialog.tsx

@@ -0,0 +1,145 @@
+import { useLayoutEffect, useId, useRef } from 'react'
+import { createPortal } from 'react-dom'
+import { ExternalLink, X } from 'lucide-react'
+import type { WorkloadMetrics } from '../../api/workloadMetrics'
+import type { PrometheusTimeRange } from '../../api/client'
+
+interface Props {
+  kind: string
+  namespace: string
+  name: string
+  range: PrometheusTimeRange
+  data?: WorkloadMetrics
+  pending: boolean
+  error?: Error | null
+  onClose: () => void
+}
+
+export function WorkloadMetricsHelpDialog({ onClose, ...props }: Props) {
+  const dialog = useRef<HTMLDialogElement>(null)
+  const backdropPointerDown = useRef(false)
+  const titleId = useId()
+  useLayoutEffect(() => {
+    const element = dialog.current!
+    element.showModal()
+    return () => element.close()
+  }, [])
+
+  return createPortal(
+    <dialog
+      ref={dialog}
+      aria-labelledby={titleId}
+      className="dialog m-auto w-[800px] max-w-[calc(100vw-2rem)] max-h-[85dvh] p-0 text-theme-text-primary open:flex open:flex-col backdrop:bg-black/60 backdrop:backdrop-blur-sm"
+      onCancel={(event) => { event.preventDefault(); onClose() }}
+      onKeyDown={(event) => event.stopPropagation()}
+      onPointerDown={(event) => {
+        const bounds = event.currentTarget.getBoundingClientRect()
+        backdropPointerDown.current = event.target === event.currentTarget && (event.clientX < bounds.left || event.clientX > bounds.right || event.clientY < bounds.top || event.clientY > bounds.bottom)
+      }}
+      onClick={(event) => {
+        if (!backdropPointerDown.current || event.target !== event.currentTarget) return
+        backdropPointerDown.current = false
+        const bounds = event.currentTarget.getBoundingClientRect()
+        if (event.clientX < bounds.left || event.clientX > bounds.right || event.clientY < bounds.top || event.clientY > bounds.bottom) onClose()
+      }}
+    >
+      <header className="flex shrink-0 items-start justify-between gap-4 border-b border-theme-border px-6 py-4">
+        <div className="min-w-0">
+          <h2 id={titleId} className="text-lg font-semibold">Metrics sources &amp; coverage</h2>
+          <p className="mt-1 break-words text-sm text-theme-text-tertiary">{props.kind} · {props.namespace}/{props.name} · {props.range}</p>
+        </div>
+        <button type="button" autoFocus onClick={onClose} aria-label="Close metrics help" className="rounded-md p-1.5 text-theme-text-secondary hover:bg-theme-hover focus-visible:outline-accent">
+          <X aria-hidden="true" className="h-5 w-5" />
+        </button>
+      </header>
+      <div className="min-h-0 overflow-y-auto px-6 py-5">
+        <WorkloadMetricsHelpContent {...props} />
+      </div>
+      <footer className="shrink-0 border-t border-theme-border px-6 py-3">
+        <a className="inline-flex items-center gap-1.5 text-sm text-accent-text hover:underline" href="https://github.com/skyhook-io/radar/blob/main/docs/workload-metrics.md#what-each-chart-needs" target="_blank" rel="noopener noreferrer">
+          What each chart needs <ExternalLink aria-hidden="true" className="h-3.5 w-3.5" />
+        </a>
+      </footer>
+    </dialog>, document.body,
+  )
+}
+
+const evidenceLabels: Record<string, string> = {
+  cpu: 'CPU', memory: 'Memory', throttling: 'Throttling', beyla: 'Beyla · HTTP requests', istio: 'Istio · HTTP requests',
+}
+
+export function WorkloadMetricsHelpContent({ data, pending, error }: Pick<Props, 'data' | 'pending' | 'error'>) {
+  const evidence = Object.entries(data?.attribution ?? {}).filter(([key]) => key !== 'scope' && key !== 'history')
+  const resourceRows = new Map<string, string[]>()
+  for (const [key, reason] of evidence) {
+    if (!['cpu', 'memory', 'throttling'].includes(key)) continue
+    const labels = resourceRows.get(reason) ?? []
+    labels.push(evidenceLabels[key])
+    resourceRows.set(reason, labels)
+  }
+  const rows = [
+    ...Array.from(resourceRows, ([reason, labels]) => ({ label: labels.join(' / '), reason })),
+    ...evidence.filter(([key]) => !['cpu', 'memory', 'throttling'].includes(key)).map(([key, reason]) => ({ label: evidenceLabels[key] ?? key, reason })),
+  ]
+  const comparisonNotices = Array.from(new Set(Object.values(data?.comparison ?? {})
+    .filter((panel) => panel.state === 'detecting' || panel.state === 'error')
+    .map((panel) => panel.reason || (panel.state === 'detecting' ? 'Matching current-Pod metrics…' : 'Current-Pod comparison could not be loaded.'))))
+  const emptyReason = data && ['detecting', 'error', 'unavailable'].includes(data.state) ? data.reason : undefined
+  return <div className="space-y-6 text-sm leading-relaxed text-theme-text-secondary">
+    <section>
+      <h3 className="mb-1 font-semibold text-theme-text-primary">Source attribution details</h3>
+      <p className="text-theme-text-tertiary">Sources are checked independently. Identity matching does not mean every Pod has samples throughout the time window.</p>
+      {pending && <p role="status" className="mt-3">Checking the selected metrics…{data && ' Evidence below is from the previous response.'}</p>}
+      {error && <p role="status" className="mt-3 text-warning-text">Matching evidence could not be {data ? 'refreshed' : 'loaded'}: {error.message}{data && ' Evidence below is from the previous response.'}</p>}
+      {rows.length > 0 ? <table className="mt-3 w-full table-fixed text-left">
+        <thead className="text-xs text-theme-text-tertiary"><tr>
+          <th scope="col" className="w-1/3 border-b border-theme-border pb-2 pr-4 font-medium">Charts / source</th>
+          <th scope="col" className="border-b border-theme-border pb-2 font-medium">Current-Pod matching</th>
+        </tr></thead>
+        <tbody>{rows.map(({ label, reason }) => <tr key={label} className="border-b border-theme-border-subtle">
+          <th scope="row" className="py-3 pr-4 align-top font-medium text-theme-text-primary">{label}</th>
+          <td className="break-words py-3 align-top">{reason}</td>
+        </tr>)}</tbody>
+      </table> : !pending && !error && !data?.attribution?.scope && comparisonNotices.length === 0 && <p className="mt-3">{emptyReason || 'No current-Pod matching evidence is available yet.'}</p>}
+      {comparisonNotices.length > 0 && <div className="mt-3">
+        <h4 className="font-medium text-theme-text-primary">Current-Pod comparison</h4>
+        {comparisonNotices.map((reason) => <p role="status" key={reason}>{reason}</p>)}
+      </div>}
+      {data?.attribution?.scope && <div className="mt-3 border-l-2 border-theme-border pl-3">
+        <h4 className="font-medium text-theme-text-primary">Operator-asserted scope</h4>
+        <p>{data.attribution.scope}</p>
+      </div>}
+      {data?.attribution?.history && <div className="mt-3 border-l-2 border-theme-border pl-3">
+        <h4 className="font-medium text-theme-text-primary">Historical ownership</h4>
+        <p>{data.attribution.history}</p>
+        <p className="mt-1 text-theme-text-tertiary">Each chart’s history label reports whether that chart can use retained ownership.</p>
+      </div>}
+    </section>
+    <section className="border-t border-theme-border pt-5">
+      <h3 className="mb-3 font-semibold text-theme-text-primary">Reading the charts</h3>
+      <dl className="grid grid-cols-1 gap-x-6 gap-y-4 min-[600px]:grid-cols-2">
+        <div><dt className="font-medium text-theme-text-primary">Workload history vs current Pods</dt><dd className="mt-1">History follows retained ownership at each timestamp, including previous replicas. “Current Pods only” excludes previous replicas. Recreation under the same workload name is included in history.</dd></div>
+        <div><dt className="font-medium text-theme-text-primary">Missing is not zero</dt><dd className="mt-1">Unmatched Pods are excluded. Missing ownership or samples produces gaps. An idle workload and an uninstrumented one can both have no HTTP observations.</dd></div>
+        <div><dt className="font-medium text-theme-text-primary">HTTP observations</dt><dd className="mt-1">Ports and processes are combined, including health checks and admin traffic. HTTP 5xx is not a gRPC error rate and excludes failures without an HTTP response. Latency is measured at the selected observer, not end to end.</dd></div>
+        <div><dt className="font-medium text-theme-text-primary">Resource usage</dt><dd className="mt-1">CPU and memory include reporting containers and sidecars. Their historical charts show the workload total and maximum Pod; current-Pod charts show individual Pods. Throttling measures CFS periods, not CPU time lost.</dd></div>
+      </dl>
+    </section>
+    <details className="border-t border-theme-border pt-4">
+      <summary className="cursor-pointer font-medium text-theme-text-primary">Troubleshooting identity matching</summary>
+      <div className="mt-3 space-y-3">
+        <p>Check the affected chart’s warning first. Scope overrides address cluster identity; they do not add missing metrics, instrumentation or ownership history.</p>
+        <p>If automatic matching cannot establish identity, an operator can explicitly assert the backend’s scope:</p>
+        <dl className="space-y-3">
+          <div><dt className="font-medium">Backend dedicated to this cluster</dt><dd><code className="break-all font-mono text-xs">--prometheus-single-cluster</code><p className="mt-1">Helm: <code className="break-all font-mono text-xs">traffic.prometheusSingleCluster: true</code></p></dd></div>
+          <div><dt className="font-medium">Shared backend with a cluster label</dt><dd><code className="break-all font-mono text-xs">--prometheus-cluster-label cluster=your-cluster</code><p className="mt-1">Helm: set the backend’s actual label and value in <code className="break-all font-mono text-xs">traffic.prometheusClusterLabels</code>.</p></dd></div>
+        </dl>
+        <p>Leave both unset for automatic matching. An override replaces automatic matching for workload requests, resources, history and Pod comparison only; it does not scope rightsizing or other metrics features.</p>
+        <h4 className="font-medium text-theme-text-primary">Operator configuration</h4>
+        <p><strong className="font-medium">Standalone CLI:</strong> supply the flag when starting Radar. Overrides are not saved; after changing the cluster, backend or credentials, verify the new scope before restarting with a fresh override.</p>
+        <p><strong className="font-medium">In-cluster OSS or Radar Cloud:</strong> ask the installation’s operator to update its Helm values or GitOps configuration. These are shared backend settings, not viewer preferences.</p>
+        <p><strong className="font-medium">Desktop:</strong> automatic matching works without flags. Desktop does not expose these overrides yet; if one is required, use the standalone CLI with a verified scope.</p>
+        <p><strong className="font-medium">Multiple Beyla observation jobs:</strong> workload charts currently honor <code className="font-mono text-xs">--beyla-job-selector</code> only alongside a verified scope override. Use one matcher, such as <code className="font-mono text-xs">{'\'job="primary-beyla"\''}</code>; Helm uses <code className="font-mono text-xs">traffic.beylaJobSelector</code>. A custom job name alone normally needs no override.</p>
+      </div>
+    </details>
+  </div>
+}