Cost Observability

Cost Observability is the surface that answers “what did it actually cost us to move this money?” — interchange, scheme, processor, and acquirer fees broken down per connector and currency, plus interchange downgrades, cost anomalies, and a forward-looking fee forecast.

It is a thin read-only proxy over Hyperswitch’s analytics OLAP surface (Kafka + ClickHouse + a scheduler), in keeping with ADR-007 · Maximum native Hyperswitch bias. MVS owns no cost data of its own here: every metric is computed in ClickHouse by Hyperswitch and surfaced through /analytics/v1/cost/*. The route layer adds exactly one thing on top — graceful degradation.

Where this lives

The routes are mounted under the authenticated API surface in apps/mvs-pay-extensions/src/app.ts:

1
// apps/mvs-pay-extensions/src/app.ts
2
api.route("/cost-observability", costObservabilityRoutes);
3
app.route("/v1", api);

so the public base path is /v1/cost-observability. Like every route on the api sub-app it sits behind authMiddleware() (internal secret + tenant resolution) and auditLog(). It is not rate-limited and not wrapped in idempotency — both are correct for read-only GETs. The spec reference for the surface is docs/superpowers/specs/2026-05-28-mvs-pay-perfection/14-phase-4-power-features.md § M22.2.

The four endpoints

Four GET endpoints, each a best-effort proxy to one Hyperswitch analytics OLAP query. See the API Reference (tag: Cost Observability) for the full request/response schemas.

Query parameters

The first three endpoints share a date-range contract, assembled by rangeQuery() in the route handler:

forecast does not take a range — it takes horizon, which is validated against the literal set {"30d", "90d"}; anything else is 400 INVALID_HORIZON.

Response shape: a discriminated union

Every endpoint returns one of two shapes. This is the crux of the surface:

1
// Happy path — OLAP data
2
{ "data": [ /* rows for this metric */ ] }
3
4
// Degraded path — OLAP unavailable
5
{ "link_to_dashboard": "https://.../analytics/cost-observability/fee-breakdown" }

The caller (SDK / operator dashboard) must branch on which key is present. The OpenAPI fragment models this explicitly as a oneOf of CostObservability<Metric>Data and CostObservabilityDashboardLink.

The OLAP data rows are typed in the OpenAPI fragment (the client itself only types them as { data: unknown[] }):

• fee-breakdown — connector, currency, interchange_amount, scheme_amount, processor_amount, acquirer_amount, total_fees, transaction_count, volume.
• downgrades — payment_id, connector, expected_tier, actual_tier, fee_delta, currency, captured_at.
• anomalies — connector, scheme, region, metric (fee_rate | volume | decline_rate), delta_pct, detected_at.
• forecast — date, expected_fees, currency, confidence_low, confidence_high.

OLAP dependency & degraded mode

This surface is only as good as the analytics pipeline behind it. That pipeline is the OLAP profile documented in the Hyperswitch OLAP runbook: three moving parts that must all be healthy before a single cost row exists.

If any link in that chain is missing — most commonly because olap.enabled is false and the StatefulSets were never created — the analytics service returns 404/501 (or 503), and the route degrades.

How degradation works

Two small helpers in cost-observability.ts do all the work:

1
// 404/501 from Hyperswitch's analytics surface = OLAP disabled or metric
2
// not exposed. We swallow those and degrade to a deep-link.
3
function isFallbackEligible(err: HyperswitchApiError): boolean {
4
  return err.statusCode === 404 || err.statusCode === 501;
5
}
6
7
function dashboardLink(path: string): { link_to_dashboard: string } {
8
  return { link_to_dashboard: `${DASHBOARD_BASE_URL}/${path}` };
9
}

The per-endpoint control flow is identical:

The deep-link target

The fallback URL is built from DASHBOARD_BASE_URL:

1
const DASHBOARD_BASE_URL =
2
  process.env.HYPERSWITCH_DASHBOARD_URL ??
3
  "https://hyperswitch.payments.internal/analytics/cost-observability";

So the link is ${HYPERSWITCH_DASHBOARD_URL || default}/<metric>, where <metric> is fee-breakdown, downgrades, anomalies, or forecast. The path segment deliberately mirrors the endpoint name so an operator lands on the right Control Center view. The same data is rendered there via the embedded Control Center analytics page — which itself only has data if OLAP is on, so a deep-link from a disabled environment leads to an empty Control Center chart, not a populated one. The link is an escape hatch, not a fix.

What the operator sees

When the route returns { link_to_dashboard }, the operator dashboard at apps/mvs-pay/app/(dashboard)/cost-observability/ renders an empty state rather than charts. (Note this page ships on disk but is not on the navigation rail returned by getMvsPayNavSections() — it is reached contextually; see the Merchant & Operator UI page.)

Forecast is the honest stub

Be explicit about this one, because it is the most likely to mislead:

Worked examples

Happy path (OLAP provisioned, data exists):

$
curl -fsS \
>
  -H "x-internal-secret: $MVS_INTERNAL_SECRET" \
>
  -H "x-org-slug: acme" \
>
  "https://extensions.mvspay.internal/v1/cost-observability/fee-breakdown?from=2026-04-01&to=2026-05-01&connector=stripe&currency=USD"
$
# { "data": [ { "connector": "stripe", "currency": "USD",
>
#               "interchange_amount": 812.40, "scheme_amount": 91.10,
>
#               "processor_amount": 220.00, "acquirer_amount": 64.00,
>
#               "total_fees": 1187.50, "transaction_count": 4123,
>
#               "volume": 318204.55 } ] }

Degraded path (OLAP not provisioned → 404 upstream → deep-link):

$
curl -fsS \
>
  -H "x-internal-secret: $MVS_INTERNAL_SECRET" \
>
  -H "x-org-slug: acme" \
>
  "https://extensions.mvspay.internal/v1/cost-observability/fee-breakdown?from=2026-04-01&to=2026-05-01"
$
# { "link_to_dashboard":
>
#     "https://hyperswitch.payments.internal/analytics/cost-observability/fee-breakdown" }

Validation error (missing range):

$
curl -s \
>
  -H "x-internal-secret: $MVS_INTERNAL_SECRET" \
>
  -H "x-org-slug: acme" \
>
  "https://extensions.mvspay.internal/v1/cost-observability/fee-breakdown?from=2026-04-01"
$
# 400
$
# { "error": { "code": "MISSING_RANGE", "message": "from and to are required" } }

These three shapes — data, link_to_dashboard, and the error envelope — are exactly what the tests in cost-observability.test.ts assert.

Turning the data on

If the dashboard is showing empty states and you need real numbers, the fix is not in this route — it’s provisioning OLAP. The full procedure is the Hyperswitch OLAP runbook; the short version:

Gaps & gotchas for the next owner

Related