@skyhook-io/radar-app 1.13.4 → 1.14.0

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>
+}

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

@@ -0,0 +1,351 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { renderToString } from 'react-dom/server'
+import { MemoryRouter } from 'react-router-dom'
+import type { WorkloadMetrics, WorkloadMetricPanel } from '../../api/workloadMetrics'
+
+let result: { data?: WorkloadMetrics; isLoading?: boolean; isPlaceholderData?: boolean; error?: Error } = {}
+vi.mock('../../api/workloadMetrics', () => ({ useWorkloadMetrics: () => result }))
+const { WorkloadMetricsSection } = await import('./WorkloadMetricsSection')
+const panel = (value: number, unit = 'requests/s'): WorkloadMetricPanel => ({
+  state: 'available', unit,
+  series: [{ labels: { pod: 'checkout-0' }, dataPoints: [{ timestamp: 100, value }, { timestamp: 160, value }] }],
+})
+const render = () => renderToString(<MemoryRouter><WorkloadMetricsSection kind="Deployment" namespace="shop" name="checkout" range="1h" /></MemoryRouter>)
+
+beforeEach(() => {
+  result = { data: {
+    state: 'available', source: 'beyla',
+    sources: [{ id: 'beyla', label: 'Beyla', state: 'available' }],
+    pods: 2, podsTotal: 2, start: 100, end: 160, stepSeconds: 60, rateWindowSeconds: 300,
+    history: { cpu: { mode: 'current-pods', reason: 'Missing retained ownership.' }, requests: { mode: 'current-pods' } },
+    comparison: { cpu: panel(0, 'cores') },
+    panels: { requests: panel(0), observedPods: panel(1, 'pods'), cpu: panel(0, 'cores') },
+  } }
+})
+
+describe('Workload metrics interpretation', () => {
+  it('shows matching evidence instead of claiming no observations when no observer is usable', () => {
+    result.data!.source = undefined
+    result.data!.sources = [{ id: 'beyla', label: 'Beyla', state: 'unavailable' }]
+    result.data!.attribution = { beyla: 'Metrics exist, but their cluster identity could not be established automatically.' }
+    result.data!.panels.requests = { state: 'unavailable', unit: 'requests/s', series: [], reason: 'Generic prerequisites' }
+    const html = render()
+    expect(html).toContain('No usable HTTP metrics in this window')
+    expect(html).toContain('Metrics exist, but their cluster identity')
+    expect(html).not.toContain('Generic prerequisites')
+    expect(html).not.toContain('No HTTP observations')
+  })
+  it('preserves a selected observer’s query reason rather than replacing it with matching evidence', () => {
+    result.data!.attribution = { beyla: 'Matched to current Pod UIDs' }
+    result.data!.panels.requests = { state: 'unavailable', unit: 'requests/s', series: [], reason: 'No samples from the selected observer' }
+    const html = render()
+    expect(html).toContain('No samples from the selected observer')
+    expect(html).not.toContain('Matched to current Pod UIDs')
+  })
+  it('separates historical aggregates from bounded current comparison', () => {
+    result.data!.podsTotal = 128
+    result.data!.pods = 100
+    result.data!.history = { cpu: { mode: 'workload-history' }, requests: { mode: 'workload-history' } }
+    result.data!.panels.cpu = { ...panel(128, 'cores'), series: [
+      { labels: { aggregation: 'Workload' }, dataPoints: [{ timestamp: 160, value: 128 }] },
+      { labels: { aggregation: 'Maximum Pod' }, dataPoints: [{ timestamp: 160, value: 1 }] },
+    ] }
+    const html = render().replaceAll('<!-- -->', '')
+    expect(html).toContain('CPU usage · workload')
+    expect(html).toContain('Maximum Pod')
+    expect(html).toContain('1 Pods reporting')
+    expect(html).not.toContain('of 128 current Pods reporting')
+    expect(html).toContain('checkout-0')
+    expect(html).toContain('Comparing 100 of 128 current Pods')
+    expect(html).toContain('when ownership disappears after Pod deletion')
+  })
+  it('names the current-only fallback rather than implying full history', () => {
+    const html = render()
+    expect(html).toContain('Current Pods only')
+    expect(html).toContain('Missing retained ownership')
+  })
+  it('keeps name-matched fallback charts separate from identity-checked metrics', () => {
+    result.data!.panels.cpu = { state: 'error', unit: 'cores', reason: 'History lookup failed', series: [] }
+    result.data!.panels.memory = panel(100, 'bytes')
+    const html = renderToString(<MemoryRouter><WorkloadMetricsSection kind="Deployment" namespace="shop" name="checkout" range="1h" nameMatchedCharts={{ cpu: <span>Existing CPU chart</span>, memory: <span>Existing memory chart</span> }} /></MemoryRouter>)
+    expect(html.replaceAll('<!-- -->', '')).toContain('Basic CPU · identity unverified')
+    expect(html).toContain('<details aria-label="Name-matched resource metrics">')
+    expect(html).toContain('matching names in a shared backend may include another cluster')
+    expect(html).toContain('Existing CPU chart')
+    expect(html).toContain('History lookup failed')
+    expect(html).not.toContain('Existing memory chart')
+  })
+  it('does not flash name-matched charts during the initial request', () => {
+    result = { isLoading: true }
+    const html = renderToString(<MemoryRouter><WorkloadMetricsSection kind="Deployment" namespace="shop" name="checkout" range="1h" nameMatchedCharts={{ cpu: <span>Existing CPU chart</span> }} /></MemoryRouter>)
+    expect(html).not.toContain('Existing CPU chart')
+    expect(html).toContain('Checking request metrics')
+  })
+  it('shows only supplied template values and qualifies actual Pod differences', () => {
+    const html = renderToString(<MemoryRouter><WorkloadMetricsSection kind="Deployment" namespace="shop" name="checkout" range="1h" cpuReferenceLines={[{ value: 0.1, label: 'request 100m', kind: 'request' }]} memoryReferenceLines={[]} /></MemoryRouter>).replaceAll('<!-- -->', '')
+    expect(html).toContain('Template per Pod · actual Pods may differ')
+    expect(html).toContain('Template request 100m')
+    expect(html).toContain('Actual Pods can differ after injection or rollout.')
+    expect(html).not.toContain(' · Memory:')
+    expect(html).not.toContain('unlimited')
+    expect(render()).not.toContain('Template per Pod')
+  })
+  it.each([true, false])('keeps absent HTTP compact without narrating resource availability: %s', (usable) => {
+    result.data!.panels.requests = { state: 'unavailable', unit: 'requests/s', series: [], reason: 'No observations' }
+    result.data!.panels.cpu = usable ? panel(0, 'cores') : { state: 'error', unit: 'cores', series: [], reason: 'Query failed' }
+    const html = render()
+    expect(html).toContain('No usable HTTP metrics in this window')
+    expect(html).not.toContain('Resource charts below remain available')
+    expect(html).not.toContain('--beyla-job-selector')
+    if (!usable) expect(html).not.toContain('CPU usage · per Pod')
+  })
+  it('does not call pending attribution a lack of HTTP traffic', () => {
+    result.data!.panels.requests = { state: 'detecting', unit: 'requests/s', series: [], reason: 'Matching identity' }
+    const html = render()
+    expect(html).toContain('Checking request metrics…')
+    expect(html).toContain('Matching identity')
+    expect(html).not.toContain('No usable HTTP metrics')
+  })
+  it('keeps empty resource titles neutral even with an all-null series', () => {
+    result.data!.panels.cpu!.series[0].dataPoints = [{ timestamp: 160, value: null }]
+    const html = render()
+    expect(html).toContain('CPU usage')
+    expect(html).not.toContain('CPU usage · per Pod')
+  })
+  it('discloses combined request ports and reporting sidecars', () => {
+    const html = render()
+    expect(html).toContain('Ports combined · includes health checks and admin traffic.')
+    expect(html).toContain('Resource totals include reporting containers and sidecars.')
+  })
+  it('describes throttling scope independently of a failed CPU history query', () => {
+    result.data!.history.cpu = { mode: 'unavailable' }
+    result.data!.history.throttling = { mode: 'workload-history' }
+    result.data!.panels.throttling = panel(5, 'percent')
+    const html = render().replaceAll('<!-- -->', '')
+    expect(html).toContain('Throttling is weighted by total periods')
+    expect(html).not.toContain('Examines 2 of 2 current Pods')
+  })
+  it('does not describe aggregate series in current-Pod help', () => {
+    result.data!.history.throttling = { mode: 'current-pods' }
+    result.data!.panels.throttling = panel(5, 'percent')
+    const html = render()
+    expect(html).not.toContain('Workload is the total across reporting Pods')
+    expect(html).not.toContain('Throttling is weighted by total periods')
+  })
+  it('explains a historical memory aggregate without implying historical throttling', () => {
+    result.data!.history.memory = { mode: 'workload-history' }
+    result.data!.panels.memory = panel(100, 'bytes')
+    result.data!.history.throttling = { mode: 'current-pods' }
+    result.data!.panels.throttling = panel(5, 'percent')
+    const html = render()
+    expect(html).toContain('In workload-history CPU and memory charts, Workload is the total')
+    expect(html).not.toContain('Throttling is weighted by total periods')
+  })
+  it('retains resource charts while loading another request observer', () => {
+    result.isPlaceholderData = true
+    const html = render()
+    expect(html).toContain('Loading selected request source')
+    expect(html).toContain('CPU usage · per Pod')
+    expect(html).toContain('Compare current Pods')
+    expect(html).not.toContain('1 of 2 current Pods reporting')
+  })
+  it('labels operator scope and discarded assertions visibly', () => {
+    result.data!.attribution = { scope: 'Operator-asserted cluster scope' }
+    result.data!.scopeNotice = 'Scope assertion discarded after reconnect'
+    const html = render()
+    expect(html).toContain('operator-asserted scope')
+    expect(html).toContain('Scope assertion discarded after reconnect')
+    expect(html).not.toContain('Automatic metrics attribution')
+  })
+  it('explains withheld populations instead of suggesting instrumentation is absent', () => {
+    result.data!.panels.requests = {state:'partial',unit:'requests/s',series:[],reason:'Multiple observation populations'}
+    const html = render()
+    expect(html).toContain('Request metrics withheld')
+    expect(html).not.toContain('No request observations')
+    expect(html).not.toContain('--beyla-job-selector')
+  })
+  it.each(['detecting', 'unavailable', 'error'] as const)('does not substitute unattributed resource charts while metrics are %s', (state) => {
+    result.data!.state = state
+    result.data!.panels = {}
+    const html = render()
+    expect(html).not.toContain('CPU usage · per Pod')
+    expect(html).not.toContain('Memory working set · per Pod')
+  })
+  it('groups CPU and memory with throttling before the full-width Pod comparison', () => {
+    result.data!.panels.throttling = panel(5, 'percent')
+    const html = render()
+    expect(html.indexOf('CPU usage · per Pod')).toBeLessThan(html.indexOf('CPU throttled periods'))
+    expect(html.indexOf('CPU throttled periods')).toBeLessThan(html.indexOf('Compare current Pods'))
+    expect(html).toContain('metrics-chart-wide')
+    expect(html).not.toContain('lg:grid-cols-3')
+  })
+  it('distinguishes reporting Pods from selected Pods and preserves measured zero', () => {
+    const html = render()
+    expect(html).toContain('1 of 2 current Pods reporting')
+    expect(html).toContain('tabular-nums text-theme-text-primary">0</span>')
+    expect(html).toContain('previous replicas are not reconstructed')
+    expect(html).toContain('/resources/pods?resource=shop%2Fcheckout-0')
+    expect(html).toContain('checkout-0')
+  })
+  it('does not substitute selected count when coverage is missing', () => {
+    delete result.data!.panels.observedPods
+    expect(render()).toContain('Reporting Pod count unavailable')
+  })
+  it('keeps operator overrides out of the chart surface', () => {
+    result.data!.attribution = { cpu: 'Metrics exist, but their cluster identity could not be established automatically.' }
+    const html = render()
+    expect(html).toContain('aria-haspopup="dialog"')
+    expect(html).not.toContain('--prometheus-single-cluster')
+    expect(html).toContain('Workload resource pressure')
+    expect(html).not.toContain('operator setup required')
+  })
+  it('shows detecting without claiming missing data or mandatory setup', () => {
+    result.data!.state = 'detecting'
+    result.data!.reason = 'Matching metrics to current Pods…'
+    result.data!.panels = {}
+    const html = render()
+    expect(html).toContain('Matching metrics to current Pods')
+    expect(html).not.toContain('No request observations')
+    expect(html).not.toContain('--prometheus-single-cluster')
+  })
+  it('discloses partial pressure coverage', () => {
+    result.data!.panels.cpu = { ...panel(1, 'cores'), state: 'partial', reason: 'Attributed to 1 of 2 current Pods; other Pods are excluded.' }
+    expect(render()).toContain('Attributed to 1 of 2 current Pods')
+  })
+  it('retains response-level population limitations outside help', () => {
+    result.data!.state = 'partial'
+    result.data!.reason = 'Current pod population was capped; values cover only the included pods.'
+    expect(render()).toContain('Current pod population was capped; values cover only the included pods.')
+  })
+  it('does not show setup instructions for a workload with no Pods', () => {
+    result.data!.state = 'unavailable'
+    result.data!.reason = 'No current Pods.'
+    expect(render()).not.toContain('operator setup required')
+  })
+  it('shows query failure rather than fabricating missing metrics', () => {
+    result = { error: new Error('Forbidden') }
+    expect(render().replaceAll('<!-- -->', '')).toContain('Workload metrics could not be loaded: Forbidden')
+  })
+  it('keeps observers explicitly separate when both are available', () => {
+    result.data!.sources.push({ id: 'istio', label: 'Istio', state: 'available' })
+    expect(render()).toContain('Request metrics source')
+    expect(render()).toContain('value="beyla" selected=""')
+  })
+  it('does not suggest a job matcher for a failed request query', () => {
+    result.data!.panels.requests = { state: 'error', unit: 'requests/s', series: [], reason: 'Query failed' }
+    const html = render()
+    expect(html).toContain('Request metrics query failed')
+    expect(html).not.toContain('--beyla-job-selector')
+  })
+  it('describes Istio at the selected destination-sidecar observer', () => {
+    result.data!.source = 'istio'
+    result.data!.sources = [{ id: 'istio', label: 'Istio · destination sidecars', state: 'available' }]
+    const html = render().replaceAll('<!-- -->', '')
+    expect(html.match(/Istio · destination sidecars/g)).toHaveLength(1)
+    expect(html).toContain('5-minute rates')
+    expect(html).not.toContain('HTTP server ·')
+  })
+  it('does not describe history for an empty Requests section', () => {
+    result.data!.panels.requests = { state: 'unavailable', unit: 'requests/s', series: [] }
+    result.data!.history.requests = { mode: 'workload-history', reason: 'Request-only history marker' }
+    const html = render()
+    expect(html).not.toContain('Request-only history marker')
+    expect(html).toContain('No usable HTTP metrics in this window')
+  })
+  it('keeps successful attribution evidence and definitions collapsed', () => {
+    result.data!.attribution = { cpu: 'Matched CPU identity' }
+    const html = render()
+    expect(html).toContain('About these metrics')
+    expect(html).not.toContain('Matched CPU identity')
+    expect(html).toContain('Resource totals include reporting containers and sidecars.')
+    expect(html).not.toMatch(/<details[^>]*\bopen[=> ]/)
+  })
+  it('deduplicates stale RED notices without losing individual reasons', () => {
+    for (const key of ['requests', 'errors', 'p50', 'p95'] as const) {
+      result.data!.panels[key] = { ...panel(1), state: 'stale', reason: `${key} history only` }
+    }
+    const html = render()
+    expect(html.match(/no recent samples/g)).toHaveLength(1)
+    for (const key of ['requests', 'errors', 'p50', 'p95']) expect(html).toContain(`${key} history only`)
+  })
+  it('shares identical partial request coverage while keeping the warning visible', () => {
+    for (const key of ['requests', 'errors', 'p50', 'p95'] as const) {
+      result.data!.panels[key] = { ...panel(1), state: 'partial', reason: 'Only one reporting Pod was identified.' }
+    }
+    const html = render().replaceAll('<!-- -->', '')
+    expect(html.match(/Only one reporting Pod was identified/g)).toHaveLength(1)
+    expect(html).toContain('Requests, HTTP 5xx and latency: Only one reporting Pod was identified.')
+  })
+  it.each([true, false])('shares partial resource coverage only with matching scopes: %s', (sameScope) => {
+    for (const key of ['cpu', 'memory', 'throttling'] as const) {
+      result.data!.history[key] = { mode: 'current-pods' }
+      result.data!.panels[key] = { ...panel(1), state: 'partial', reason: 'Attributed to 1 of 2 Pods.' }
+    }
+    if (!sameScope) result.data!.history.memory = { mode: 'workload-history' }
+    expect(render().match(/Attributed to 1 of 2 Pods/g)).toHaveLength(sameScope ? 1 : 3)
+  })
+  it('does not hide a withheld chart behind a shared partial warning', () => {
+    for (const key of ['requests', 'errors', 'p50', 'p95'] as const) {
+      result.data!.panels[key] = { ...panel(1), state: 'partial', reason: 'Incomplete observation population.' }
+    }
+    result.data!.panels.p95!.series = []
+    result.data!.panels.p50!.series = []
+    const html = render()
+    expect(html).not.toContain('Requests, HTTP 5xx and latency:')
+    expect(html.match(/Incomplete observation population/g)).toHaveLength(3)
+  })
+  it('keeps stale samples withheld by coverage checks local to their chart', () => {
+    for (const key of ['requests', 'errors', 'p50', 'p95'] as const) {
+      result.data!.panels[key] = { ...panel(1), state: 'stale', reason: 'Historical samples only' }
+    }
+    result.data!.panels.errors!.series[0].dataPoints = [{ timestamp: 100, value: null }]
+    result.data!.panels.errors!.reason = 'Historical samples only. HTTP status coverage is incomplete.'
+    const html = render()
+    expect(html).not.toContain('Requests, HTTP 5xx and latency:')
+    expect(html).toContain('HTTP status coverage is incomplete')
+    expect(html).toMatch(/<p role="status"[^>]*>Historical samples only\. HTTP status coverage is incomplete\.<\/p>/)
+  })
+  it('keeps stale and failed quantiles local when RED states differ', () => {
+    result.data!.panels.p95 = { ...panel(1, 'seconds'), state: 'stale', reason: 'Old latency' }
+    result.data!.panels.p50 = { state: 'error', unit: 'seconds', series: [], reason: 'Median query failed' }
+    const html = render()
+    expect(html).toContain('Historical samples only')
+    expect(html).toContain('Median query failed')
+    expect(html).not.toContain('Requests, HTTP 5xx and latency:')
+  })
+  it('shows an identical empty-quantile explanation once', () => {
+    result.data!.panels.p50 = { state: 'unavailable', unit: 'seconds', series: [], reason: 'No histogram samples' }
+    result.data!.panels.p95 = { state: 'unavailable', unit: 'seconds', series: [], reason: 'No histogram samples' }
+    expect(render().match(/No histogram samples/g)).toHaveLength(1)
+  })
+  it('does not repeat a chart error in its history details', () => {
+    result.data!.history.cpu = { mode: 'unavailable', reason: 'CPU history query failed' }
+    result.data!.panels.cpu = { state: 'error', unit: 'cores', series: [], reason: 'CPU history query failed' }
+    expect(render().match(/CPU history query failed/g)).toHaveLength(1)
+  })
+  it('shows comparison matching once, not as missing Pod samples', () => {
+    result.data!.comparison = {
+      cpu: { state: 'detecting', unit: 'cores', series: [], reason: 'Matching metrics' },
+      memory: { state: 'detecting', unit: 'bytes', series: [], reason: 'Matching metrics' },
+    }
+    const html = render().replaceAll('<!-- -->', '')
+    expect(html.match(/Matching CPU \/ Memory metrics to current Pods/g)).toHaveLength(1)
+    expect(html).not.toContain('No Pod samples available')
+  })
+  it('deduplicates identical comparison failures and retains affected metrics', () => {
+    result.data!.comparison = {
+      cpu: { state: 'error', unit: 'cores', series: [], reason: 'Comparison query failed' },
+      memory: { state: 'error', unit: 'bytes', series: [], reason: 'Comparison query failed' },
+    }
+    const html = render().replaceAll('<!-- -->', '')
+    expect(html.match(/Comparison query failed/g)).toHaveLength(1)
+    expect(html).toContain('CPU / Memory: Comparison query failed')
+    expect(html).not.toContain('No Pod samples available')
+  })
+  it('does not explain an empty resource chart in terms of HTTP traffic', () => {
+    result.data!.panels.cpu = { state: 'unavailable', unit: 'cores', series: [] }
+    const html = render()
+    expect(html).toContain('No usable samples in this window')
+    expect(html).not.toContain('Idle traffic has no defined error percentage or latency')
+  })
+})