diff --git a/packages/plugins/live-debugger/CONTRIBUTING.md b/packages/plugins/live-debugger/CONTRIBUTING.md
index ec8cdc040..892ad1387 100644
--- a/packages/plugins/live-debugger/CONTRIBUTING.md
+++ b/packages/plugins/live-debugger/CONTRIBUTING.md
@@ -62,6 +62,8 @@ The terminal output prints one row per browser and workload (`Tiny`, `Hot`). Bro
### What it measures
+In this benchmark, a **workload** is a small, repeatable piece of JavaScript chosen to exercise a particular runtime shape. It is not a complete application or a traffic profile. The harness repeats the code enough times to measure it reliably, then reports the result per instrumented function call. `Tiny` and `Hot` describe how the code is used, not the size of the application.
+
Each sample measures three variants:
- **baseline**: the uninstrumented workload.
@@ -77,6 +79,8 @@ There are two workloads because one number cannot describe every runtime shape:
Read them together. `Tiny` shows the minimum cost and the measurement floor. `Hot` shows the repeated-call hot-path cost. If `Hot` is higher than `Tiny` in nanoseconds per call, the gap is the extra cost from the hot-path shape in this benchmark. If `Tiny` is higher in percentage, that usually means the denominator is much smaller, not that `Tiny` has a larger absolute cost.
+Real applications contain a mixture of these shapes. An instrumented function called occasionally is closer to the concern measured by `Tiny`; a small helper called repeatedly from a rendering, event-processing, or data-processing loop is closer to `Hot`. An application itself is therefore not "Tiny" or "Hot." These rows are controlled reference points, not predictions of whole-application slowdown. The real impact also depends on how many instrumented functions run, how often they run, how much useful work surrounds each call, and how the browser optimizes that code. In practice, frequently executed paths deserve the most attention because even a small per-call cost can accumulate there.
+
### How to interpret the results
Start with three columns:
diff --git a/packages/tests/src/bench/liveDebuggerRuntime/reporter/benchReporter.test.ts b/packages/tests/src/bench/liveDebuggerRuntime/reporter/benchReporter.test.ts
index afc4882c1..5651b918e 100644
--- a/packages/tests/src/bench/liveDebuggerRuntime/reporter/benchReporter.test.ts
+++ b/packages/tests/src/bench/liveDebuggerRuntime/reporter/benchReporter.test.ts
@@ -2,7 +2,7 @@
// This product includes software developed at Datadog (https://www.datadoghq.com/).
// Copyright 2019-Present Datadog, Inc.
-import type { BenchResultRow } from '../types';
+import type { BenchFailure, BenchResultRow } from '../types';
import { buildAlignedTable, renderMarkdownComment } from './benchReporter';
@@ -81,40 +81,64 @@ describe('Live Debugger runtime benchmark reporter', () => {
test('should render GitHub comment summary and diagnostics', () => {
const row = createBenchResultRow();
- const comment = renderMarkdownComment([row], []);
- const summary = comment.split('')[0];
-
- expect(comment).toContain(
- 'SDK-loaded dormant-probe runtime overhead, measured against an uninstrumented bundle in the same browser session.',
- );
- expect(comment).toContain('| Browser | Workload | Quality | Per-call overhead upper |');
- expect(comment).toContain('Full diagnostics
');
- expect(comment).toContain('| chrome | Tiny | caution (outliers) | <= 0.05 ns |');
- expect(summary).not.toContain('<= 1.23%');
- expect(summary).not.toContain('| overhead upper |');
- expect(comment).toContain('1.235 ms');
- expect(comment).toContain('-0.04..0.03 ns');
- expect(comment).toContain('<= 1.23%');
- expect(comment).toContain('overhead upper');
- });
-
- test('should label the SDK build with publish date and a short S3 ETag', () => {
- const row = createBenchResultRow();
- // CloudFront returns a weak ETag (W/"...") when it compresses the response; the
- // label must reduce it to the bare content hash, not leak the W/ prefix or quotes.
const comment = renderMarkdownComment([row], [], '7.4.0', {
publishedAt: '2026-06-23T08:01:00.000Z',
etag: 'W/"0766e1c8f7af8eceb34ea84386a51f37"',
});
-
- // The build fingerprint disambiguates the (ambiguous) baked version, and the hash is
- // explicitly labeled "S3 ETag" so it is not mistaken for a git commit SHA.
- expect(comment).toContain(
+ const diagnosticsTable = buildAlignedTable([row]);
+ const expectedComment = [
+ '',
+ '## Live Debugger Runtime Benchmark',
+ '',
+ 'SDK-loaded dormant-probe runtime overhead, measured against an uninstrumented bundle in the same browser session.',
+ '',
+ '| Browser | Workload | Quality | Per-call overhead upper |',
+ '| --- | --- | --- | ---: |',
+ '| chrome | Tiny | caution (outliers) | <= 0.05 ns |',
+ '',
+ '[What do the Tiny and Hot workloads represent?](https://github.com/DataDog/build-plugins/blob/master/packages/plugins/live-debugger/CONTRIBUTING.md#what-it-measures)',
+ '',
'Browser Debugger SDK: `7.4.0` · built 2026-06-23 · S3 ETag `0766e1c8`',
- );
- // The ETag is shortened, with no weak-validator prefix, quotes, or full bare hash.
- expect(comment).not.toContain('0766e1c8f7af8eceb34ea84386a51f37');
- expect(comment).not.toContain('W/');
+ '',
+ '',
+ 'Full diagnostics
',
+ '',
+ '```',
+ diagnosticsTable,
+ '```',
+ '',
+ 'Raw samples are in the `live-debugger-runtime-bench-results` artifact.',
+ '',
+ ' ',
+ '',
+ ].join('\n');
+
+ expect(comment).toBe(expectedComment);
+ });
+
+ test('should surface the raw samples artifact after benchmark failures', () => {
+ const row = createBenchResultRow();
+ const failure: BenchFailure = {
+ projectName: 'safari',
+ title: 'Measures SDK-loaded dormant runtime overhead',
+ status: 'failed',
+ error: 'Browser closed',
+ };
+ const comment = renderMarkdownComment([row], [failure]);
+ const [details, afterDetails] = comment.split(' ');
+ const expectedAfterDetails = [
+ '',
+ '',
+ '### Benchmark failures',
+ '',
+ '- **safari** (failed): Browser closed',
+ '',
+ 'Raw samples are in the `live-debugger-runtime-bench-results` artifact.',
+ '',
+ ].join('\n');
+
+ expect(details).not.toContain('Raw samples are in');
+ expect(afterDetails).toBe(expectedAfterDetails);
});
test('should render the SDK version alone when no build fingerprint is available', () => {
diff --git a/packages/tests/src/bench/liveDebuggerRuntime/reporter/benchReporter.ts b/packages/tests/src/bench/liveDebuggerRuntime/reporter/benchReporter.ts
index 0cda84f88..df27af618 100644
--- a/packages/tests/src/bench/liveDebuggerRuntime/reporter/benchReporter.ts
+++ b/packages/tests/src/bench/liveDebuggerRuntime/reporter/benchReporter.ts
@@ -36,6 +36,9 @@ import {
const ATTACHMENT_NAME = 'live-debugger-runtime-bench';
const COMMENT_MARKER = '';
const COMMENT_FILE = path.resolve(os.tmpdir(), 'live-debugger-runtime-bench-comment.md');
+const WORKLOAD_DOCS_URL =
+ 'https://github.com/DataDog/build-plugins/blob/master/packages/plugins/live-debugger/CONTRIBUTING.md#what-it-measures';
+const RAW_SAMPLES_NOTE = 'Raw samples are in the `live-debugger-runtime-bench-results` artifact.';
const buildResultsFilePath = (generatedAt: string) => {
const safeTimestamp = generatedAt.replace(/[:.]/g, '-');
@@ -412,10 +415,6 @@ export const renderMarkdownComment = (
} else {
body +=
'SDK-loaded dormant-probe runtime overhead, measured against an uninstrumented bundle in the same browser session.\n\n';
- if (sdkVersion) {
- const sdkLabel = formatSdkLabel(sdkVersion, sdkBuild, (value) => `\`${value}\``);
- body += `Browser Debugger SDK: ${sdkLabel}\n\n`;
- }
body += '| Browser | Workload | Quality | Per-call overhead upper |\n';
body += '| --- | --- | --- | ---: |\n';
@@ -423,10 +422,18 @@ export const renderMarkdownComment = (
body += `| ${row.browserName} | ${row.workloadLabel} | ${formatQuality(row)} | ${formatCallOverhead(row)} |\n`;
}
+ body += `\n[What do the Tiny and Hot workloads represent?](${WORKLOAD_DOCS_URL})\n`;
+ if (sdkVersion) {
+ const sdkLabel = formatSdkLabel(sdkVersion, sdkBuild, (value) => `\`${value}\``);
+ body += `\nBrowser Debugger SDK: ${sdkLabel}\n`;
+ }
body += '\n\nFull diagnostics
\n\n';
body += '```\n';
body += `${buildAlignedTable(rows)}\n`;
body += '```\n';
+ if (failures.length === 0) {
+ body += `\n${RAW_SAMPLES_NOTE}\n`;
+ }
body += '\n \n';
}
@@ -435,10 +442,7 @@ export const renderMarkdownComment = (
for (const failure of failures) {
body += `- **${failure.projectName}** (${failure.status}): ${failure.error}\n`;
}
- }
-
- if (rows.length > 0 || failures.length > 0) {
- body += '\nRaw samples are in the `live-debugger-runtime-bench-results` artifact.\n';
+ body += `\n${RAW_SAMPLES_NOTE}\n`;
}
return body;