@absolutejs/metering

Per-tenant cost-attribution + budget enforcement for multi-tenant Bun runtimes.

Built for PaaS providers that run many small Bun apps under one host. Consumes handlerMetrics from @absolutejs/sync and lifecycle events from @absolutejs/runtime, rolls them up per tenant, and trips a circuit breaker the moment any per-tenant budget dimension is exceeded. The library SB-6 layer between the runtime and the billing / observability pipeline downstream.

import { createMeter, consoleSink } from "@absolutejs/metering";

const meter = createMeter({
  sinks: [consoleSink, influxSink],
  budgets: {
    "*": { cpuMs: 60_000, requests: 10_000 }, // free-tier default
    "acme-prod": { cpuMs: 600_000, requests: 1_000_000 }, // paid override
  },
  onBreach: ({ tenant, dimension, observed, limit }) => {
    suspendAtRouter(tenant, { dimension, observed, limit });
  },
});

// Wire it into a sync engine: sync handlerMetrics records → meter.record(...)
syncEngine.handlerMetrics = (record) => {
  meter.record({
    type: "handler",
    tenant: currentTenantId(),
    mutationName: record.mutationName,
    durationMs: record.durationMs,
    cpuMs: record.cpuMs,
    heapBytes: record.heapBytes,
    ok: record.ok,
    errorName: record.errorName,
  });
};

// And a runtime: spawn/idle-kill/exit transitions → meter.record(...)
runtime.options.onTransition = (event) => {
  meter.record({
    type: "process",
    tenant: event.key,
    transition: event.type,
    durationMs: event.durationMs,
  });
};

// And @absolutejs/[email protected]'s Linux observation events:
runtime.options.onMetrics = (event) => {
  if (event.type === "observation") {
    meter.record({
      type: "observation",
      tenant: event.key,
      cpuMs: event.cpuMs,
      rssBytes: event.rssBytes,
      at: event.at,
    });
  }
};

// Record one terminal AI agent run. `costMicros` is caller-calculated so model
// pricing stays an operator policy instead of becoming stale library data.
meter.record({
  type: "ai",
  tenant: tenantId,
  requestId,
  provider: "anthropic",
  model: "claude-sonnet-4-6",
  inputTokens: finish.usage.inputTokens,
  outputTokens: finish.usage.outputTokens,
  cacheReadInputTokens: finish.usage.cacheReadInputTokens,
  cacheWriteInputTokens: finish.usage.cacheWriteInputTokens,
  durationMs: finish.durationMs,
  turns: finish.turns,
  costMicros,
  ok: finish.reason === "complete",
  stopReason: finish.reason,
});

// Inside a hosted workload, hand handler/request events to the authenticated
// host-local collector. The PaaS injects this endpoint, token, and per-process
// source id; no tenant id is accepted from application code.
import { createWorkloadMeterReporter } from "@absolutejs/metering/reporter";
import { workloadMeterElysia } from "@absolutejs/metering/elysia";

const reporter = createWorkloadMeterReporter({
  endpoint: process.env.ABSOLUTE_METER_ENDPOINT!,
  sourceId: process.env.ABSOLUTE_METER_SOURCE_ID!,
  token: process.env.ABSOLUTE_METER_TOKEN!,
});
const app = new Elysia().use(workloadMeterElysia({ reporter }));
syncEngine.handlerMetrics = reporter.handlerMetrics;

// In your request handler, gate on the meter:
if (!meter.allow(tenantId))
  return new Response("Quota exceeded", { status: 429 });

Surface (0.2.0)

Sinks

A MeterSink is either a function (event) => void | Promise<void> or an object { ingest, flush?, close? }. Sinks are fanned out in order. A throw or rejection from one sink does not stop later sinks — the meter is on the billing critical path. The error is logged to stderr; the recorder keeps going.

On dispose(), every object-shaped sink's flush() is awaited (serial across sinks), then every close() is awaited. A throwing flush is logged + swallowed; later sinks still flush. This is what batched adapters (Stripe, Influx, ClickHouse) need to not drop the last few events on shutdown.

Bundled: consoleSink. Adapters for Influx / Prometheus / Stripe ship later as sibling packages.

Cumulative budgets

budgets['*'] is the default; per-tenant entries override it. Any dimension hitting its limit trips the breaker; onBreach fires once per trip (call reset() to re-arm). Subsequent events still accumulate — the bill keeps growing even after the gate is closed, which matches how real billing works.

Dimensions: cpuMs, processCpuMs, bytesEgress, requests, errors, hibernationGbSeconds, aiRequests, aiInputTokens, aiOutputTokens, aiCostMicros.

Rolling-window budgets

createMeter({
  rollingBudgets: {
    "*": [
      { dimension: "errors", windowMs: 5 * 60_000, limit: 50 }, // 50 errors / 5 min trips the breaker
      { dimension: "requests", windowMs: 1 * 60_000, limit: 1_000 }, // 1k req / min rate cap
    ],
    "acme-prod": [
      { dimension: "cpuMs", windowMs: 60_000, limit: 50_000 }, // 50s sandbox CPU / minute
    ],
  },
});

A rolling-window rule trips when the rolling sum reaches limit. It re-closes automatically as events drain out of the window — no reset() needed. That's the difference from a cumulative budget, which sticks until reset(). Both kinds can be set on the same tenant; allow() is false if any rule trips.

Observation accounting

@absolutejs/[email protected] emits { type: 'observation', cpuMs, rssBytes } on a configurable interval. The meter treats cpuMs as CUMULATIVE since spawn and charges the delta since the previous observation. A process event of transition === 'spawn', 'adopt', 'restored', or 'exit' resets the baseline so a fresh or newly supervised process doesn't double-charge. Only a real spawn increments the spawn counter.

Hibernation accounting

@absolutejs/runtime emits idle-kill / lru-evict transitions; the metering caller is responsible for computing the GB-seconds the tenant racks up while hibernated and passing it as hibernationGbSeconds on the process event. The meter sums the values it sees — it does not infer them.

Snapshot + restore

const json = JSON.stringify(meter.snapshot());
await persistToDisk('/var/lib/meter/state.json', json);

// On shard restart:
const restored = createMeter({ ... same config ... });
restored.restore(JSON.parse(await readFromDisk('/var/lib/meter/state.json')));

The snapshot captures every tenant's usage, tripped state, rolling-window state, and the last observation cpuMs baseline so the next observation charges a sensible delta instead of jumping to the cumulative-since-process-start value.

Architectural role

• @absolutejs/sync — emits handlerMetrics records on every sandboxed mutation.
• @absolutejs/runtime — emits lifecycle events on every spawn / idle-kill / exit.
• @absolutejs/metering — this library. Rolls those up per tenant + gates them.
• @absolutejs/router (planned) — consumes meter.allow() to refuse traffic for over-quota tenants at the edge.

License

BSL 1.1 with a named carveout for the hosted multi-tenant metering / cost-attribution / per-tenant billing category (Stripe Metered Billing, Orb, Metronome, Lago, Amberflo, Cloudflare Workers billing, Convex usage dashboards, Vercel usage dashboards). See LICENSE. Change Date: 4 years from first release; Change License: Apache 2.0.