@things-factory/headless-twin 10.1.277 → 10.1.279

package/server/engine/load-meter.ts

@@ -1,393 +0,0 @@
-/*
- * 부하 계기판 — **어떤 작업이 이벤트 루프를 얼마나 쓰는지** 작업별로 잰다. 순수(import 없음).
- *
- * ── 왜 필요한가 (2026-08-07) ───────────────────────────────────────────────
- * 시뮬 틱은 트윈마다 `setInterval(1000ms)` 로 **메인 이벤트 루프에서 동기로** 수행된다. 부팅 시 16개가
- * 자동 프로비저닝되므로 초당 16번이 같은 루프에서 차례로 실행된다. 한 주기가 예산을 넘기면 타이머가
- * 밀려 쌓이고, 같은 루프에 있는 HTTP·GraphQL·웹소켓이 **함께 멈춘다.**
- *
- * 실제로 그런 상태를 만났다: 포트는 LISTEN 이고 webpack 은 `compiled successfully` 인데 요청이 하나도
- * 처리되지 않고 CPU 만 99% 였다. **터지면 알지만 느려지면 몰랐다** — `tickGuarded` 는 예외만 잡고
- * 시간은 재지 않았고, `TwinMetrics` 에는 라이브 지표(유입·브로드캐스팅·저널)뿐이라 시뮬 틱은 아무도 안 봤다.
- *
- * ── 총량만으로는 부족하다 ─────────────────────────────────────────────────
- * "틱이 800ms 걸렸다" 는 어디를 고칠지 알려 주지 않는다. 한 주기는 여러 작업으로 이뤄진다 —
- * 커널 틱 · 상태 투영(snapshot) · 브로드캐스팅 payload 만들기 · 발행 · 저널 기록 · 유입 흡수. 그래서
- * **작업마다 따로** 잰다. 어느 작업이 총 시간의 몇 %인지 보이면 손댈 곳이 정해진다.
- *
- * 재고 말하는 것이 먼저다. 워커 스레드로 옮기는 것은 그다음이다 — 무엇이 느린지 모른 채 옮기면
- * 느린 채로 옮겨진다.
- */
-
-/** 작업 이름 — 새 작업을 재기 시작하면 여기 늘린다(문자열을 자유롭게 쓰지 않는다: 오타가 새 칸이 된다). */
-/*
- * ── 부팅 구간을 재는 두 이름 (2026-08-22) ───────────────────────────────────
- * 실측으로 부팅이 620~717초였고 트윈 하나를 세우는 데 15~93초였다. 그런데 **어느 작업이 그 시간을
- * 쓰는지 아무 계기도 답하지 못했다** — 재는 이름이 도는 중의 작업(틱·브로드캐스팅·저널)뿐이었다.
- * 짐작으로 원인을 적으면 그것이 사실로 읽히므로, 그 자리에 이름을 둔다.
- *
- *  · `warmStart` — 저장된 상태를 커널에 심는다(물품·오더·작업·주목 시각).
- *  · `stimulus`  — 선언된 자극을 싣고 시작한다(실측: 큰 트윈에서 이 뒤가 29~72초였다).
- */
-export const LOAD_PHASES = ['tick', 'snapshot', 'deltas', 'publish', 'journal', 'ingest', 'forecast', 'forkTick', 'warmStart', 'stimulus'] as const
-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 function newLoadMeter(): LoadMeter {
-  return { phases: {}, window: { startMs: -1, phases: {} }, recent: null, forksCreated: 0, overBudget: 0, lastWarnMs: -Infinity }
-}
-
-/**
- * 예산 — 틱 간격의 절반. 넘으면 루프의 절반을 이 트윈 하나가 쓰고 있다는 뜻이다.
- *
- * 절반인 이유: 트윈이 여럿이라 각자 간격을 다 쓰면 이미 포화다. 절반에서 알아야 손 쓸 틈이 있다.
- */
-export const TICK_BUDGET_RATIO = 0.5
-
-/** 경고를 다시 낼 때까지의 최소 간격(ms) — 느린 트윈은 매 틱 느리므로, 그대로 두면 로그가 원인을 덮는다. */
-export const WARN_COOLDOWN_MS = 30_000
-
-/**
- * 한 작업의 소요를 기록한다. **누적만 하고 판단하지 않는다.**
- *
- * 음수·NaN 은 기록하지 않는다(시계가 뒤로 간 경우). 없는 값을 0 으로 세면 평균이 거짓이 된다.
- */
-export function recordPhase(meter: LoadMeter, phase: LoadPhase, tookMs: number, nowMs = Date.now()): void {
-  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 하나가 만들어졌다 — 예측 한 번이 수십 개를 만든다. 수를 알아야 부하의 출처를 짚는다. */
-export function recordFork(meter: LoadMeter, count = 1): void {
-  meter.forksCreated += count
-}
-
-/** 실시간 창의 길이(ms) — 이보다 길게 보려면 누적을 본다. */
-export const WINDOW_MS = 10_000
-
-/** 창이 다 찼으면 닫고 새로 연다. **닫힌 창만 "최근" 으로 읽는다** — 채우는 중인 창은 과소 집계다. */
-export function rollWindow(meter: LoadMeter, nowMs: number, windowMs = WINDOW_MS): void {
-  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: {} }
-}
-
-/**
- * 이 주기가 예산을 넘었나 — 넘었으면 세고, **말할 때인지**까지 답한다.
- */
-export function judgeCycle(
-  meter: LoadMeter,
-  tookMs: number,
-  tickMs: number,
-  nowMs: number,
-  budgetRatio = TICK_BUDGET_RATIO,
-  cooldownMs = WARN_COOLDOWN_MS
-): { over: boolean; warn: boolean; budgetMs: number } {
-  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: number) => Math.round(v * 100) / 100
-/**
- * 비율은 자릿수를 더 준다 — **작은 값이 0 이 되면 "안 쓴다" 로 읽힌다.**
- *
- * 24ms/11초 = 0.0022 인데 소수 둘째 자리로 반올림하면 0 이 되어, 재서 나온 값과 없는 값이 같아진다.
- * 오늘 겪은 착각(0 과 없음을 구별 못 함)과 같은 종류라 여기서 막는다.
- */
-const round4 = (v: number) => Math.round(v * 10000) / 10000
-
-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
-}
-
-function toRows(phases: Partial<Record<LoadPhase, PhaseStats>>): { rows: PhaseRow[]; totalMs: number } {
-  const entries = (Object.entries(phases) as [LoadPhase, PhaseStats][]).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: Partial<Record<LoadPhase, PhaseStats>>, spanMs: number | null): LoadView | null {
-  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`)도 잰 작업들 사이의 비율일 뿐 — **재지 않은 작업은 분모에 없다.**
- */
-export 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 {
-  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 * TICK_BUDGET_RATIO,
-    loadRatio: tick && tick.count > 0 ? round4(tick.lastMs / tickMs) : null
-  }
-}
-
-/**
- * 경고 한 줄 — **무엇이 느린지까지 말한다.** "틱이 800ms" 만으로는 어디를 볼지 알 수 없다.
- *
- * 가장 무거운 작업 셋을 몫과 함께 적는다.
- */
-export function slowTickMessage(instanceId: string, tookMs: number, budgetMs: number, meter: LoadMeter): string {
-  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위는 오래 떠 있던 것일 뿐일
- * 수 있다).
- */
-export 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 }[]
-} {
-  const byMode: Record<string, number> = {}
-  const domains = new Map<string, { label: string; instances: number; recentBusyMs: number }>()
-  let forksCreated = 0
-  let recentBusyMs = 0
-  let recentSpanMs: number | null = 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
-  }
-}
-
-/**
- * 프로세스가 실제로 쓴 CPU — **계기판의 다른 숫자들과 뜻이 다르다.**
- *
- * 이 파일의 다른 값들은 트윈의 **계측된 8개 작업**만 잰 것이다. 그런데 프로세스는 그 밖에도 일한다:
- * GraphQL·TypeORM·GC·webpack·HTTP. 그래서 "루프 점유 <1%" 인데 CPU 는 110% 일 수 있고, 실제로 그런
- * 상태를 겪었다. 두 숫자를 나란히 두면 **트윈이 범인인지 아닌지**를 바로 가릴 수 있다.
- *
- * 코어 여러 개를 쓰면 1 을 넘을 수 있다(운영체제의 `%CPU` 와 같은 뜻).
- */
-export type CpuSampler = { lastMicros: number; lastMs: number }
-
-/** 첫 표본은 비교 대상이 없다 — `-1` 로 두어 "아직 모른다" 와 0 을 구별한다. */
-export function newCpuSampler(): CpuSampler {
-  return { lastMicros: -1, lastMs: -1 }
-}
-
-/**
- * 두 표본 사이의 CPU 점유율. 처음 부르면 `null`(0 이 아니다 — 잰 구간이 없다).
- *
- * @param totalMicros `process.cpuUsage()` 의 user + system (마이크로초 누적)
- */
-export function sampleCpu(s: CpuSampler, totalMicros: number, nowMs: number): { ratio: number; spanMs: number } | null {
-  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) }
-}