talon-agent 1.36.0 → 1.37.0

package/src/util/metrics.ts

@@ -1,80 +1,168 @@
-// src/util/metrics.ts — lightweight in-process metrics
+// Session-backed metrics aggregation. Writes for chat turns live on
+// storage/sessions.ts; this module keeps the public read shape used by
+// /metrics and a small compatibility sink for non-chat legacy counters.
 
-const counters = new Map<string, number>();
-const MAX_METRIC_KEYS = 500; // cap to prevent unbounded growth from high-cardinality names
+import {
+  getAllSessions,
+  resetAllSessionMetrics,
+  todayUtc,
+  type MetricsGrain,
+  type MetricsLatencyAgg,
+} from "../storage/sessions.js";
 
-// Ring buffer for histograms — O(1) insert, avoids splice overhead
-interface RingBuffer {
-  data: number[];
-  head: number; // next write position
-  size: number; // current number of valid entries (≤ capacity)
-}
+const legacyCounters = new Map<string, number>();
 
-const histograms = new Map<string, RingBuffer>();
-const MAX_HISTOGRAM_SIZE = 1000;
+export type MetricsSnapshot = {
+  counters: Record<string, number>;
+  histograms: Record<
+    string,
+    { count: number; avg: number; min: number; max: number }
+  >;
+};
 
-function createRingBuffer(capacity: number): RingBuffer {
-  return { data: new Array<number>(capacity), head: 0, size: 0 };
+export function incrementCounter(name: string, amount = 1): void {
+  legacyCounters.set(name, (legacyCounters.get(name) ?? 0) + amount);
 }
 
-function ringPush(buf: RingBuffer, value: number): void {
-  buf.data[buf.head] = value;
-  buf.head = (buf.head + 1) % buf.data.length;
-  if (buf.size < buf.data.length) buf.size++;
+export function recordHistogram(_name: string, _value: number): void {
+  // The old global histogram ring is intentionally gone. Chat-turn
+  // histograms are now latency aggregates on SessionMetrics.
 }
 
-function ringValues(buf: RingBuffer): number[] {
-  if (buf.size < buf.data.length) return buf.data.slice(0, buf.size);
-  // Full ring — read from head (oldest) wrapping around
-  return [...buf.data.slice(buf.head), ...buf.data.slice(0, buf.head)];
+function addCounter(
+  counters: Record<string, number>,
+  name: string,
+  amount: number | undefined,
+): void {
+  if (typeof amount === "number" && Number.isFinite(amount) && amount !== 0) {
+    counters[name] = (counters[name] ?? 0) + amount;
+  }
 }
 
-export function incrementCounter(name: string, amount = 1): void {
-  // Only allow new keys up to the cap — existing keys always pass
-  if (!counters.has(name) && counters.size >= MAX_METRIC_KEYS) return;
-  counters.set(name, (counters.get(name) ?? 0) + amount);
+function mergeAgg(target: MetricsLatencyAgg, source: MetricsLatencyAgg): void {
+  if (!source.count) return;
+  target.count += source.count;
+  target.sumMs += source.sumMs;
+  target.minMs = Math.min(target.minMs, source.minMs);
+  target.maxMs = Math.max(target.maxMs, source.maxMs);
 }
 
-export function recordHistogram(name: string, value: number): void {
-  if (!Number.isFinite(value)) return; // drop NaN/Infinity/invalid samples
-  let buf = histograms.get(name);
-  if (!buf) {
-    if (histograms.size >= MAX_METRIC_KEYS) return; // cap key count
-    buf = createRingBuffer(MAX_HISTOGRAM_SIZE);
-    histograms.set(name, buf);
-  }
-  ringPush(buf, value);
+function emptyAgg(): MetricsLatencyAgg {
+  return { count: 0, sumMs: 0, minMs: Infinity, maxMs: 0 };
 }
 
-export function getMetrics(): {
-  counters: Record<string, number>;
-  histograms: Record<
-    string,
-    { count: number; p50: number; p95: number; p99: number; avg: number }
-  >;
-} {
-  const result: ReturnType<typeof getMetrics> = {
-    counters: {},
-    histograms: {},
+function snapshotAgg(agg: MetricsLatencyAgg) {
+  return {
+    count: agg.count,
+    avg: Math.round(agg.sumMs / agg.count),
+    min: agg.minMs,
+    max: agg.maxMs,
   };
-  for (const [k, v] of counters) result.counters[k] = v;
-  for (const [k, buf] of histograms) {
-    if (buf.size === 0) continue;
-    const values = ringValues(buf);
-    const sorted = [...values].sort((a, b) => a - b);
-    const len = sorted.length;
-    result.histograms[k] = {
-      count: len,
-      p50: sorted[Math.floor(len * 0.5)],
-      p95: sorted[Math.floor(len * 0.95)],
-      p99: sorted[Math.floor(len * 0.99)],
-      avg: Math.round(values.reduce((a, b) => a + b, 0) / len),
-    };
+}
+
+function buildSnapshot(
+  grains: MetricsGrain[],
+  counters: Record<string, number>,
+): MetricsSnapshot {
+  const responseLatency = emptyAgg();
+  const toolCallsPerTurn = emptyAgg();
+  const apiCallsPerTurn = emptyAgg();
+  const cacheHitPercent = emptyAgg();
+  const backendLatency = new Map<string, MetricsLatencyAgg>();
+
+  for (const grain of grains) {
+    const c = grain.counters;
+    addCounter(counters, "queries_total", c.queries);
+    addCounter(counters, "turns_with_tools_total", c.turnsWithTools);
+    addCounter(counters, "api_calls_total", c.apiCalls);
+    addCounter(counters, "tokens.input_total", c.inputTokens);
+    addCounter(counters, "tokens.output_total", c.outputTokens);
+    addCounter(counters, "tokens.cache_read_total", c.cacheReadTokens);
+    addCounter(counters, "tokens.cache_write_total", c.cacheWriteTokens);
+    addCounter(
+      counters,
+      "scratchpad.trailing_text_dropped",
+      c.trailingTextDropped,
+    );
+    addCounter(
+      counters,
+      "scratchpad.flow_violation_retried",
+      c.flowViolationRetries,
+    );
+    addCounter(
+      counters,
+      "scratchpad.flow_violation_cap_exhausted",
+      c.flowViolationCapExhausted,
+    );
+    for (const [name, count] of Object.entries(grain.toolCallsByName)) {
+      addCounter(counters, `tool_calls.${name}`, count);
+    }
+    for (const [backend, bc] of Object.entries(grain.backend)) {
+      addCounter(counters, `backend.${backend}.queries`, bc.queries);
+      addCounter(counters, `backend.${backend}.tool_calls`, bc.toolCalls);
+      addCounter(counters, `backend.${backend}.turn_failed`, bc.failedTurns);
+      addCounter(counters, `backend.${backend}.tokens.input`, bc.inputTokens);
+      addCounter(counters, `backend.${backend}.tokens.output`, bc.outputTokens);
+      addCounter(
+        counters,
+        `backend.${backend}.tokens.cache_read`,
+        bc.cacheReadTokens,
+      );
+      addCounter(
+        counters,
+        `backend.${backend}.tokens.cache_write`,
+        bc.cacheWriteTokens,
+      );
+      const agg = backendLatency.get(backend) ?? emptyAgg();
+      mergeAgg(agg, bc.latency);
+      backendLatency.set(backend, agg);
+    }
+    mergeAgg(responseLatency, grain.latency);
+    mergeAgg(toolCallsPerTurn, grain.toolCallsPerTurn);
+    mergeAgg(apiCallsPerTurn, grain.apiCallsPerTurn);
+    mergeAgg(cacheHitPercent, grain.cacheHitPercent);
+  }
+
+  const histograms: MetricsSnapshot["histograms"] = {};
+  if (responseLatency.count)
+    histograms.response_latency_ms = snapshotAgg(responseLatency);
+  if (toolCallsPerTurn.count)
+    histograms.tool_calls_per_turn = snapshotAgg(toolCallsPerTurn);
+  if (apiCallsPerTurn.count)
+    histograms.api_calls_per_turn = snapshotAgg(apiCallsPerTurn);
+  if (cacheHitPercent.count)
+    histograms.cache_hit_percent = snapshotAgg(cacheHitPercent);
+  for (const [backend, agg] of backendLatency) {
+    if (agg.count)
+      histograms[`backend.${backend}.response_latency_ms`] = snapshotAgg(agg);
   }
-  return result;
+
+  return { counters, histograms };
+}
+
+/** Lifetime fleet snapshot: all sessions' cumulative metrics plus the
+ * in-process legacy counters. */
+export function getMetrics(): MetricsSnapshot {
+  const counters: Record<string, number> = {};
+  for (const [key, value] of legacyCounters) addCounter(counters, key, value);
+  return buildSnapshot(
+    getAllSessions().map(({ info }) => info.metrics.lifetime),
+    counters,
+  );
+}
+
+/** Today's (UTC) fleet snapshot, aggregated from the sessions' daily
+ * rollup buckets. Legacy counters are process-lifetime, not daily, so
+ * they are excluded here. */
+export function getTodayMetrics(): MetricsSnapshot {
+  const day = todayUtc();
+  return buildSnapshot(
+    getAllSessions().flatMap(({ info }) => info.metrics.buckets[day] ?? []),
+    {},
+  );
 }
 
 export function resetMetrics(): void {
-  counters.clear();
-  histograms.clear();
+  legacyCounters.clear();
+  resetAllSessionMetrics();
 }