Observability: Decision Taps, Analytics, OpenTelemetry

import { tapDecisions, type DecisionTap, type DecisionEvent } from "throttlekit";

const limiter = tapDecisions(
  rateLimit({ strategy: gcra({ limit: 100, periodMs: 60_000 }) }),
  (event) => {
    if (!event.decision.allowed) {
      log.warn({ key: event.key, retryAfterMs: event.decision.retryAfterMs }, "rate limited");
    }
    myHistogram.observe(event.durationMs);
  },
);

import { withAnalytics } from "throttlekit";
import { ManualClock, gcra, rateLimit } from "throttlekit";

const clock = new ManualClock(0);

const limiter = withAnalytics(
  rateLimit({ strategy: gcra({ limit: 3, periodMs: 60_000 }), clock }),
  { topK: 5, windowMs: 60_000, clock },
);

// Drive some traffic
for (let i = 0; i < 10; i++) limiter.checkSync("198.51.100.7");  // 3 allowed, 7 denied
for (let i = 0; i < 2; i++)  limiter.checkSync("203.0.113.9");   // both allowed

const snap = limiter.analytics();
console.log({ allowed: snap.allowed, denied: snap.denied, denyRate: snap.denyRate });
console.log("topRequested:", snap.topRequested.map((h) => `${h.key}=${h.count}`).join(", "));
console.log("topDenied:",    snap.topDenied.map((h) => `${h.key}=${h.count}`).join(", "));

// After a window roll, counts reset
clock.advance(60_000);
console.log("after roll, total:", limiter.analytics().total); // 0

interface HeavyHitter {
  key: string;
  count: number; // Space-Saving upper-bound estimate; never under-counts a true heavy hitter
}

import { instrumentLimiter, instrumentGuard } from "throttlekit/otel";
import { metrics } from "@opentelemetry/api";

const meter  = metrics.getMeter("my-service");
const limiter = instrumentLimiter(baseRateLimiter, meter);
const guard   = instrumentGuard(concurrencyGuard, meter);

import { bindingAxisOf } from "throttlekit/otel";

const axis = bindingAxisOf(admit.lastDecisions());
// → "rate" | "concurrency" | "cost" | undefined (on allow or policy-deny)

throttlekit-server --config .throttlekit.yaml --tui