@cartanova/qgrid-cli 2.4.4 → 2.4.6

package/bundle/src/application/monit/log-buffer.test.ts

@@ -0,0 +1,121 @@
+import { type LogRecord } from "@logtape/logtape";
+import { describe, expect, it } from "vitest";
+
+import { MonitLogBuffer } from "./log-buffer";
+
+function record(partial: Partial<LogRecord> & { message?: readonly unknown[] }): LogRecord {
+  return {
+    category: ["qgrid"],
+    level: "info",
+    message: ["hello"],
+    rawMessage: "hello",
+    timestamp: 1_000,
+    properties: {},
+    ...partial,
+  } as LogRecord;
+}
+
+describe("MonitLogBuffer", () => {
+  it("flattens interleaved template parts and renders non-string values", () => {
+    const buffer = new MonitLogBuffer();
+    buffer.push(
+      record({ message: ["worker ", 3, " ready in ", { ms: 120 }, ""], timestamp: 42 }),
+    );
+
+    const { entries } = buffer.after(undefined, 10);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      seq: 1,
+      timestamp: 42,
+      level: "info",
+      category: ["qgrid"],
+      text: 'worker 3 ready in {"ms":120}',
+    });
+  });
+
+  it("truncates oversized messages and marks the cut", () => {
+    const buffer = new MonitLogBuffer(10, 100);
+    buffer.push(record({ message: ["x".repeat(500)] }));
+
+    const [entry] = buffer.after(undefined, 1).entries;
+    expect(entry!.text).toHaveLength(101);
+    expect(entry!.text.endsWith("…")).toBe(true);
+  });
+
+  it("evicts oldest entries past capacity while seq stays monotonic", () => {
+    const buffer = new MonitLogBuffer(3);
+    for (let i = 1; i <= 5; i++) buffer.push(record({ message: [`line ${i}`] }));
+
+    expect(buffer.oldestSeq).toBe(3);
+    expect(buffer.latestSeq).toBe(5);
+    const { entries } = buffer.after(undefined, 10);
+    expect(entries.map((entry) => entry.seq)).toEqual([3, 4, 5]);
+    expect(entries.map((entry) => entry.text)).toEqual(["line 3", "line 4", "line 5"]);
+  });
+
+  it("returns the tail up to limit when no cursor is given", () => {
+    const buffer = new MonitLogBuffer();
+    for (let i = 1; i <= 5; i++) buffer.push(record({ message: [`line ${i}`] }));
+
+    const chunk = buffer.after(undefined, 2);
+    expect(chunk.entries.map((entry) => entry.seq)).toEqual([4, 5]);
+    expect(chunk.nextCursor).toBe(5);
+    expect(chunk.dropped).toBe(0);
+  });
+
+  it("returns only entries newer than the cursor with no boundary duplicates", () => {
+    const buffer = new MonitLogBuffer();
+    for (let i = 1; i <= 5; i++) buffer.push(record({ message: [`line ${i}`] }));
+
+    const chunk = buffer.after(2, 10);
+    expect(chunk.entries.map((entry) => entry.seq)).toEqual([3, 4, 5]);
+    expect(chunk.nextCursor).toBe(5);
+    expect(chunk.dropped).toBe(0);
+  });
+
+  it("signals dropped lines when the cursor fell behind eviction", () => {
+    const buffer = new MonitLogBuffer(3);
+    for (let i = 1; i <= 6; i++) buffer.push(record({ message: [`line ${i}`] }));
+
+    // oldest 는 seq 4 — 커서 1 은 seq 2,3 을 유실했다.
+    const chunk = buffer.after(1, 10);
+    expect(chunk.dropped).toBe(2);
+    expect(chunk.entries.map((entry) => entry.seq)).toEqual([4, 5, 6]);
+    expect(chunk.nextCursor).toBe(6);
+  });
+
+  it("resyncs a future cursor from a previous process to the current tail", () => {
+    const buffer = new MonitLogBuffer();
+    buffer.push(record({}));
+
+    const chunk = buffer.after(999, 10);
+    expect(chunk.entries).toEqual([]);
+    expect(chunk.nextCursor).toBe(buffer.latestSeq);
+    expect(chunk.dropped).toBe(0);
+  });
+
+  it("handles an empty buffer without crashing", () => {
+    const buffer = new MonitLogBuffer();
+    const chunk = buffer.after(undefined, 10);
+    expect(chunk).toEqual({ entries: [], nextCursor: 0, dropped: 0 });
+  });
+
+  it("keeps processStartedAt fixed across buffer churn (AE1 server half)", () => {
+    const buffer = new MonitLogBuffer(2);
+    const startedAt = buffer.processStartedAt;
+    for (let i = 0; i < 10; i++) buffer.push(record({}));
+    expect(buffer.processStartedAt).toBe(startedAt);
+  });
+
+  it("never throws on malformed records", () => {
+    const buffer = new MonitLogBuffer();
+    expect(() =>
+      buffer.push(record({ message: undefined as unknown as readonly unknown[] })),
+    ).not.toThrow();
+    const cyclic: Record<string, unknown> = {};
+    cyclic.self = cyclic;
+    expect(() => buffer.push(record({ message: ["cyclic ", cyclic, ""] }))).not.toThrow();
+    const { entries } = buffer.after(undefined, 10);
+    expect(entries.at(-1)?.text.startsWith("cyclic ")).toBe(true);
+  });
+});

package/bundle/src/application/monit/log-buffer.ts

@@ -0,0 +1,121 @@
+/**
+ * Monit 로그 ring buffer — 프로세스 생존 기간 동안 최근 로그를 구조화 레코드로 보관한다.
+ *
+ * 콘솔 sink 와 병렬로 등록되는 두 번째 logtape sink 가 이 버퍼를 채우고,
+ * monit.frame 이 커서 기반으로 읽어 대시보드 Monit 탭에 제공한다.
+ * 재시작하면 리셋된다 — 영속 기록은 request_log 의 몫.
+ *
+ * timestamp/processStartedAt 은 epoch ms 숫자로 유지한다. web 의 전역 dateReviver 가
+ * ISO 문자열을 Date 로 바꿔버리므로, 숫자만이 재시작 감지의 동등성 비교를 보존한다.
+ */
+import { type LogRecord, type Sink } from "@logtape/logtape";
+
+const DEFAULT_CAPACITY = 2_000;
+const DEFAULT_MAX_TEXT_LENGTH = 4_000;
+
+// 표시 전용 wire 레코드. properties/원본 값은 버퍼에 싣지 않는다(allowlist).
+export interface MonitLogEntry {
+  seq: number;
+  timestamp: number;
+  level: string;
+  category: string[];
+  text: string;
+}
+
+export interface MonitLogChunk {
+  entries: MonitLogEntry[];
+  nextCursor: number;
+  // 호출자의 커서가 eviction 에 밀려 유실된 라인 수. 0 이면 공백 없음.
+  dropped: number;
+}
+
+// logtape message 배열은 홀수 길이 — 짝수 인덱스가 템플릿 텍스트, 홀수가 보간 값.
+function flattenMessage(message: readonly unknown[]): string {
+  return message
+    .map((part, index) => (index % 2 === 0 ? String(part ?? "") : renderValue(part)))
+    .join("");
+}
+
+function renderValue(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value instanceof Error) return value.message;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+export class MonitLogBuffer {
+  readonly processStartedAt = Date.now();
+  private entries: MonitLogEntry[] = [];
+  private nextSeq = 1;
+
+  constructor(
+    private readonly capacity = DEFAULT_CAPACITY,
+    private readonly maxTextLength = DEFAULT_MAX_TEXT_LENGTH,
+  ) {}
+
+  // logtape sink 본체. logtape 가 sink 오류를 격리하지만, 버퍼 버그가
+  // meta logger 소음을 만들지 않도록 방어적으로 한 번 더 감싼다.
+  push(record: LogRecord): void {
+    try {
+      let text = flattenMessage(record.message);
+      if (text.length > this.maxTextLength) {
+        text = `${text.slice(0, this.maxTextLength)}…`;
+      }
+      this.entries.push({
+        seq: this.nextSeq++,
+        timestamp: record.timestamp,
+        level: record.level,
+        category: [...record.category],
+        text,
+      });
+      if (this.entries.length > this.capacity) {
+        this.entries.splice(0, this.entries.length - this.capacity);
+      }
+    } catch {
+      // 로그 캡처 실패는 조용히 무시 — 로깅 경로를 절대 방해하지 않는다.
+    }
+  }
+
+  get oldestSeq(): number {
+    return this.entries[0]?.seq ?? this.nextSeq;
+  }
+
+  get latestSeq(): number {
+    return this.nextSeq - 1;
+  }
+
+  // cursor 이후의 엔트리를 최대 limit 개 반환한다. cursor 미지정이면 tail.
+  after(cursor: number | undefined, limit: number): MonitLogChunk {
+    if (cursor === undefined) {
+      const entries = this.entries.slice(-limit);
+      return {
+        entries,
+        nextCursor: entries.at(-1)?.seq ?? this.latestSeq,
+        dropped: 0,
+      };
+    }
+
+    // 이전 프로세스의 커서 등 미래 커서는 방어적으로 현재 tail 로 재동기화한다.
+    if (cursor > this.latestSeq) {
+      return { entries: [], nextCursor: this.latestSeq, dropped: 0 };
+    }
+
+    const dropped = Math.max(this.oldestSeq - cursor - 1, 0);
+    const startIndex = this.entries.findIndex((entry) => entry.seq > cursor);
+    const entries = startIndex === -1 ? [] : this.entries.slice(startIndex, startIndex + limit);
+    return {
+      entries,
+      nextCursor: entries.at(-1)?.seq ?? cursor + dropped,
+      dropped,
+    };
+  }
+}
+
+export const monitLogBuffer = new MonitLogBuffer();
+
+export const monitLogSink: Sink = (record) => {
+  monitLogBuffer.push(record);
+};

package/bundle/src/application/monit/monit.frame.test.ts

@@ -0,0 +1,176 @@
+import { type LogRecord } from "@logtape/logtape";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const requestLogSaveMock = vi.hoisted(() => vi.fn());
+vi.mock("../request-log/request-log.model", () => ({
+  RequestLogModel: { save: requestLogSaveMock, createRun: requestLogSaveMock },
+  MICRO_USD: 1_000_000,
+}));
+
+import { QgridDispatcher } from "../qgrid/qgrid.dispatcher";
+import { monitLogBuffer } from "./log-buffer";
+import { MonitFrame } from "./monit.frame";
+
+function push(text: string, extra: Partial<LogRecord> = {}): void {
+  monitLogBuffer.push({
+    category: ["qgrid"],
+    level: "info",
+    message: [text],
+    rawMessage: text,
+    timestamp: 1_000,
+    properties: {},
+    ...extra,
+  } as LogRecord);
+}
+
+describe("MonitFrame.monitLogs", () => {
+  beforeEach(() => {
+    requestLogSaveMock.mockReset();
+    vi.restoreAllMocks();
+  });
+
+  it("returns the tail with a usable nextCursor when no cursor is given", async () => {
+    push("first line");
+    push("second line");
+
+    const chunk = await MonitFrame.monitLogs();
+    expect(chunk.processStartedAt).toBe(monitLogBuffer.processStartedAt);
+    expect(chunk.dropped).toBe(0);
+    expect(chunk.nextCursor).toBe(monitLogBuffer.latestSeq);
+    expect(chunk.entries.at(-1)?.text).toBe("second line");
+  });
+
+  it("returns only entries newer than the cursor with no boundary duplicates", async () => {
+    const baseline = monitLogBuffer.latestSeq;
+    push("after baseline 1");
+    push("after baseline 2");
+
+    const chunk = await MonitFrame.monitLogs(baseline);
+    expect(chunk.entries.map((entry) => entry.text)).toEqual([
+      "after baseline 1",
+      "after baseline 2",
+    ]);
+    expect(chunk.nextCursor).toBe(monitLogBuffer.latestSeq);
+
+    const followUp = await MonitFrame.monitLogs(chunk.nextCursor);
+    expect(followUp.entries).toEqual([]);
+  });
+
+  it("surfaces dropped counts from the buffer (AE4 server half)", async () => {
+    const after = vi.spyOn(monitLogBuffer, "after").mockReturnValue({
+      entries: [],
+      nextCursor: 10,
+      dropped: 3,
+    });
+
+    const chunk = await MonitFrame.monitLogs(1);
+    expect(after).toHaveBeenCalledWith(1, 1_000);
+    expect(chunk.dropped).toBe(3);
+  });
+
+  it("handles an empty buffer without crashing", async () => {
+    vi.spyOn(monitLogBuffer, "after").mockReturnValue({
+      entries: [],
+      nextCursor: 0,
+      dropped: 0,
+    });
+
+    await expect(MonitFrame.monitLogs()).resolves.toMatchObject({
+      entries: [],
+      nextCursor: 0,
+      dropped: 0,
+    });
+  });
+
+  it("ships only allowlisted DTO fields — the text channel is the live path", async () => {
+    // 실제 유출 채널 검증: 템플릿 리터럴 로깅에서 secret 은 보간 값으로 text 에 실린다.
+    // properties 는 wire 를 절대 건너지 않는다.
+    push("token refresh failed: ", {
+      message: ["token refresh failed: ", "sk-interpolated-credential", ""],
+      properties: { accessToken: "forbidden-property-secret", refreshToken: "also-forbidden" },
+    });
+
+    const chunk = await MonitFrame.monitLogs(monitLogBuffer.latestSeq - 1);
+    const serialized = JSON.stringify(chunk);
+    expect(serialized).not.toContain("forbidden-property-secret");
+    expect(serialized).not.toContain("also-forbidden");
+    expect(serialized).not.toContain("properties");
+    // text 채널은 보간 값을 그대로 실어 나른다 — 이것이 실제 노출 경로임을 문서화한다.
+    expect(chunk.entries.at(-1)?.text).toBe("token refresh failed: sk-interpolated-credential");
+    expect(Object.keys(chunk.entries.at(-1)!).toSorted()).toEqual([
+      "category",
+      "level",
+      "seq",
+      "text",
+      "timestamp",
+    ]);
+  });
+
+  it("writes no request logs", async () => {
+    push("a line");
+    await MonitFrame.monitLogs();
+    expect(requestLogSaveMock).not.toHaveBeenCalled();
+  });
+
+  it("piggybacks live vitals on every chunk, zeroed before dispatchers boot", async () => {
+    QgridDispatcher.openaiDispatcher = {
+      workerCount: 25,
+      readyWorkerCount: 24,
+      queueLength: 3,
+      workerCountsByToken: [
+        { name: "openai/haze", count: 12 },
+        { name: "openai/nk", count: 13 },
+      ],
+    } as never;
+    QgridDispatcher.anthropicDispatcher = {
+      tokenCount: 8,
+      tokenNames: ["anthropic/haze", "anthropic/noa"],
+    } as never;
+    try {
+      const chunk = await MonitFrame.monitLogs();
+      expect(chunk.vitals).toEqual({
+        openaiWorkerCount: 25,
+        openaiReadyWorkerCount: 24,
+        openaiQueueLength: 3,
+        openaiWorkersByToken: [
+          { name: "openai/haze", count: 12 },
+          { name: "openai/nk", count: 13 },
+        ],
+        anthropicTokenCount: 8,
+        anthropicTokenNames: ["anthropic/haze", "anthropic/noa"],
+      });
+    } finally {
+      QgridDispatcher.openaiDispatcher = null;
+      QgridDispatcher.anthropicDispatcher = null;
+    }
+
+    const empty = await MonitFrame.monitLogs();
+    expect(empty.vitals.openaiWorkerCount).toBe(0);
+    expect(empty.vitals.openaiWorkersByToken).toEqual([]);
+    expect(empty.vitals.anthropicTokenCount).toBe(0);
+    expect(empty.vitals.anthropicTokenNames).toEqual([]);
+  });
+});
+
+describe("MonitFrame.monitInfo", () => {
+  it("returns the active DB connection, server url, and pool bounds without secrets", async () => {
+    vi.stubEnv("HOST", "0.0.0.0");
+    vi.stubEnv("PORT", "45000");
+    vi.stubEnv("QGRID_DB_HOST", "db.internal");
+    vi.stubEnv("QGRID_DB_NAME", "qgrid_dev");
+
+    // 단위 테스트에선 DB 미초기화 → env 폴백 경로. 부팅된 서버에선 활성 knex 설정을 읽는다
+    // (dev 서버의 통합 테스트 러너가 env 를 오염시키는 문제 회피 — curl 로 별도 검증).
+    const info = await MonitFrame.monitInfo();
+    expect(info.serverUrl).toBe("http://0.0.0.0:45000");
+    expect(info.dbHost).toBe("db.internal");
+    expect(info.dbName).toBe("qgrid_dev");
+    expect(info.openai.minWorkersPerToken).toBeGreaterThan(0);
+    expect(info.openai.maxWorkersPerToken).toBeGreaterThanOrEqual(info.openai.minWorkersPerToken);
+    // allowlist — 연결 객체의 password/user 등은 절대 실리지 않는다.
+    expect(Object.keys(info).toSorted()).toEqual(["dbHost", "dbName", "openai", "serverUrl"]);
+    expect(JSON.stringify(info)).not.toContain("password");
+
+    vi.unstubAllEnvs();
+  });
+});

package/bundle/src/application/monit/monit.frame.ts

@@ -0,0 +1,77 @@
+/**
+ * Monit — 대시보드 Monit 탭용 프로세스 로그 관측 API.
+ *
+ * 읽기 전용. ring buffer 를 얇게 직접 읽으며(범용 쿼리 기계 없이),
+ * request log 를 남기지 않는다. 접근 경계는 다른 대시보드 API 와 동일하다.
+ */
+import { api, BaseFrameClass, DB } from "sonamu";
+
+import { resolveOpenAIWorkerPoolConfig } from "../../utils/providers/openai/openai-dispatcher";
+import { QgridDispatcher } from "../qgrid/qgrid.dispatcher";
+import { monitLogBuffer } from "./log-buffer";
+import { type MonitLogChunk, type MonitServerInfo, type MonitVitals } from "./monit.types";
+
+// 응답당 엔트리 상한 — 폴링 클라이언트는 다음 폴에서 이어서 따라잡는다.
+const RESPONSE_ENTRY_LIMIT = 1_000;
+
+class MonitFrameClass extends BaseFrameClass {
+  constructor() {
+    super("Monit");
+  }
+
+  @api({ httpMethod: "GET", clients: ["axios", "tanstack-query"] })
+  async monitLogs(cursor?: number): Promise<MonitLogChunk> {
+    return {
+      processStartedAt: monitLogBuffer.processStartedAt,
+      ...monitLogBuffer.after(cursor, RESPONSE_ENTRY_LIMIT),
+      vitals: currentVitals(),
+    };
+  }
+
+  // 프로세스 정적 정보 — 폴링 불필요, 페이지당 1회 조회.
+  @api({ httpMethod: "GET", clients: ["axios", "tanstack-query"] })
+  async monitInfo(): Promise<MonitServerInfo> {
+    const pool = resolveOpenAIWorkerPoolConfig();
+    const host = process.env.HOST ?? "localhost";
+    const port = process.env.PORT ?? "44900";
+    const conn = activeDbConnection();
+    return {
+      serverUrl: `http://${host}:${port}`,
+      dbHost: conn.host ?? "localhost",
+      dbName: conn.database ?? "qgrid",
+      openai: {
+        minWorkersPerToken: pool.minWorkersPerToken,
+        maxWorkersPerToken: pool.maxWorkersPerToken,
+        autoscale: pool.autoscale,
+      },
+    };
+  }
+}
+
+// dispatcher 미초기화(부팅 직후) 시 0 으로 응답한다 — 가벼운 스냅샷이라 오류로 만들지 않는다.
+function currentVitals(): MonitVitals {
+  return {
+    openaiWorkerCount: QgridDispatcher.openaiDispatcher?.workerCount ?? 0,
+    openaiReadyWorkerCount: QgridDispatcher.openaiDispatcher?.readyWorkerCount ?? 0,
+    openaiQueueLength: QgridDispatcher.openaiDispatcher?.queueLength ?? 0,
+    openaiWorkersByToken: QgridDispatcher.openaiDispatcher?.workerCountsByToken ?? [],
+    anthropicTokenCount: QgridDispatcher.anthropicDispatcher?.tokenCount ?? 0,
+    anthropicTokenNames: QgridDispatcher.anthropicDispatcher?.tokenNames ?? [],
+  };
+}
+
+// 실제 활성 knex 연결에서 읽는다 — dev 서버의 통합 테스트 러너가 process.env.QGRID_DB_NAME 을
+// 테스트 DB 이름으로 덮어쓰므로 env 는 신뢰할 수 없다. DB 미초기화(부팅 전) 시에만 env 폴백.
+function activeDbConnection(): { host?: string; database?: string } {
+  try {
+    const connection = DB.getDBConfig("w").connection;
+    if (typeof connection === "object" && connection !== null) {
+      return connection as { host?: string; database?: string };
+    }
+  } catch {
+    // DB config 미초기화 — env 폴백으로 진행
+  }
+  return { host: process.env.QGRID_DB_HOST, database: process.env.QGRID_DB_NAME };
+}
+
+export const MonitFrame = new MonitFrameClass();

package/bundle/src/application/monit/monit.types.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+
+// ─── Monit (프로세스 로그 관측) ───
+//
+// timestamp/processStartedAt 은 epoch ms 숫자다. web 전역 dateReviver 가 ISO 문자열을
+// Date 로 변환하므로, 숫자만이 재시작 감지(processStartedAt 동등성)와 커서 비교를 보존한다.
+// 이 파일은 web 으로 그대로 sync 되므로 서버 전용 import 를 두지 않는다.
+
+export const MonitLogEntry = z.object({
+  seq: z.number(),
+  timestamp: z.number(),
+  level: z.string(),
+  category: z.array(z.string()),
+  text: z.string(),
+});
+export type MonitLogEntry = z.infer<typeof MonitLogEntry>;
+
+// 폴링에 편승하는 라이브 카운트 — 깊은 워커/큐 진단은 audit 대시보드(별도)의 몫이고,
+// 여기는 "지금 몇 개 돌고 큐가 쌓이나"만 가볍게 답한다.
+export const MonitVitals = z.object({
+  openaiWorkerCount: z.number(),
+  openaiReadyWorkerCount: z.number(),
+  openaiQueueLength: z.number(),
+  // 토큰별 현재 워커 수 — autoscale 로 늘고 주는 것을 토큰 단위로 본다
+  openaiWorkersByToken: z.array(z.object({ name: z.string(), count: z.number() })),
+  anthropicTokenCount: z.number(),
+  // fresh-spawn 이라 워커 수는 없다 — 풀에 어떤 토큰이 있는지만 보여준다
+  anthropicTokenNames: z.array(z.string()),
+});
+export type MonitVitals = z.infer<typeof MonitVitals>;
+
+export const MonitLogChunk = z.object({
+  processStartedAt: z.number(),
+  entries: z.array(MonitLogEntry),
+  nextCursor: z.number(),
+  // 호출자의 커서가 buffer eviction 에 밀려 유실된 라인 수
+  dropped: z.number(),
+  vitals: MonitVitals,
+});
+export type MonitLogChunk = z.infer<typeof MonitLogChunk>;
+
+// 프로세스 단위 정적 환경 정보 — 어느 서버/DB 를 보고 있는지 한눈에 확인하는 용도.
+// 비밀값(DB 비밀번호, 토큰)은 절대 싣지 않는다.
+export const MonitServerInfo = z.object({
+  serverUrl: z.string(),
+  dbHost: z.string(),
+  dbName: z.string(),
+  openai: z.object({
+    minWorkersPerToken: z.number(),
+    maxWorkersPerToken: z.number(),
+    autoscale: z.boolean(),
+  }),
+});
+export type MonitServerInfo = z.infer<typeof MonitServerInfo>;

package/bundle/src/application/qgrid/qgrid.frame.test.ts

@@ -305,4 +305,28 @@ describe("QgridFrame.usage", () => {
     });
     expect(getRateLimitsByTokenIdMock).not.toHaveBeenCalled();
   });
+
+  it("returns the provider-reported OpenAI window duration", async () => {
+    findManyMock.mockResolvedValueOnce({
+      rows: [{ ...tokenEntry, provider: "openai", active: true }],
+    });
+    getRateLimitsByTokenIdMock.mockResolvedValueOnce({
+      data: {
+        rateLimits: {
+          primary: { usedPercent: 11, resetsAt: 1_784_000_000, windowDurationMins: 10_080 },
+          secondary: null,
+        },
+      },
+    });
+
+    await expect(QgridFrame.usage(1)).resolves.toEqual({
+      provider: "openai",
+      fiveHour: {
+        utilization: 11,
+        resetsAt: new Date(1_784_000_000 * 1_000).toISOString(),
+        windowDurationMins: 10_080,
+      },
+      sevenDay: null,
+    });
+  });
 });

package/bundle/src/application/qgrid/qgrid.frame.ts

@@ -583,12 +583,14 @@ class QgridFrameClass extends BaseFrameClass {
             ? {
                 utilization: rl.primary.usedPercent,
                 resetsAt: unixSecondsToIso(rl.primary.resetsAt),
+                windowDurationMins: rl.primary.windowDurationMins,
               }
             : null,
           sevenDay: rl?.secondary
             ? {
                 utilization: rl.secondary.usedPercent,
                 resetsAt: unixSecondsToIso(rl.secondary.resetsAt),
+                windowDurationMins: rl.secondary.windowDurationMins,
               }
             : null,
         };

package/bundle/src/application/qgrid/qgrid.types.ts

@@ -256,6 +256,7 @@ const RateWindow = z
   .object({
     utilization: z.number().nullable(),
     resetsAt: z.string().nullable(),
+    windowDurationMins: z.number().nullable().optional(),
   })
   .nullable();
 

package/bundle/src/application/queries.generated.ts

@@ -92,3 +92,11 @@ export namespace QgridService {
   export const health = (): SSRQuery =>
     createSSRQuery("QgridFrame", "health", [], ["Qgrid", "health"]);
 }
+
+export namespace MonitService {
+  export const monitLogs = (cursor?: number): SSRQuery =>
+    createSSRQuery("MonitFrame", "monitLogs", [cursor], ["Monit", "monitLogs"]);
+
+  export const monitInfo = (): SSRQuery =>
+    createSSRQuery("MonitFrame", "monitInfo", [], ["Monit", "monitInfo"]);
+}

package/bundle/src/application/sonamu.generated.http

@@ -492,4 +492,16 @@ Content-Type: application/json
 
 GET {{baseUrl}}/api/qgrid/health
 	?
+Content-Type: application/json
+
+###
+
+GET {{baseUrl}}/api/monit/monitLogs
+	?cursor=0
+Content-Type: application/json
+
+###
+
+GET {{baseUrl}}/api/monit/monitInfo
+	?
 Content-Type: application/json

package/bundle/src/sonamu.config.ts

@@ -7,6 +7,7 @@ import dotenv from "dotenv";
 import { CachePresets, defineConfig } from "sonamu";
 import { drivers as cacheDrivers, store } from "sonamu/cache";
 
+import { monitLogSink } from "./application/monit/log-buffer";
 import { QgridDispatcher } from "./application/qgrid/qgrid.dispatcher";
 import { QgridFrame } from "./application/qgrid/qgrid.frame";
 import { TokenSubscriber } from "./application/qgrid/token-subscriber";
@@ -81,12 +82,14 @@ export default defineConfig({
           categoryTruncate: "middle",
         }),
       }),
+      // Monit 탭용 in-memory ring buffer. 포맷은 sink 별 — 콘솔 출력은 그대로다.
+      monit: monitLogSink,
     },
     loggers: [
       // qgrid 로그 (요청 분배, oauth/usage API)
-      { category: ["qgrid"], sinks: ["console"], lowestLevel: "info" },
+      { category: ["qgrid"], sinks: ["console", "monit"], lowestLevel: "info" },
       // sonamu 로그는 warning 이상만
-      { category: ["sonamu"], sinks: ["console"], lowestLevel: "warning" },
+      { category: ["sonamu"], sinks: ["console", "monit"], lowestLevel: "warning" },
       // fastify 로그 차단
       { category: ["fastify"], sinks: [], lowestLevel: "fatal" },
     ],

package/bundle/src/utils/providers/anthropic/anthropic-dispatcher.ts

@@ -92,6 +92,11 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     return this.tokenPool.size;
   }
 
+  // Monit 표시용 — 풀에 있는 토큰 이름 스냅샷 (이름순 정렬)
+  get tokenNames(): string[] {
+    return [...this.tokenPool.values()].map((token) => token.name).toSorted();
+  }
+
   // DB active anthropic 토큰 목록으로 풀을 재동기화한다(periodic reconcile/재연결용).
   // LISTEN/NOTIFY 가 끊긴 동안 유실된 추가/삭제/비활성화를 DB 기준으로 다시 맞춘다.
   // 이벤트 핸들러를 재사용해 풀 갱신이 일관되게 적용되도록 한다: