Fix spans-per-trace slider not affecting storage calculations (#169)

The spans-per-trace slider had no effect on any storage or ingest
metric because total spans was a direct input. Restructured the
model so traces/month is the input and spans = traces * spans/trace,
making every slider affect at least one output metric.

Also fixed stale formulas in the How It Works section and docs page.

Signed-off-by: Anirudha Jadhav <anirudha@nyu.edu>

Author: anirudha

docs/src/components/APMUsageCalculator.test.tsx

@@ -3,7 +3,7 @@ import { render, screen } from '@testing-library/react';
 import APMUsageCalculator, { calculateUsage } from './APMUsageCalculator';
 
 const defaults = {
-  spansPerMonth: 10_000_000,
+  tracesPerMonth: 1_250_000,
   avgSpanSizeKB: 0.5,
   spansPerTrace: 8,
   services: 10,
@@ -12,22 +12,30 @@ const defaults = {
 };
 
 describe('calculateUsage', () => {
-  it('computes traces from spans and spans-per-trace', () => {
+  it('derives spans from traces * spans-per-trace', () => {
     const result = calculateUsage(defaults);
-    expect(result.tracesPerMonth).toBe(10_000_000 / 8);
+    expect(result.spansPerMonth).toBe(1_250_000 * 8);
   });
 
   it('computes retained spans based on retention', () => {
     const result = calculateUsage(defaults);
-    expect(result.retainedSpans).toBe(10_000_000 * (15 / 30));
+    const spansPerMonth = 1_250_000 * 8;
+    expect(result.retainedSpans).toBe(spansPerMonth * (15 / 30));
   });
 
   it('computes span storage in bytes with index overhead', () => {
     const result = calculateUsage(defaults);
-    const rawBytes = 10_000_000 * (15 / 30) * 0.5 * 1024;
+    const spansPerMonth = 1_250_000 * 8;
+    const rawBytes = spansPerMonth * (15 / 30) * 0.5 * 1024;
     expect(result.spanStorageBytes).toBe(rawBytes * 2.0);
   });
 
+  it('spans-per-trace slider affects storage', () => {
+    const r8 = calculateUsage({ ...defaults, spansPerTrace: 8 });
+    const r16 = calculateUsage({ ...defaults, spansPerTrace: 16 });
+    expect(r16.spanStorageBytes).toBe(r8.spanStorageBytes * 2);
+  });
+
   it('computes directed service map edges as n*(n-1)', () => {
     const result = calculateUsage(defaults);
     expect(result.edges).toBe(10 * 9);
@@ -53,7 +61,7 @@ describe('calculateUsage', () => {
   it('scales storage linearly with retention', () => {
     const r15 = calculateUsage({ ...defaults, retentionDays: 15 });
     const r30 = calculateUsage({ ...defaults, retentionDays: 30 });
-    expect(r30.spanStorageBytes).toBe(r15.spanStorageBytes * 2);
+    expect(r30.spanStorageBytes).toBeCloseTo(r15.spanStorageBytes * 2, 0);
   });
 
   it('ingest rate is positive', () => {
@@ -65,7 +73,7 @@ describe('calculateUsage', () => {
 describe('APMUsageCalculator component', () => {
   it('renders slider labels', () => {
     render(<APMUsageCalculator />);
-    expect(screen.getByText('Spans ingested / month')).toBeTruthy();
+    expect(screen.getByText('Traces (requests) / month')).toBeTruthy();
     expect(screen.getByText('Avg span payload size')).toBeTruthy();
     expect(screen.getByText('Number of services')).toBeTruthy();
     expect(screen.getByText('Retention period')).toBeTruthy();

docs/src/components/APMUsageCalculator.tsx

@@ -34,13 +34,13 @@ function formatBytes(bytes: number): string {
 }
 
 const sliders: Record<string, SliderConfig> = {
-  spansPerMonth: {
-    label: 'Spans ingested / month',
-    min: 1_000_000,
-    max: 10_000_000_000,
-    step: 1_000_000,
-    default: 10_000_000,
-    unit: 'spans',
+  tracesPerMonth: {
+    label: 'Traces (requests) / month',
+    min: 100_000,
+    max: 1_000_000_000,
+    step: 100_000,
+    default: 1_250_000,
+    unit: 'traces',
     format: formatCompact,
     logarithmic: true,
   },
@@ -272,16 +272,16 @@ function Section({
 
 export function calculateUsage(values: Record<SliderKey, number>) {
   const {
-    spansPerMonth,
+    tracesPerMonth,
     avgSpanSizeKB,
     spansPerTrace,
     services,
     opsPerService,
     retentionDays,
   } = values;
 
-  // Span storage
-  const tracesPerMonth = spansPerMonth / spansPerTrace;
+  // Span storage — spans derived from traces * spans/trace
+  const spansPerMonth = tracesPerMonth * spansPerTrace;
   const retainedSpans = spansPerMonth * (retentionDays / 30);
   const spanRawBytes = retainedSpans * avgSpanSizeKB * 1024;
   const spanStorageBytes = spanRawBytes * OPENSEARCH_INDEX_OVERHEAD;
@@ -311,6 +311,7 @@ export function calculateUsage(values: Record<SliderKey, number>) {
   const ingestRate = totalDocsPerDay / 86400;
 
   return {
+    spansPerMonth,
     tracesPerMonth,
     retainedSpans,
     spanStorageBytes,
@@ -381,7 +382,7 @@ function HowItWorks() {
               start/end timestamps, duration, status code, and dynamic attributes.
             </p>
             <div className="font-mono text-xs bg-slate-950 rounded p-3 space-y-1">
-              <div><span className="text-slate-500">Traces/month</span> = spans_per_month / avg_spans_per_trace</div>
+              <div><span className="text-slate-500">Spans/month</span> = traces_per_month * avg_spans_per_trace</div>
               <div><span className="text-slate-500">Retained spans</span> = spans_per_month * (retention_days / 30)</div>
               <div><span className="text-slate-500">Storage</span> = retained_spans * avg_span_size_kb * 1024 * 2.0x index overhead</div>
             </div>
@@ -501,14 +502,14 @@ export default function APMUsageCalculator() {
 
           <Section title="Span Storage (OpenSearch)">
             <MetricRow
-              label="Traces / month"
-              value={formatCompact(usage.tracesPerMonth)}
-              formula={`= ${formatCompact(values.spansPerMonth)} spans / ${values.spansPerTrace} spans-per-trace`}
+              label="Spans / month"
+              value={formatCompact(usage.spansPerMonth)}
+              formula={`= ${formatCompact(values.tracesPerMonth)} traces * ${values.spansPerTrace} spans/trace`}
             />
             <MetricRow
               label="Spans retained"
               value={formatCompact(usage.retainedSpans)}
-              formula={`= ${formatCompact(values.spansPerMonth)} spans/mo * (${values.retentionDays} / 30) retention`}
+              formula={`= ${formatCompact(usage.spansPerMonth)} spans/mo * (${values.retentionDays} / 30) retention`}
             />
             <MetricRow
               label="Storage (with index overhead)"

docs/starlight-docs/src/content/docs/apm/sizing-calculator.md

@@ -17,7 +17,7 @@ Spans are the raw building blocks of traces. Each span document is indexed into
 
 | Output | Formula |
 |--------|---------|
-| **Traces / month** | `spans_per_month ÷ avg_spans_per_trace` |
+| **Spans / month** | `traces_per_month × avg_spans_per_trace` |
 | **Retained spans** | `spans_per_month × (retention_days ÷ 30)` |
 | **Storage** | `retained_spans × avg_span_size × 2.0` (the 2.0× factor accounts for OpenSearch index overhead — field mappings, inverted indices, doc values) |
 | **Ingest rate** | `spans_per_month ÷ 30 ÷ 86400` (spans/sec) |
@@ -50,7 +50,7 @@ The calculator sums OpenSearch storage (spans + service map) and Prometheus stor
 
 | Parameter | Default | Range | Description |
 |-----------|---------|-------|-------------|
-| Spans ingested / month | 10M | 1M – 10B | Total span documents your applications generate per month |
+| Traces (requests) / month | 1.25M | 100K – 1B | Total traces (requests) your applications generate per month |
 | Avg span payload size | 0.5 KB | 0.1 – 50 KB | Average size of a single span document before indexing |
 | Avg spans per trace | 8 | 1 – 200 | How many spans make up one trace on average |
 | Number of services | 10 | 1 – 1000 | Distinct instrumented services in your environment |