axusage 3.5.0 → 3.6.0

package/dist/commands/serve-command.js

@@ -97,12 +97,15 @@ export async function serveCommand(options) {
             process.exit(1);
         }, 5000);
         forceExit.unref();
-        server.stop().then(() => {
+        server
+            .stop()
+            .finally(() => {
             clearTimeout(forceExit);
+        })
+            .then(() => {
             // eslint-disable-next-line unicorn/no-process-exit -- CLI graceful shutdown
             process.exit(0);
         }, (error) => {
-            clearTimeout(forceExit);
             console.error("Error during shutdown:", error);
             // eslint-disable-next-line unicorn/no-process-exit -- CLI graceful shutdown
             process.exit(1);

package/dist/commands/usage-command.js

@@ -74,9 +74,10 @@ export async function usageCommand(options) {
                 console.log(formatServiceUsageDataAsJson(singleSuccess));
             }
             else {
+                const now = Date.now();
                 const payload = successes.length === 1 && singleSuccess
-                    ? toJsonObject(singleSuccess)
-                    : successes.map((data) => toJsonObject(data));
+                    ? toJsonObject(singleSuccess, now)
+                    : successes.map((data) => toJsonObject(data, now));
                 const output = hasPartialFailures
                     ? {
                         results: payload,
@@ -94,7 +95,7 @@ export async function usageCommand(options) {
         }
         case "prometheus": {
             // Emit Prometheus text metrics using prom-client
-            const output = await formatPrometheusMetrics(successes);
+            const output = await formatPrometheusMetrics(successes, Date.now());
             process.stdout.write(output);
             break;
         }

package/dist/server/routes.js

@@ -27,6 +27,8 @@ export function createMetricsRouter(getState) {
     // Memoize the rendered Prometheus text by the state snapshot's refreshedAt
     // timestamp. Scrapes within the same cache window reuse the same Promise,
     // avoiding recreating prom-client Registry/Gauge objects on each request.
+    // Rate is computed at refreshedAt so output is deterministic per snapshot,
+    // keeping the gauge coherent with the usage data it describes.
     // Assignments happen synchronously (before any await) so require-atomic-updates
     // is satisfied and concurrent scrapes naturally coalesce onto one render.
     let memoFor;
@@ -40,7 +42,7 @@ export function createMetricsRouter(getState) {
         }
         if (memoFor !== state.refreshedAt) {
             memoFor = state.refreshedAt;
-            memoPromise = formatPrometheusMetrics(usage);
+            memoPromise = formatPrometheusMetrics(usage, state.refreshedAt.getTime());
         }
         const text = await memoPromise;
         response
@@ -60,7 +62,9 @@ export function createUsageRouter(getFreshState) {
             response.status(503).json({ error: "No data yet" });
             return;
         }
-        response.status(200).json(usage.map((entry) => toJsonObject(entry)));
+        response
+            .status(200)
+            .json(usage.map((entry) => toJsonObject(entry, state.refreshedAt.getTime())));
     });
     return router;
 }

package/dist/utils/calculate-usage-rate.d.ts

@@ -6,4 +6,4 @@
  * Rate is shown after either {@link MIN_ELAPSED_FRACTION} of the period OR
  * {@link MIN_ELAPSED_TIME_MS} has passed (whichever comes first).
  */
-export declare function calculateUsageRate(utilization: number, resetsAt: Date | undefined, periodDurationMs: number): number | undefined;
+export declare function calculateUsageRate(utilization: number, resetsAt: Date | undefined, periodDurationMs: number, now: number): number | undefined;

package/dist/utils/calculate-usage-rate.js

@@ -10,12 +10,11 @@ const MIN_ELAPSED_TIME_MS = 2 * 60 * 60 * 1000;
  * Rate is shown after either {@link MIN_ELAPSED_FRACTION} of the period OR
  * {@link MIN_ELAPSED_TIME_MS} has passed (whichever comes first).
  */
-export function calculateUsageRate(utilization, resetsAt, periodDurationMs) {
+export function calculateUsageRate(utilization, resetsAt, periodDurationMs, now) {
     if (!resetsAt)
         return undefined;
     if (periodDurationMs <= 0)
         return 0;
-    const now = Date.now();
     const resetTime = resetsAt.getTime();
     const periodStart = resetTime - periodDurationMs;
     const elapsedTime = now - periodStart;

package/dist/utils/format-prometheus-metrics.d.ts

@@ -1,6 +1,6 @@
 import type { ServiceUsageData } from "../types/domain.js";
 /**
  * Formats service usage data as Prometheus text exposition using prom-client.
- * Emits a gauge `axusage_utilization_percent{service,window}` per window.
+ * Emits gauges `axusage_utilization_percent` and `axusage_usage_rate` per window.
  */
-export declare function formatPrometheusMetrics(data: readonly ServiceUsageData[]): Promise<string>;
+export declare function formatPrometheusMetrics(data: readonly ServiceUsageData[], now: number): Promise<string>;

package/dist/utils/format-prometheus-metrics.js

@@ -1,19 +1,31 @@
 import { Gauge, Registry } from "prom-client";
+import { calculateUsageRate } from "./calculate-usage-rate.js";
 /**
  * Formats service usage data as Prometheus text exposition using prom-client.
- * Emits a gauge `axusage_utilization_percent{service,window}` per window.
+ * Emits gauges `axusage_utilization_percent` and `axusage_usage_rate` per window.
  */
-export async function formatPrometheusMetrics(data) {
+export async function formatPrometheusMetrics(data, now) {
     const registry = new Registry();
-    const gauge = new Gauge({
+    const utilizationGauge = new Gauge({
         name: "axusage_utilization_percent",
         help: "Current utilization percentage by service/window",
         labelNames: ["service", "window"],
         registers: [registry],
     });
+    const rateGauge = new Gauge({
+        name: "axusage_usage_rate",
+        help: "Usage rate (utilization / elapsed fraction of period); >1 means over budget",
+        labelNames: ["service", "window"],
+        registers: [registry],
+    });
     for (const entry of data) {
         for (const w of entry.windows) {
-            gauge.set({ service: entry.service, window: w.name }, w.utilization);
+            const labels = { service: entry.service, window: w.name };
+            utilizationGauge.set(labels, w.utilization);
+            const rate = calculateUsageRate(w.utilization, w.resetsAt, w.periodDurationMs, now);
+            if (rate !== undefined) {
+                rateGauge.set(labels, rate);
+            }
         }
     }
     return registry.metrics();

package/dist/utils/format-service-usage.d.ts

@@ -6,7 +6,7 @@ export declare function formatServiceUsageData(data: ServiceUsageData): string;
 /**
  * Converts service usage data to a plain JSON-serializable object
  */
-export declare function toJsonObject(data: ServiceUsageData): unknown;
+export declare function toJsonObject(data: ServiceUsageData, now: number): unknown;
 /**
  * Formats service usage data as JSON string
  */

package/dist/utils/format-service-usage.js

@@ -34,10 +34,9 @@ function getUtilizationColor(rate) {
  */
 function formatUsageWindow(window) {
     const utilizationString = formatUtilization(window.utilization);
-    const rate = calculateUsageRate(window.utilization, window.resetsAt, window.periodDurationMs);
+    const rate = calculateUsageRate(window.utilization, window.resetsAt, window.periodDurationMs, Date.now());
     const coloredUtilization = getUtilizationColor(rate)(utilizationString);
     const resetTime = formatResetTime(window.resetsAt);
-    // Build full display string for rate to keep formatting consistent
     const rateDisplay = rate === undefined ? "Not available" : `${rate.toFixed(2)}x rate`;
     return `${chalk.bold(window.name)}:
   Utilization: ${coloredUtilization} (${rateDisplay})
@@ -47,14 +46,17 @@ function formatUsageWindow(window) {
  * Formats complete service usage data for human-readable display
  */
 export function formatServiceUsageData(data) {
+    let statusWarning;
+    if (data.metadata?.limitReached === true) {
+        statusWarning = chalk.red("⚠ Rate limit reached");
+    }
+    else if (data.metadata?.allowed === false) {
+        statusWarning = chalk.red("⚠ Usage not allowed");
+    }
     const header = [
         chalk.cyan.bold(`=== ${data.service} Usage ===`),
         data.planType ? chalk.gray(`Plan: ${data.planType}`) : undefined,
-        data.metadata?.limitReached === true
-            ? chalk.red("⚠ Rate limit reached")
-            : data.metadata?.allowed === false
-                ? chalk.red("⚠ Usage not allowed")
-                : undefined,
+        statusWarning,
     ]
         .filter(Boolean)
         .join("\n");
@@ -66,16 +68,20 @@ export function formatServiceUsageData(data) {
 /**
  * Converts service usage data to a plain JSON-serializable object
  */
-export function toJsonObject(data) {
+export function toJsonObject(data, now) {
     return {
         service: data.service,
         planType: data.planType,
-        windows: data.windows.map((w) => ({
-            name: w.name,
-            utilization: w.utilization,
-            resetsAt: w.resetsAt?.toISOString(),
-            periodDurationMs: w.periodDurationMs,
-        })),
+        windows: data.windows.map((w) => {
+            const rate = calculateUsageRate(w.utilization, w.resetsAt, w.periodDurationMs, now);
+            return {
+                name: w.name,
+                utilization: w.utilization,
+                rate,
+                resetsAt: w.resetsAt?.toISOString(),
+                periodDurationMs: w.periodDurationMs,
+            };
+        }),
         metadata: data.metadata,
     };
 }
@@ -84,7 +90,7 @@ export function toJsonObject(data) {
  */
 export function formatServiceUsageDataAsJson(data) {
     // eslint-disable-next-line unicorn/no-null -- JSON.stringify requires null for no replacer
-    return JSON.stringify(toJsonObject(data), null, 2);
+    return JSON.stringify(toJsonObject(data, Date.now()), null, 2);
 }
 const TSV_HEADER = "SERVICE\tPLAN\tWINDOW\tUTILIZATION\tRATE\tRESETS_AT";
 /**
@@ -99,7 +105,7 @@ function sanitizeForTsv(value) {
  */
 function formatServiceUsageRowsAsTsv(data) {
     return data.windows.map((w) => {
-        const rate = calculateUsageRate(w.utilization, w.resetsAt, w.periodDurationMs);
+        const rate = calculateUsageRate(w.utilization, w.resetsAt, w.periodDurationMs, Date.now());
         return [
             sanitizeForTsv(data.service),
             sanitizeForTsv(data.planType ?? "-"),

package/package.json

@@ -2,7 +2,7 @@
   "name": "axusage",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Monitor API usage across Claude, ChatGPT, GitHub Copilot, and Gemini from a single CLI",
   "repository": {
     "type": "git",