Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
4.7 KB
Raw Blame
import { Counter, Gauge, type Registry, register } from 'prom-client'

/** Terminal disposition of one `bootstrapUserCatalog` run. */
type RunOutcome = 'noop' | 'admitted' | 'partial' | 'timed_out' | 'skipped' | 'error'
/** Per-coordinate probe disposition (the §6.3 buckets, plus the answer). */
type ProbeResult =
  | 'present'
  | 'absent'
  | 'unknown'
  | 'cached_absent'
  | 'cached_failed'
  | 'budget'
  | 'paused'
type Partition = 'per-user' | 'shared'
// 'stale' is declared for completeness but stays 0 today: the admission layer
// resolves a superseded/fenced attempt as ok (per-user) or throws (shared), so
// the bootstrap never labels an outcome 'stale'. Kept as a materialized-zero
// series so the label exists if that bookkeeping is ever surfaced.
type AdmissionOutcome = 'ok' | 'failed' | 'stale'

/** Probe dispositions counted for one run; omitted/zero keys are not incremented. */
export type ProbeResultCounts = Partial<Record<ProbeResult, number>>

export interface McpCatalogBootstrapMetricsPort {
  runFinished(outcome: RunOutcome, waitedMs: number): void
  probes(counts: ProbeResultCounts): void
  admission(partition: Partition, outcome: AdmissionOutcome): void
  awaitingGrant(size: number): void
}

function counter<Label extends string>(
  registry: Registry,
  options: { name: string; help: string; labelNames?: Label[] }
): Counter<Label> {
  const existing = registry.getSingleMetric(options.name)
  if (existing) return existing as Counter<Label>
  return new Counter<Label>({ ...options, registers: [registry] })
}

function gauge<Label extends string>(
  registry: Registry,
  options: { name: string; help: string; labelNames?: Label[] }
): Gauge<Label> {
  const existing = registry.getSingleMetric(options.name)
  if (existing) return existing as Gauge<Label>
  return new Gauge<Label>({ ...options, registers: [registry] })
}

const RUN_OUTCOMES: RunOutcome[] = ['noop', 'admitted', 'partial', 'timed_out', 'skipped', 'error']
const PROBE_RESULTS: ProbeResult[] = [
  'present',
  'absent',
  'unknown',
  'cached_absent',
  'cached_failed',
  'budget',
  'paused',
]
const PARTITIONS: Partition[] = ['per-user', 'shared']
const ADMISSION_OUTCOMES: AdmissionOutcome[] = ['ok', 'failed', 'stale']

export class McpCatalogBootstrapMetrics implements McpCatalogBootstrapMetricsPort {
  private readonly runs: Counter<'outcome'>
  private readonly probesTotal: Counter<'result'>
  private readonly admissions: Counter<'partition' | 'outcome'>
  private readonly waitMs: Gauge
  private readonly awaiting: Gauge

  constructor(registry: Registry = register) {
    this.runs = counter(registry, {
      name: 'clerum_mcp_catalog_bootstrap_runs_total',
      help: 'Per-turn catalog bootstrap runs by terminal outcome.',
      labelNames: ['outcome'],
    })
    this.probesTotal = counter(registry, {
      name: 'clerum_mcp_catalog_bootstrap_probes_total',
      help: 'Grant-existence probe coordinates by disposition (answer or skip bucket).',
      labelNames: ['result'],
    })
    this.admissions = counter(registry, {
      name: 'clerum_mcp_catalog_bootstrap_admissions_total',
      help: 'Bootstrap-initiated partition admissions by partition kind and outcome.',
      labelNames: ['partition', 'outcome'],
    })
    this.waitMs = gauge(registry, {
      name: 'clerum_mcp_catalog_bootstrap_wait_ms',
      help: 'Time the most recent bootstrap run waited on its admissions before continuing.',
    })
    this.awaiting = gauge(registry, {
      name: 'clerum_mcp_oauth_shared_awaiting_grant',
      help: 'SHARED oauth-context servers currently registered without a confirmed grant.',
    })
    this.initializeSeries()
  }

  /**
   * Materialize every counter series at zero so a scrape distinguishes "none"
   * from "not exported" — the same contract the status-heartbeat metrics keep
   * so an alert on, say, `result="paused"` reads a real zero, not a gap.
   */
  private initializeSeries(): void {
    for (const outcome of RUN_OUTCOMES) this.runs.inc({ outcome }, 0)
    for (const result of PROBE_RESULTS) this.probesTotal.inc({ result }, 0)
    for (const partition of PARTITIONS)
      for (const outcome of ADMISSION_OUTCOMES) this.admissions.inc({ partition, outcome }, 0)
    this.awaiting.set(0)
  }

  runFinished(outcome: RunOutcome, waitedMs: number): void {
    this.runs.inc({ outcome })
    this.waitMs.set(waitedMs)
  }

  probes(counts: ProbeResultCounts): void {
    for (const result of PROBE_RESULTS) {
      const n = counts[result]
      if (n && n > 0) this.probesTotal.inc({ result }, n)
    }
  }

  admission(partition: Partition, outcome: AdmissionOutcome): void {
    this.admissions.inc({ partition, outcome })
  }

  awaitingGrant(size: number): void {
    this.awaiting.set(size)
  }
}

export const catalogBootstrapMetrics = new McpCatalogBootstrapMetrics()