@things-factory/headless-twin 10.0.8 → 10.0.10

package/dist-server/engine/load-meter.d.ts

@@ -0,0 +1,181 @@
+/** 작업 이름 — 새 작업을 재기 시작하면 여기 늘린다(문자열을 자유롭게 쓰지 않는다: 오타가 새 칸이 된다). */
+export declare const LOAD_PHASES: readonly ["tick", "snapshot", "deltas", "publish", "journal", "ingest", "forecast", "forkTick"];
+export type LoadPhase = (typeof LOAD_PHASES)[number];
+export interface PhaseStats {
+    /** 잰 횟수. */
+    count: number;
+    /** 마지막 소요(ms). */
+    lastMs: number;
+    /** 가장 오래 걸린 것(ms) — 평균은 순간 정체를 가린다. */
+    maxMs: number;
+    /** 소요 합(ms). 나눗셈은 읽는 쪽에서 한다. */
+    totalMs: number;
+}
+/** 창(window) 하나의 누적 — "지금 얼마나 쓰고 있나" 를 답한다. */
+interface Window {
+    /** 창이 열린 시각. **아직 안 열렸으면 `-1`** — 0 으로 두면 시각 0 과 구별이 안 된다(검사가 잡았다). */
+    startMs: number;
+    phases: Partial<Record<LoadPhase, PhaseStats>>;
+}
+export interface LoadMeter {
+    /** **누적** — 프로세스가 뜬 뒤 전부. 총량과 최악값을 본다. */
+    phases: Partial<Record<LoadPhase, PhaseStats>>;
+    /** 지금 쌓고 있는 창. */
+    window: Window;
+    /** **마지막으로 닫힌 창** — 이것이 "실시간" 이다. 없으면 아직 한 창도 안 지났다. */
+    recent: (Window & {
+        endMs: number;
+    }) | null;
+    /** 이 트윈에서 만들어진 fork 수(누적) — 예측 한 번이 수십 개를 만든다. */
+    forksCreated: number;
+    /** 한 주기(틱)가 예산을 넘긴 횟수. */
+    overBudget: number;
+    /**
+     * 마지막 경고 시각(ms). **한 번도 안 했으면 `-Infinity`** — 0 으로 두면 "0 시점에 경고했다" 가 되어
+     * 첫 느린 틱이 조용히 지나간다(검사가 그것을 잡았다).
+     */
+    lastWarnMs: number;
+}
+export declare function newLoadMeter(): LoadMeter;
+/**
+ * 예산 — 틱 간격의 절반. 넘으면 루프의 절반을 이 트윈 하나가 쓰고 있다는 뜻이다.
+ *
+ * 절반인 이유: 트윈이 여럿이라 각자 간격을 다 쓰면 이미 포화다. 절반에서 알아야 손 쓸 틈이 있다.
+ */
+export declare const TICK_BUDGET_RATIO = 0.5;
+/** 경고를 다시 낼 때까지의 최소 간격(ms) — 느린 트윈은 매 틱 느리므로, 그대로 두면 로그가 원인을 덮는다. */
+export declare const WARN_COOLDOWN_MS = 30000;
+/**
+ * 한 작업의 소요를 기록한다. **누적만 하고 판단하지 않는다.**
+ *
+ * 음수·NaN 은 기록하지 않는다(시계가 뒤로 간 경우). 없는 값을 0 으로 세면 평균이 거짓이 된다.
+ */
+export declare function recordPhase(meter: LoadMeter, phase: LoadPhase, tookMs: number, nowMs?: number): void;
+/** fork 하나가 만들어졌다 — 예측 한 번이 수십 개를 만든다. 수를 알아야 부하의 출처를 짚는다. */
+export declare function recordFork(meter: LoadMeter, count?: number): void;
+/** 실시간 창의 길이(ms) — 이보다 길게 보려면 누적을 본다. */
+export declare const WINDOW_MS = 10000;
+/** 창이 다 찼으면 닫고 새로 연다. **닫힌 창만 "최근" 으로 읽는다** — 채우는 중인 창은 과소 집계다. */
+export declare function rollWindow(meter: LoadMeter, nowMs: number, windowMs?: number): void;
+/**
+ * 이 주기가 예산을 넘었나 — 넘었으면 세고, **말할 때인지**까지 답한다.
+ */
+export declare function judgeCycle(meter: LoadMeter, tookMs: number, tickMs: number, nowMs: number, budgetRatio?: number, cooldownMs?: number): {
+    over: boolean;
+    warn: boolean;
+    budgetMs: number;
+};
+export interface PhaseRow {
+    phase: LoadPhase;
+    count: number;
+    lastMs: number;
+    maxMs: number;
+    avgMs: number;
+    totalMs: number;
+    /** 잰 작업 전체 시간 중 이 작업의 몫(0~1). 어디를 고칠지 이 값이 정한다. */
+    share: number;
+}
+export interface LoadView {
+    phases: PhaseRow[];
+    measuredTotalMs: number;
+    /** 이 구간의 길이(ms). 누적은 프로세스 기동 이후라 알 수 없으므로 `null`. */
+    spanMs: number | null;
+    /** 구간 중 몇 %를 이 트윈이 썼나(0~1+). 구간을 모르면 `null` — **0 이 아니다.** */
+    busyRatio: number | null;
+}
+/**
+ * 읽기용 요약 — **실시간과 누적을 함께** 낸다.
+ *
+ *  · `recent` — 마지막으로 **닫힌** 창. 지금 이 트윈이 루프를 얼마나 쓰고 있나. 채우는 중인 창은
+ *    과소 집계라 쓰지 않는다.
+ *  · `total` — 기동 이후 전부. 총량과 최악값.
+ *
+ * 잰 적이 없으면 **`null` 이다.** 0 으로 채우면 "0ms 다"(= 아주 빠르다)로 읽혀, 재지 않은 것과 정반대의
+ * 뜻이 된다. 몫(`share`)도 잰 작업들 사이의 비율일 뿐 — **재지 않은 작업은 분모에 없다.**
+ */
+export declare function loadSummary(meter: LoadMeter | undefined, tickMs: number): {
+    recent: LoadView | null;
+    total: LoadView | null;
+    forksCreated: number;
+    overBudget: number;
+    budgetMs: number;
+    /** 마지막 틱이 간격을 얼마나 썼나(0~1+). 1 이면 간격을 통째로 쓴다. */
+    loadRatio: number | null;
+} | null;
+/**
+ * 경고 한 줄 — **무엇이 느린지까지 말한다.** "틱이 800ms" 만으로는 어디를 볼지 알 수 없다.
+ *
+ * 가장 무거운 작업 셋을 몫과 함께 적는다.
+ */
+export declare function slowTickMessage(instanceId: string, tookMs: number, budgetMs: number, meter: LoadMeter): string;
+/**
+ * 전체 한눈에 — **누가 루프를 점유하고 있나.**
+ *
+ * 인스턴스 목록을 받아 대수·모드별 수·fork 총수를 세고, **최근 창의 부하가 큰 순서**로 줄을 세운다.
+ * 누적이 아니라 최근으로 세우는 이유: 지금 아픈 것을 먼저 봐야 한다(누적 1위는 오래 떠 있던 것일 뿐일
+ * 수 있다).
+ */
+export declare function fleetLoad(rows: {
+    instanceId: string;
+    mode: string;
+    domainId?: string;
+    domainLabel?: string;
+    meter?: LoadMeter;
+}[], tickMs: number): {
+    instances: number;
+    byMode: Record<string, number>;
+    /**
+     * **테넌트별 몫** — 운영자가 먼저 묻는 것은 "어느 테넌트가 루프를 먹나" 다.
+     *
+     * 실측으로 필요해졌다: 한 도메인 트윈 22개가 CPU 를 110% 쓰는 동안 다른 도메인 화면은 0 이었다.
+     * 무거운 순으로 낸다. 몫은 **잰 트윈들 사이의 비율**이다(안 잰 트윈은 분모에 없다).
+     */
+    byDomain: {
+        domainId: string;
+        label: string;
+        instances: number;
+        recentBusyMs: number;
+        share: number;
+    }[];
+    forksCreated: number;
+    /** 최근 창에서 트윈들이 쓴 시간의 합(ms) — 창 길이를 넘으면 루프가 이미 밀리고 있다. */
+    recentBusyMs: number;
+    /** 그 창의 길이(ms). 창이 하나도 안 닫혔으면 `null`. */
+    recentSpanMs: number | null;
+    /** 전체가 루프를 얼마나 쓰나(0~1+). 1 을 넘으면 **한 틱 안에 다 못 끝낸다.** */
+    fleetBusyRatio: number | null;
+    slowest: {
+        instanceId: string;
+        mode: string;
+        domainId?: string;
+        domainLabel?: string;
+        recentBusyMs: number;
+        topPhase: LoadPhase | null;
+        overBudget: number;
+    }[];
+};
+/**
+ * 프로세스가 실제로 쓴 CPU — **계기판의 다른 숫자들과 뜻이 다르다.**
+ *
+ * 이 파일의 다른 값들은 트윈의 **계측된 8개 작업**만 잰 것이다. 그런데 프로세스는 그 밖에도 일한다:
+ * GraphQL·TypeORM·GC·webpack·HTTP. 그래서 "루프 점유 <1%" 인데 CPU 는 110% 일 수 있고, 실제로 그런
+ * 상태를 겪었다. 두 숫자를 나란히 두면 **트윈이 범인인지 아닌지**를 바로 가릴 수 있다.
+ *
+ * 코어 여러 개를 쓰면 1 을 넘을 수 있다(운영체제의 `%CPU` 와 같은 뜻).
+ */
+export type CpuSampler = {
+    lastMicros: number;
+    lastMs: number;
+};
+/** 첫 표본은 비교 대상이 없다 — `-1` 로 두어 "아직 모른다" 와 0 을 구별한다. */
+export declare function newCpuSampler(): CpuSampler;
+/**
+ * 두 표본 사이의 CPU 점유율. 처음 부르면 `null`(0 이 아니다 — 잰 구간이 없다).
+ *
+ * @param totalMicros `process.cpuUsage()` 의 user + system (마이크로초 누적)
+ */
+export declare function sampleCpu(s: CpuSampler, totalMicros: number, nowMs: number): {
+    ratio: number;
+    spanMs: number;
+} | null;
+export {};

package/dist-server/engine/load-meter.js

@@ -0,0 +1,267 @@
+"use strict";
+/*
+ * 부하 계기판 — **어떤 작업이 이벤트 루프를 얼마나 쓰는지** 작업별로 잰다. 순수(import 없음).
+ *
+ * ── 왜 필요한가 (2026-08-07) ───────────────────────────────────────────────
+ * 시뮬 틱은 트윈마다 `setInterval(1000ms)` 로 **메인 이벤트 루프에서 동기로** 수행된다. 부팅 시 16개가
+ * 자동 프로비저닝되므로 초당 16번이 같은 루프에서 차례로 실행된다. 한 주기가 예산을 넘기면 타이머가
+ * 밀려 쌓이고, 같은 루프에 있는 HTTP·GraphQL·웹소켓이 **함께 멈춘다.**
+ *
+ * 실제로 그런 상태를 만났다: 포트는 LISTEN 이고 webpack 은 `compiled successfully` 인데 요청이 하나도
+ * 처리되지 않고 CPU 만 99% 였다. **터지면 알지만 느려지면 몰랐다** — `tickGuarded` 는 예외만 잡고
+ * 시간은 재지 않았고, `TwinMetrics` 에는 라이브 지표(유입·방송·저널)뿐이라 시뮬 틱은 아무도 안 봤다.
+ *
+ * ── 총량만으로는 부족하다 ─────────────────────────────────────────────────
+ * "틱이 800ms 걸렸다" 는 어디를 고칠지 알려 주지 않는다. 한 주기는 여러 작업으로 이뤄진다 —
+ * 커널 틱 · 상태 투영(snapshot) · 방송 payload 만들기 · 발행 · 저널 기록 · 유입 흡수. 그래서
+ * **작업마다 따로** 잰다. 어느 작업이 총 시간의 몇 %인지 보이면 손댈 곳이 정해진다.
+ *
+ * 재고 말하는 것이 먼저다. 워커 스레드로 옮기는 것은 그다음이다 — 무엇이 느린지 모른 채 옮기면
+ * 느린 채로 옮겨진다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WINDOW_MS = exports.WARN_COOLDOWN_MS = exports.TICK_BUDGET_RATIO = exports.LOAD_PHASES = void 0;
+exports.newLoadMeter = newLoadMeter;
+exports.recordPhase = recordPhase;
+exports.recordFork = recordFork;
+exports.rollWindow = rollWindow;
+exports.judgeCycle = judgeCycle;
+exports.loadSummary = loadSummary;
+exports.slowTickMessage = slowTickMessage;
+exports.fleetLoad = fleetLoad;
+exports.newCpuSampler = newCpuSampler;
+exports.sampleCpu = sampleCpu;
+/** 작업 이름 — 새 작업을 재기 시작하면 여기 늘린다(문자열을 자유롭게 쓰지 않는다: 오타가 새 칸이 된다). */
+exports.LOAD_PHASES = ['tick', 'snapshot', 'deltas', 'publish', 'journal', 'ingest', 'forecast', 'forkTick'];
+function newLoadMeter() {
+    return { phases: {}, window: { startMs: -1, phases: {} }, recent: null, forksCreated: 0, overBudget: 0, lastWarnMs: -Infinity };
+}
+/**
+ * 예산 — 틱 간격의 절반. 넘으면 루프의 절반을 이 트윈 하나가 쓰고 있다는 뜻이다.
+ *
+ * 절반인 이유: 트윈이 여럿이라 각자 간격을 다 쓰면 이미 포화다. 절반에서 알아야 손 쓸 틈이 있다.
+ */
+exports.TICK_BUDGET_RATIO = 0.5;
+/** 경고를 다시 낼 때까지의 최소 간격(ms) — 느린 트윈은 매 틱 느리므로, 그대로 두면 로그가 원인을 덮는다. */
+exports.WARN_COOLDOWN_MS = 30_000;
+/**
+ * 한 작업의 소요를 기록한다. **누적만 하고 판단하지 않는다.**
+ *
+ * 음수·NaN 은 기록하지 않는다(시계가 뒤로 간 경우). 없는 값을 0 으로 세면 평균이 거짓이 된다.
+ */
+function recordPhase(meter, phase, tookMs, nowMs = Date.now()) {
+    if (!Number.isFinite(tookMs) || tookMs < 0)
+        return;
+    rollWindow(meter, nowMs);
+    for (const bucket of [meter.phases, meter.window.phases]) {
+        const s = bucket[phase] ?? (bucket[phase] = { count: 0, lastMs: 0, maxMs: 0, totalMs: 0 });
+        s.count += 1;
+        s.lastMs = tookMs;
+        s.totalMs += tookMs;
+        if (tookMs > s.maxMs)
+            s.maxMs = tookMs;
+    }
+}
+/** fork 하나가 만들어졌다 — 예측 한 번이 수십 개를 만든다. 수를 알아야 부하의 출처를 짚는다. */
+function recordFork(meter, count = 1) {
+    meter.forksCreated += count;
+}
+/** 실시간 창의 길이(ms) — 이보다 길게 보려면 누적을 본다. */
+exports.WINDOW_MS = 10_000;
+/** 창이 다 찼으면 닫고 새로 연다. **닫힌 창만 "최근" 으로 읽는다** — 채우는 중인 창은 과소 집계다. */
+function rollWindow(meter, nowMs, windowMs = exports.WINDOW_MS) {
+    if (meter.window.startMs < 0) {
+        meter.window.startMs = nowMs;
+        return;
+    }
+    if (nowMs - meter.window.startMs < windowMs)
+        return;
+    meter.recent = { ...meter.window, endMs: nowMs };
+    meter.window = { startMs: nowMs, phases: {} };
+}
+/**
+ * 이 주기가 예산을 넘었나 — 넘었으면 세고, **말할 때인지**까지 답한다.
+ */
+function judgeCycle(meter, tookMs, tickMs, nowMs, budgetRatio = exports.TICK_BUDGET_RATIO, cooldownMs = exports.WARN_COOLDOWN_MS) {
+    const budgetMs = tickMs * budgetRatio;
+    const over = Number.isFinite(tookMs) && tookMs > budgetMs;
+    if (!over)
+        return { over: false, warn: false, budgetMs };
+    meter.overBudget += 1;
+    const warn = nowMs - meter.lastWarnMs >= cooldownMs;
+    if (warn)
+        meter.lastWarnMs = nowMs;
+    return { over: true, warn, budgetMs };
+}
+const round2 = (v) => Math.round(v * 100) / 100;
+/**
+ * 비율은 자릿수를 더 준다 — **작은 값이 0 이 되면 "안 쓴다" 로 읽힌다.**
+ *
+ * 24ms/11초 = 0.0022 인데 소수 둘째 자리로 반올림하면 0 이 되어, 재서 나온 값과 없는 값이 같아진다.
+ * 오늘 겪은 착각(0 과 없음을 구별 못 함)과 같은 종류라 여기서 막는다.
+ */
+const round4 = (v) => Math.round(v * 10000) / 10000;
+function toRows(phases) {
+    const entries = Object.entries(phases).filter(([, s]) => s.count > 0);
+    const totalMs = entries.reduce((sum, [, s]) => sum + s.totalMs, 0);
+    const rows = entries
+        .map(([phase, s]) => ({
+        phase,
+        count: s.count,
+        lastMs: round2(s.lastMs),
+        maxMs: round2(s.maxMs),
+        avgMs: round2(s.totalMs / s.count),
+        totalMs: round2(s.totalMs),
+        share: totalMs > 0 ? round4(s.totalMs / totalMs) : 0
+    }))
+        .sort((a, b) => b.totalMs - a.totalMs);
+    return { rows, totalMs };
+}
+function toView(phases, spanMs) {
+    const { rows, totalMs } = toRows(phases);
+    if (!rows.length)
+        return null;
+    return {
+        phases: rows,
+        measuredTotalMs: round2(totalMs),
+        spanMs,
+        busyRatio: spanMs && spanMs > 0 ? round4(totalMs / spanMs) : null
+    };
+}
+/**
+ * 읽기용 요약 — **실시간과 누적을 함께** 낸다.
+ *
+ *  · `recent` — 마지막으로 **닫힌** 창. 지금 이 트윈이 루프를 얼마나 쓰고 있나. 채우는 중인 창은
+ *    과소 집계라 쓰지 않는다.
+ *  · `total` — 기동 이후 전부. 총량과 최악값.
+ *
+ * 잰 적이 없으면 **`null` 이다.** 0 으로 채우면 "0ms 다"(= 아주 빠르다)로 읽혀, 재지 않은 것과 정반대의
+ * 뜻이 된다. 몫(`share`)도 잰 작업들 사이의 비율일 뿐 — **재지 않은 작업은 분모에 없다.**
+ */
+function loadSummary(meter, tickMs) {
+    if (!meter)
+        return null;
+    const total = toView(meter.phases, null);
+    const recent = meter.recent ? toView(meter.recent.phases, meter.recent.endMs - meter.recent.startMs) : null;
+    if (!total && !recent && !meter.forksCreated)
+        return null;
+    const tick = meter.phases.tick;
+    return {
+        recent,
+        total,
+        forksCreated: meter.forksCreated,
+        overBudget: meter.overBudget,
+        budgetMs: tickMs * exports.TICK_BUDGET_RATIO,
+        loadRatio: tick && tick.count > 0 ? round4(tick.lastMs / tickMs) : null
+    };
+}
+/**
+ * 경고 한 줄 — **무엇이 느린지까지 말한다.** "틱이 800ms" 만으로는 어디를 볼지 알 수 없다.
+ *
+ * 가장 무거운 작업 셋을 몫과 함께 적는다.
+ */
+function slowTickMessage(instanceId, tookMs, budgetMs, meter) {
+    const { rows } = toRows(meter.recent?.phases ?? meter.phases);
+    const top = rows
+        .slice(0, 3)
+        .map(p => `${p.phase} ${p.avgMs}ms(${Math.round(p.share * 100)}%)`)
+        .join(' · ');
+    return (`[twin-engine] "${instanceId}" 틱 ${round2(tookMs)}ms — 예산 ${round2(budgetMs)}ms 초과. ` +
+        (top ? `무거운 작업: ${top}. ` : '') +
+        `시뮬 틱이 메인 이벤트 루프에서 수행됩니다 — 이 상태가 이어지면 HTTP·구독이 함께 느려집니다.`);
+}
+/**
+ * 전체 한눈에 — **누가 루프를 점유하고 있나.**
+ *
+ * 인스턴스 목록을 받아 대수·모드별 수·fork 총수를 세고, **최근 창의 부하가 큰 순서**로 줄을 세운다.
+ * 누적이 아니라 최근으로 세우는 이유: 지금 아픈 것을 먼저 봐야 한다(누적 1위는 오래 떠 있던 것일 뿐일
+ * 수 있다).
+ */
+function fleetLoad(rows, tickMs) {
+    const byMode = {};
+    const domains = new Map();
+    let forksCreated = 0;
+    let recentBusyMs = 0;
+    let recentSpanMs = null;
+    const slowest = rows.map(r => {
+        byMode[r.mode] = (byMode[r.mode] ?? 0) + 1;
+        forksCreated += r.meter?.forksCreated ?? 0;
+        const recent = r.meter?.recent;
+        const { rows: phaseRows, totalMs } = toRows(recent?.phases ?? {});
+        /*
+         * **잎에서 한 번만 반올림한다.** 도메인 합계와 전체 합계는 이 값을 더해서 만든다.
+         *
+         * 전에는 트윈·도메인·전체를 각자 원값에서 반올림했다. 그래서 화면의 숫자가 서로 안 맞았다:
+         * system 도메인 0.08ms 인데 그 도메인의 트윈 둘은 0.08 + 0.01 = 0.09ms (2026-08-07 지적).
+         * 보이는 부분들의 합이 보이는 합계와 달라지면 계기판을 믿을 수 없다.
+         */
+        const busyMs = round2(totalMs);
+        if (recent) {
+            recentBusyMs += busyMs;
+            const span = recent.endMs - recent.startMs;
+            /* 창 길이는 트윈마다 조금씩 다를 수 있다 — 가장 긴 것을 쓴다(짧은 것을 쓰면 비율이 부풀려진다). */
+            if (span > 0 && (recentSpanMs === null || span > recentSpanMs))
+                recentSpanMs = span;
+        }
+        /* 테넌트별 합산 — 라벨을 모르면 id 를 그대로 쓴다(지어내지 않는다). */
+        const key = r.domainId ?? '(unknown)';
+        const dom = domains.get(key) ?? { label: r.domainLabel || key, instances: 0, recentBusyMs: 0 };
+        dom.instances += 1;
+        dom.recentBusyMs += busyMs;
+        domains.set(key, dom);
+        return {
+            instanceId: r.instanceId,
+            mode: r.mode,
+            domainId: r.domainId,
+            domainLabel: r.domainLabel,
+            recentBusyMs: busyMs,
+            topPhase: phaseRows[0]?.phase ?? null,
+            overBudget: r.meter?.overBudget ?? 0
+        };
+    });
+    slowest.sort((a, b) => b.recentBusyMs - a.recentBusyMs);
+    const byDomain = [...domains.entries()]
+        .map(([domainId, d]) => ({
+        domainId,
+        label: d.label,
+        instances: d.instances,
+        recentBusyMs: round2(d.recentBusyMs),
+        share: recentBusyMs > 0 ? round4(d.recentBusyMs / recentBusyMs) : 0
+    }))
+        .sort((a, b) => b.recentBusyMs - a.recentBusyMs);
+    return {
+        instances: rows.length,
+        byMode,
+        byDomain,
+        forksCreated,
+        recentBusyMs: round2(recentBusyMs),
+        recentSpanMs,
+        fleetBusyRatio: recentSpanMs && recentSpanMs > 0 ? round4(recentBusyMs / recentSpanMs) : null,
+        slowest
+    };
+}
+/** 첫 표본은 비교 대상이 없다 — `-1` 로 두어 "아직 모른다" 와 0 을 구별한다. */
+function newCpuSampler() {
+    return { lastMicros: -1, lastMs: -1 };
+}
+/**
+ * 두 표본 사이의 CPU 점유율. 처음 부르면 `null`(0 이 아니다 — 잰 구간이 없다).
+ *
+ * @param totalMicros `process.cpuUsage()` 의 user + system (마이크로초 누적)
+ */
+function sampleCpu(s, totalMicros, nowMs) {
+    const prevMicros = s.lastMicros;
+    const prevMs = s.lastMs;
+    s.lastMicros = totalMicros;
+    s.lastMs = nowMs;
+    if (prevMicros < 0 || prevMs < 0)
+        return null;
+    const spanMs = nowMs - prevMs;
+    if (spanMs <= 0)
+        return null;
+    const usedMs = (totalMicros - prevMicros) / 1000;
+    if (usedMs < 0)
+        return null;
+    return { ratio: round4(usedMs / spanMs), spanMs: Math.round(spanMs) };
+}
+//# sourceMappingURL=load-meter.js.map

package/dist-server/engine/load-meter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-meter.js","sourceRoot":"","sources":["../../server/engine/load-meter.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 부하 계기판 — **어떤 작업이 이벤트 루프를 얼마나 쓰는지** 작업별로 잰다. 순수(import 없음).\n *\n * ── 왜 필요한가 (2026-08-07) ───────────────────────────────────────────────\n * 시뮬 틱은 트윈마다 `setInterval(1000ms)` 로 **메인 이벤트 루프에서 동기로** 수행된다. 부팅 시 16개가\n * 자동 프로비저닝되므로 초당 16번이 같은 루프에서 차례로 실행된다. 한 주기가 예산을 넘기면 타이머가\n * 밀려 쌓이고, 같은 루프에 있는 HTTP·GraphQL·웹소켓이 **함께 멈춘다.**\n *\n * 실제로 그런 상태를 만났다: 포트는 LISTEN 이고 webpack 은 `compiled successfully` 인데 요청이 하나도\n * 처리되지 않고 CPU 만 99% 였다. **터지면 알지만 느려지면 몰랐다** — `tickGuarded` 는 예외만 잡고\n * 시간은 재지 않았고, `TwinMetrics` 에는 라이브 지표(유입·방송·저널)뿐이라 시뮬 틱은 아무도 안 봤다.\n *\n * ── 총량만으로는 부족하다 ─────────────────────────────────────────────────\n * \"틱이 800ms 걸렸다\" 는 어디를 고칠지 알려 주지 않는다. 한 주기는 여러 작업으로 이뤄진다 —\n * 커널 틱 · 상태 투영(snapshot) · 방송 payload 만들기 · 발행 · 저널 기록 · 유입 흡수. 그래서\n * **작업마다 따로** 잰다. 어느 작업이 총 시간의 몇 %인지 보이면 손댈 곳이 정해진다.\n *\n * 재고 말하는 것이 먼저다. 워커 스레드로 옮기는 것은 그다음이다 — 무엇이 느린지 모른 채 옮기면\n * 느린 채로 옮겨진다.\n */\n\n/** 작업 이름 — 새 작업을 재기 시작하면 여기 늘린다(문자열을 자유롭게 쓰지 않는다: 오타가 새 칸이 된다). */\nexport const LOAD_PHASES = ['tick', 'snapshot', 'deltas', 'publish', 'journal', 'ingest', 'forecast', 'forkTick'] as const\nexport type LoadPhase = (typeof LOAD_PHASES)[number]\n\nexport interface PhaseStats {\n  /** 잰 횟수. */\n  count: number\n  /** 마지막 소요(ms). */\n  lastMs: number\n  /** 가장 오래 걸린 것(ms) — 평균은 순간 정체를 가린다. */\n  maxMs: number\n  /** 소요 합(ms). 나눗셈은 읽는 쪽에서 한다. */\n  totalMs: number\n}\n\n/** 창(window) 하나의 누적 — \"지금 얼마나 쓰고 있나\" 를 답한다. */\ninterface Window {\n  /** 창이 열린 시각. **아직 안 열렸으면 `-1`** — 0 으로 두면 시각 0 과 구별이 안 된다(검사가 잡았다). */\n  startMs: number\n  phases: Partial<Record<LoadPhase, PhaseStats>>\n}\n\nexport interface LoadMeter {\n  /** **누적** — 프로세스가 뜬 뒤 전부. 총량과 최악값을 본다. */\n  phases: Partial<Record<LoadPhase, PhaseStats>>\n  /** 지금 쌓고 있는 창. */\n  window: Window\n  /** **마지막으로 닫힌 창** — 이것이 \"실시간\" 이다. 없으면 아직 한 창도 안 지났다. */\n  recent: (Window & { endMs: number }) | null\n  /** 이 트윈에서 만들어진 fork 수(누적) — 예측 한 번이 수십 개를 만든다. */\n  forksCreated: number\n  /** 한 주기(틱)가 예산을 넘긴 횟수. */\n  overBudget: number\n  /**\n   * 마지막 경고 시각(ms). **한 번도 안 했으면 `-Infinity`** — 0 으로 두면 \"0 시점에 경고했다\" 가 되어\n   * 첫 느린 틱이 조용히 지나간다(검사가 그것을 잡았다).\n   */\n  lastWarnMs: number\n}\n\nexport function newLoadMeter(): LoadMeter {\n  return { phases: {}, window: { startMs: -1, phases: {} }, recent: null, forksCreated: 0, overBudget: 0, lastWarnMs: -Infinity }\n}\n\n/**\n * 예산 — 틱 간격의 절반. 넘으면 루프의 절반을 이 트윈 하나가 쓰고 있다는 뜻이다.\n *\n * 절반인 이유: 트윈이 여럿이라 각자 간격을 다 쓰면 이미 포화다. 절반에서 알아야 손 쓸 틈이 있다.\n */\nexport const TICK_BUDGET_RATIO = 0.5\n\n/** 경고를 다시 낼 때까지의 최소 간격(ms) — 느린 트윈은 매 틱 느리므로, 그대로 두면 로그가 원인을 덮는다. */\nexport const WARN_COOLDOWN_MS = 30_000\n\n/**\n * 한 작업의 소요를 기록한다. **누적만 하고 판단하지 않는다.**\n *\n * 음수·NaN 은 기록하지 않는다(시계가 뒤로 간 경우). 없는 값을 0 으로 세면 평균이 거짓이 된다.\n */\nexport function recordPhase(meter: LoadMeter, phase: LoadPhase, tookMs: number, nowMs = Date.now()): void {\n  if (!Number.isFinite(tookMs) || tookMs < 0) return\n\n  rollWindow(meter, nowMs)\n  for (const bucket of [meter.phases, meter.window.phases]) {\n    const s = bucket[phase] ?? (bucket[phase] = { count: 0, lastMs: 0, maxMs: 0, totalMs: 0 })\n    s.count += 1\n    s.lastMs = tookMs\n    s.totalMs += tookMs\n    if (tookMs > s.maxMs) s.maxMs = tookMs\n  }\n}\n\n/** fork 하나가 만들어졌다 — 예측 한 번이 수십 개를 만든다. 수를 알아야 부하의 출처를 짚는다. */\nexport function recordFork(meter: LoadMeter, count = 1): void {\n  meter.forksCreated += count\n}\n\n/** 실시간 창의 길이(ms) — 이보다 길게 보려면 누적을 본다. */\nexport const WINDOW_MS = 10_000\n\n/** 창이 다 찼으면 닫고 새로 연다. **닫힌 창만 \"최근\" 으로 읽는다** — 채우는 중인 창은 과소 집계다. */\nexport function rollWindow(meter: LoadMeter, nowMs: number, windowMs = WINDOW_MS): void {\n  if (meter.window.startMs < 0) {\n    meter.window.startMs = nowMs\n    return\n  }\n  if (nowMs - meter.window.startMs < windowMs) return\n\n  meter.recent = { ...meter.window, endMs: nowMs }\n  meter.window = { startMs: nowMs, phases: {} }\n}\n\n/**\n * 이 주기가 예산을 넘었나 — 넘었으면 세고, **말할 때인지**까지 답한다.\n */\nexport function judgeCycle(\n  meter: LoadMeter,\n  tookMs: number,\n  tickMs: number,\n  nowMs: number,\n  budgetRatio = TICK_BUDGET_RATIO,\n  cooldownMs = WARN_COOLDOWN_MS\n): { over: boolean; warn: boolean; budgetMs: number } {\n  const budgetMs = tickMs * budgetRatio\n  const over = Number.isFinite(tookMs) && tookMs > budgetMs\n  if (!over) return { over: false, warn: false, budgetMs }\n\n  meter.overBudget += 1\n  const warn = nowMs - meter.lastWarnMs >= cooldownMs\n  if (warn) meter.lastWarnMs = nowMs\n\n  return { over: true, warn, budgetMs }\n}\n\nconst round2 = (v: number) => Math.round(v * 100) / 100\n/**\n * 비율은 자릿수를 더 준다 — **작은 값이 0 이 되면 \"안 쓴다\" 로 읽힌다.**\n *\n * 24ms/11초 = 0.0022 인데 소수 둘째 자리로 반올림하면 0 이 되어, 재서 나온 값과 없는 값이 같아진다.\n * 오늘 겪은 착각(0 과 없음을 구별 못 함)과 같은 종류라 여기서 막는다.\n */\nconst round4 = (v: number) => Math.round(v * 10000) / 10000\n\nexport interface PhaseRow {\n  phase: LoadPhase\n  count: number\n  lastMs: number\n  maxMs: number\n  avgMs: number\n  totalMs: number\n  /** 잰 작업 전체 시간 중 이 작업의 몫(0~1). 어디를 고칠지 이 값이 정한다. */\n  share: number\n}\n\nexport interface LoadView {\n  phases: PhaseRow[]\n  measuredTotalMs: number\n  /** 이 구간의 길이(ms). 누적은 프로세스 기동 이후라 알 수 없으므로 `null`. */\n  spanMs: number | null\n  /** 구간 중 몇 %를 이 트윈이 썼나(0~1+). 구간을 모르면 `null` — **0 이 아니다.** */\n  busyRatio: number | null\n}\n\nfunction toRows(phases: Partial<Record<LoadPhase, PhaseStats>>): { rows: PhaseRow[]; totalMs: number } {\n  const entries = (Object.entries(phases) as [LoadPhase, PhaseStats][]).filter(([, s]) => s.count > 0)\n  const totalMs = entries.reduce((sum, [, s]) => sum + s.totalMs, 0)\n  const rows = entries\n    .map(([phase, s]) => ({\n      phase,\n      count: s.count,\n      lastMs: round2(s.lastMs),\n      maxMs: round2(s.maxMs),\n      avgMs: round2(s.totalMs / s.count),\n      totalMs: round2(s.totalMs),\n      share: totalMs > 0 ? round4(s.totalMs / totalMs) : 0\n    }))\n    .sort((a, b) => b.totalMs - a.totalMs)\n\n  return { rows, totalMs }\n}\n\nfunction toView(phases: Partial<Record<LoadPhase, PhaseStats>>, spanMs: number | null): LoadView | null {\n  const { rows, totalMs } = toRows(phases)\n  if (!rows.length) return null\n\n  return {\n    phases: rows,\n    measuredTotalMs: round2(totalMs),\n    spanMs,\n    busyRatio: spanMs && spanMs > 0 ? round4(totalMs / spanMs) : null\n  }\n}\n\n/**\n * 읽기용 요약 — **실시간과 누적을 함께** 낸다.\n *\n *  · `recent` — 마지막으로 **닫힌** 창. 지금 이 트윈이 루프를 얼마나 쓰고 있나. 채우는 중인 창은\n *    과소 집계라 쓰지 않는다.\n *  · `total` — 기동 이후 전부. 총량과 최악값.\n *\n * 잰 적이 없으면 **`null` 이다.** 0 으로 채우면 \"0ms 다\"(= 아주 빠르다)로 읽혀, 재지 않은 것과 정반대의\n * 뜻이 된다. 몫(`share`)도 잰 작업들 사이의 비율일 뿐 — **재지 않은 작업은 분모에 없다.**\n */\nexport function loadSummary(meter: LoadMeter | undefined, tickMs: number): {\n  recent: LoadView | null\n  total: LoadView | null\n  forksCreated: number\n  overBudget: number\n  budgetMs: number\n  /** 마지막 틱이 간격을 얼마나 썼나(0~1+). 1 이면 간격을 통째로 쓴다. */\n  loadRatio: number | null\n} | null {\n  if (!meter) return null\n\n  const total = toView(meter.phases, null)\n  const recent = meter.recent ? toView(meter.recent.phases, meter.recent.endMs - meter.recent.startMs) : null\n  if (!total && !recent && !meter.forksCreated) return null\n\n  const tick = meter.phases.tick\n  return {\n    recent,\n    total,\n    forksCreated: meter.forksCreated,\n    overBudget: meter.overBudget,\n    budgetMs: tickMs * TICK_BUDGET_RATIO,\n    loadRatio: tick && tick.count > 0 ? round4(tick.lastMs / tickMs) : null\n  }\n}\n\n/**\n * 경고 한 줄 — **무엇이 느린지까지 말한다.** \"틱이 800ms\" 만으로는 어디를 볼지 알 수 없다.\n *\n * 가장 무거운 작업 셋을 몫과 함께 적는다.\n */\nexport function slowTickMessage(instanceId: string, tookMs: number, budgetMs: number, meter: LoadMeter): string {\n  const { rows } = toRows(meter.recent?.phases ?? meter.phases)\n  const top = rows\n    .slice(0, 3)\n    .map(p => `${p.phase} ${p.avgMs}ms(${Math.round(p.share * 100)}%)`)\n    .join(' · ')\n\n  return (\n    `[twin-engine] \"${instanceId}\" 틱 ${round2(tookMs)}ms — 예산 ${round2(budgetMs)}ms 초과. ` +\n    (top ? `무거운 작업: ${top}. ` : '') +\n    `시뮬 틱이 메인 이벤트 루프에서 수행됩니다 — 이 상태가 이어지면 HTTP·구독이 함께 느려집니다.`\n  )\n}\n\n/**\n * 전체 한눈에 — **누가 루프를 점유하고 있나.**\n *\n * 인스턴스 목록을 받아 대수·모드별 수·fork 총수를 세고, **최근 창의 부하가 큰 순서**로 줄을 세운다.\n * 누적이 아니라 최근으로 세우는 이유: 지금 아픈 것을 먼저 봐야 한다(누적 1위는 오래 떠 있던 것일 뿐일\n * 수 있다).\n */\nexport function fleetLoad(\n  rows: { instanceId: string; mode: string; domainId?: string; domainLabel?: string; meter?: LoadMeter }[],\n  tickMs: number\n): {\n  instances: number\n  byMode: Record<string, number>\n  /**\n   * **테넌트별 몫** — 운영자가 먼저 묻는 것은 \"어느 테넌트가 루프를 먹나\" 다.\n   *\n   * 실측으로 필요해졌다: 한 도메인 트윈 22개가 CPU 를 110% 쓰는 동안 다른 도메인 화면은 0 이었다.\n   * 무거운 순으로 낸다. 몫은 **잰 트윈들 사이의 비율**이다(안 잰 트윈은 분모에 없다).\n   */\n  byDomain: { domainId: string; label: string; instances: number; recentBusyMs: number; share: number }[]\n  forksCreated: number\n  /** 최근 창에서 트윈들이 쓴 시간의 합(ms) — 창 길이를 넘으면 루프가 이미 밀리고 있다. */\n  recentBusyMs: number\n  /** 그 창의 길이(ms). 창이 하나도 안 닫혔으면 `null`. */\n  recentSpanMs: number | null\n  /** 전체가 루프를 얼마나 쓰나(0~1+). 1 을 넘으면 **한 틱 안에 다 못 끝낸다.** */\n  fleetBusyRatio: number | null\n  slowest: { instanceId: string; mode: string; domainId?: string; domainLabel?: string; recentBusyMs: number; topPhase: LoadPhase | null; overBudget: number }[]\n} {\n  const byMode: Record<string, number> = {}\n  const domains = new Map<string, { label: string; instances: number; recentBusyMs: number }>()\n  let forksCreated = 0\n  let recentBusyMs = 0\n  let recentSpanMs: number | null = null\n\n  const slowest = rows.map(r => {\n    byMode[r.mode] = (byMode[r.mode] ?? 0) + 1\n    forksCreated += r.meter?.forksCreated ?? 0\n\n    const recent = r.meter?.recent\n    const { rows: phaseRows, totalMs } = toRows(recent?.phases ?? {})\n    /*\n     * **잎에서 한 번만 반올림한다.** 도메인 합계와 전체 합계는 이 값을 더해서 만든다.\n     *\n     * 전에는 트윈·도메인·전체를 각자 원값에서 반올림했다. 그래서 화면의 숫자가 서로 안 맞았다:\n     * system 도메인 0.08ms 인데 그 도메인의 트윈 둘은 0.08 + 0.01 = 0.09ms (2026-08-07 지적).\n     * 보이는 부분들의 합이 보이는 합계와 달라지면 계기판을 믿을 수 없다.\n     */\n    const busyMs = round2(totalMs)\n    if (recent) {\n      recentBusyMs += busyMs\n      const span = recent.endMs - recent.startMs\n      /* 창 길이는 트윈마다 조금씩 다를 수 있다 — 가장 긴 것을 쓴다(짧은 것을 쓰면 비율이 부풀려진다). */\n      if (span > 0 && (recentSpanMs === null || span > recentSpanMs)) recentSpanMs = span\n    }\n\n    /* 테넌트별 합산 — 라벨을 모르면 id 를 그대로 쓴다(지어내지 않는다). */\n    const key = r.domainId ?? '(unknown)'\n    const dom = domains.get(key) ?? { label: r.domainLabel || key, instances: 0, recentBusyMs: 0 }\n    dom.instances += 1\n    dom.recentBusyMs += busyMs\n    domains.set(key, dom)\n\n    return {\n      instanceId: r.instanceId,\n      mode: r.mode,\n      domainId: r.domainId,\n      domainLabel: r.domainLabel,\n      recentBusyMs: busyMs,\n      topPhase: phaseRows[0]?.phase ?? null,\n      overBudget: r.meter?.overBudget ?? 0\n    }\n  })\n\n  slowest.sort((a, b) => b.recentBusyMs - a.recentBusyMs)\n\n  const byDomain = [...domains.entries()]\n    .map(([domainId, d]) => ({\n      domainId,\n      label: d.label,\n      instances: d.instances,\n      recentBusyMs: round2(d.recentBusyMs),\n      share: recentBusyMs > 0 ? round4(d.recentBusyMs / recentBusyMs) : 0\n    }))\n    .sort((a, b) => b.recentBusyMs - a.recentBusyMs)\n\n  return {\n    instances: rows.length,\n    byMode,\n    byDomain,\n    forksCreated,\n    recentBusyMs: round2(recentBusyMs),\n    recentSpanMs,\n    fleetBusyRatio: recentSpanMs && recentSpanMs > 0 ? round4(recentBusyMs / recentSpanMs) : null,\n    slowest\n  }\n}\n\n/**\n * 프로세스가 실제로 쓴 CPU — **계기판의 다른 숫자들과 뜻이 다르다.**\n *\n * 이 파일의 다른 값들은 트윈의 **계측된 8개 작업**만 잰 것이다. 그런데 프로세스는 그 밖에도 일한다:\n * GraphQL·TypeORM·GC·webpack·HTTP. 그래서 \"루프 점유 <1%\" 인데 CPU 는 110% 일 수 있고, 실제로 그런\n * 상태를 겪었다. 두 숫자를 나란히 두면 **트윈이 범인인지 아닌지**를 바로 가릴 수 있다.\n *\n * 코어 여러 개를 쓰면 1 을 넘을 수 있다(운영체제의 `%CPU` 와 같은 뜻).\n */\nexport type CpuSampler = { lastMicros: number; lastMs: number }\n\n/** 첫 표본은 비교 대상이 없다 — `-1` 로 두어 \"아직 모른다\" 와 0 을 구별한다. */\nexport function newCpuSampler(): CpuSampler {\n  return { lastMicros: -1, lastMs: -1 }\n}\n\n/**\n * 두 표본 사이의 CPU 점유율. 처음 부르면 `null`(0 이 아니다 — 잰 구간이 없다).\n *\n * @param totalMicros `process.cpuUsage()` 의 user + system (마이크로초 누적)\n */\nexport function sampleCpu(s: CpuSampler, totalMicros: number, nowMs: number): { ratio: number; spanMs: number } | null {\n  const prevMicros = s.lastMicros\n  const prevMs = s.lastMs\n  s.lastMicros = totalMicros\n  s.lastMs = nowMs\n\n  if (prevMicros < 0 || prevMs < 0) return null\n\n  const spanMs = nowMs - prevMs\n  if (spanMs <= 0) return null\n\n  const usedMs = (totalMicros - prevMicros) / 1000\n  if (usedMs < 0) return null\n\n  return { ratio: round4(usedMs / spanMs), spanMs: Math.round(spanMs) }\n}\n"]}