refactor: update HTTP benchmark result structure and improve documentation clarity

Author: jaydrogers

app/Actions/Results/HttpBenchmarkResults.php

@@ -282,7 +282,7 @@ public static function selfGenerator(): array
     }
 
     /**
-     * @return array{mode: string|null, target: string|null, duration_seconds: int|null, connections: int|null, io_ms: int|null, routes: array<string, array<string, mixed>>}|null
+     * @return array{mode: string|null, target: string|null, io_ms: int|null, workers: int|null, levels: array<string, array<int, int>>, routes: array<string, array<string, mixed>>}|null
      */
     public function execute(): ?array
     {

app/Support/Http/LoadCurve.php

@@ -8,7 +8,7 @@
  * numbers untrustworthy.
  *
  * Nothing here drives the load. The levels are chosen before the run starts
- * (LoadProfile::levels) and run as a plain list, so this only has to describe
+ * (LoadProfile::levelsFor) and run as a plain list, so this only has to describe
  * what came back — which is why the same class can read a self-test and an
  * external run without either of them knowing it exists.
  */

app/Support/Http/LoadStep.php

@@ -9,7 +9,7 @@
  * rather than per route. The external generator posts its result back to that
  * index, and the server refuses anything that is not the step it is currently
  * waiting for — which is what makes a retried upload cost one round trip
- * instead of corrupting the ramp.
+ * instead of corrupting the sweep.
  */
 class LoadStep
 {
@@ -37,7 +37,7 @@ public function __construct(
      * OPcache warm; its numbers describe a cold server and are never parsed.
      * Saying so here keeps the drivers from having to know which phases mean
      * something — the generator sends `{}` for an uncaptured step, and the
-     * state machine advances on the acknowledgement alone.
+     * driver advances on the acknowledgement alone.
      */
     public function isMeasured(): bool
     {
@@ -47,9 +47,8 @@ public function isMeasured(): bool
     /**
      * Whether the raw oha JSON for this step is kept on disk.
      *
-     * Ramp rungs are reduced to a curve point and discarded: thirty-odd files
-     * of three-second throwaway data are not worth keeping, and nothing may
-     * cite a rung as a measurement. The two published passes are kept whole.
+     * Every measured window is kept: a sweep level backs one point on the
+     * published curve, and the response-time pass backs the percentiles.
      */
     public function isPublished(): bool
     {

app/Support/Http/StepResult.php

@@ -3,7 +3,7 @@
 namespace App\Support\Http;
 
 /**
- * One oha result, reduced to the facts the state machine and the curve need.
+ * One oha result, reduced to the facts the sweep and the curve need.
  *
  * Reducing here rather than passing the raw document around is what lets the
  * two drivers stay identical: the generator uploads oha's JSON and the local
@@ -89,7 +89,7 @@ public static function failed(string $reason): self
      * every request reports a perfect success rate, and at a *higher* rate
      * than a working one, because an error is cheap to produce. Checking the
      * status distribution is what turns that from a flattering number into a
-     * stopped ramp.
+     * stopped sweep.
      */
     public function isClean(): bool
     {

docs/app/pages/results/[id].vue

@@ -138,18 +138,12 @@
                          HTTP benchmark — reading it off `http` here silently
                          labelled every worker-mode run "classic mode". -->
                     <ResultsChip>{{ run.environment.php.octane ? 'worker mode' : 'classic mode' }}</ResultsChip>
-                    <ResultsChip v-if="http.duration_seconds">
-                        {{ http.duration_seconds }}s
-                    </ResultsChip>
-                    <ResultsChip v-if="http.connections">
-                        {{ http.connections }} connections
+                    <ResultsChip v-if="http.workers">
+                        {{ http.workers }} workers
                     </ResultsChip>
                     <ResultsChip v-if="http.io_ms != null">
                         I/O {{ http.io_ms }}ms
                     </ResultsChip>
-                    <ResultsChip v-if="http.mode">
-                        {{ http.mode }}
-                    </ResultsChip>
                     <ResultsChip v-if="loadModeLabel">
                         {{ loadModeLabel }}
                     </ResultsChip>
@@ -162,8 +156,9 @@
                 </template>
 
                 <p class="mt-2 text-xs text-neutral-500">
-                    Saturation test — connections held open to find max throughput, so response times
-                    include time spent queued.
+                    Concurrency was raised until throughput stopped improving. Response times were
+                    measured separately, at about 70% of that rate, so they include no queue a real
+                    visitor would not also hit.
                     <NuxtLink
                         to="/docs/benchmarks"
                         class="text-neutral-400 underline underline-offset-4 decoration-white/20 transition-colors hover:text-neutral-300 hover:decoration-white/40"
@@ -187,10 +182,13 @@
                         </p>
                         <div class="mt-2">
                             <p class="text-5xl text-white font-mono font-medium leading-none tabular-nums">
-                                {{ round(benchRoute.data.throughput?.requests_per_second) }}
+                                <!-- A run whose sweep never flattened measured the most BenchKit
+                                     could ask for, not the most the machine can serve. A gallery
+                                     that prints that flat ranks a floor against maximums. -->
+                                <span v-if="benchRoute.isFloor" class="text-amber-400">≥</span>{{ round(benchRoute.data.throughput?.requests_per_second) }}
                             </p>
                             <p class="mt-1.5 text-sm text-neutral-400 font-mono">
-                                req/s
+                                req/s <span v-if="benchRoute.concurrency" class="text-neutral-500">at {{ benchRoute.concurrency }} concurrent</span>
                             </p>
                         </div>
                         <div class="mt-4 flex flex-col gap-2.5">
@@ -230,10 +228,10 @@
                         </p>
                         <div class="mt-auto pt-4">
                             <p class="text-4xl text-white font-mono font-medium leading-none tabular-nums">
-                                {{ round(benchRoute.data.throughput?.requests_per_second) }}
+                                <span v-if="benchRoute.isFloor" class="text-amber-400">≥</span>{{ round(benchRoute.data.throughput?.requests_per_second) }}
                             </p>
                             <p class="mt-1.5 text-sm text-neutral-400 font-mono">
-                                req/s
+                                req/s <span v-if="benchRoute.concurrency" class="text-neutral-500">at {{ benchRoute.concurrency }} concurrent</span>
                             </p>
                         </div>
                     </div>
@@ -691,6 +689,9 @@ const routes = computed(() => {
             })
             return {
                 key,
+                // Where the peak happened, and whether it was a peak at all.
+                concurrency: data.throughput?.concurrency ?? null,
+                isFloor: data.throughput?.saturated === false,
                 label: ROUTES[key]!.label,
                 description: key === 'io' ? `Simulated ~${http.value.io_ms ?? 100}ms outbound call` : ROUTES[key]!.description,
                 data,

resources/js/Components/Share/templates/TemplateFullSuite.vue

@@ -186,7 +186,11 @@ const chips = computed(() => {
         environment.phpVersion ? { text: `PHP ${environment.phpVersion}` } : null,
         environment.laravelVersion ? { text: `Laravel ${environment.laravelVersion}` } : null,
         environment.database ? { text: environment.database } : null,
-        http?.connections && http?.duration_seconds ? { text: `${http.connections} connections · ${http.duration_seconds}s` } : null,
+        // Only when it is not the standard delay: a chip that always says the
+        // same thing is furniture. The connections/duration chip that used to
+        // sit here read fields that no longer exist, so it silently never
+        // rendered.
+        http?.io_ms != null && http.io_ms !== 100 ? { text: `I/O ${http.io_ms}ms` } : null,
         http?.mode && http.mode !== 'loopback' ? { text: httpTargetLabel(http.mode) } : null,
         http?.generator?.mode === 'external' ? { text: 'external load' } : null,
     ].filter(Boolean);

resources/js/Pages/Runs/Compare.vue

@@ -55,7 +55,7 @@
                     </div>
 
                     <p v-if="httpLoadMismatch && headline.path.startsWith('routes.')" class="mt-7 text-sm text-center text-[#F79009]">
-                        These runs used different load settings &mdash; Run A: <span class="font-mono">{{ httpLoadMismatch.a }}</span> &middot; Run B: <span class="font-mono">{{ httpLoadMismatch.b }}</span> &mdash; so throughput isn't directly comparable.
+                        These runs simulated a different outbound call &mdash; Run A: <span class="font-mono">{{ httpLoadMismatch.a }}</span> &middot; Run B: <span class="font-mono">{{ httpLoadMismatch.b }}</span> &mdash; so the I/O route measured different work on each side.
                     </p>
                 </section>
 
@@ -164,11 +164,19 @@ const httpLoadMismatch = computed(() => {
         return null;
     }
 
-    if( a.connections === b.connections && a.duration_seconds === b.duration_seconds ) {
+    // The load sizes itself from each machine now, so two runs differing in
+    // concurrency is expected and says nothing. What still makes throughput
+    // apples-to-oranges is the one load parameter left — the simulated delay
+    // changes what /bench/io measures rather than how hard the load pushes.
+    //
+    // This used to compare connections and duration, and after those stopped
+    // existing it compared undefined against undefined: always equal, so the
+    // banner could never fire at all.
+    if( (a.io_ms ?? null) === (b.io_ms ?? null) ) {
         return null;
     }
 
-    const label = (http) => `${http.connections ?? '?'} connections × ${http.duration_seconds ?? '?'}s`;
+    const label = (http) => `${http.io_ms ?? '?'}ms simulated I/O`;
 
     return { a: label(a), b: label(b) };
 });