front-cpu 0.1.1

package/src/logging/CPUDebugger.ts

@@ -0,0 +1,235 @@
+/**
+ * CPU 调试器
+ *
+ * 职责：
+ * 1. 提供调试器 API
+ * 2. 支持时间旅行调试
+ * 3. 支持指令重放
+ */
+
+import { cpuLogger } from './CPULogger'
+import { CPUEventType, type CPUEvent } from './types'
+
+export class CPUDebugger {
+  /**
+   * 查询：执行最慢的指令
+   */
+  getSlowestInstructions(limit: number = 10): Array<{
+    instructionId: string
+    instructionType: string
+    duration: number
+    events: CPUEvent[]
+  }> {
+    const instructionTraces = Array.from(cpuLogger['eventsByInstruction'].entries())
+
+    const withDuration = instructionTraces
+      .map(([instructionId, events]) => {
+        const firstEvent = events[0]
+        const lastEvent = events[events.length - 1]
+        if (!firstEvent || !lastEvent) return null
+        const duration = lastEvent.timestamp - firstEvent.timestamp
+
+        return {
+          instructionId,
+          instructionType: firstEvent.instructionType,
+          duration,
+          events,
+        }
+      })
+      .filter((item): item is NonNullable<typeof item> => item !== null && item.duration > 0)
+
+    return withDuration.sort((a, b) => b.duration - a.duration).slice(0, limit)
+  }
+
+  /**
+   * 查询：失败的指令
+   */
+  getFailedInstructions(): Array<{
+    instructionId: string
+    instructionType: string
+    error: string
+    events: CPUEvent[]
+  }> {
+    const failEvents = cpuLogger.getEventsByType(CPUEventType.INSTRUCTION_FAILED)
+
+    return failEvents.map((failEvent) => ({
+      instructionId: failEvent.instructionId,
+      instructionType: failEvent.instructionType,
+      error: failEvent.payload?.error || 'Unknown error',
+      events: cpuLogger.getInstructionTrace(failEvent.instructionId),
+    }))
+  }
+
+  /**
+   * 查询：触发回滚的指令
+   */
+  getRolledBackInstructions(): Array<{
+    instructionId: string
+    instructionType: string
+    reason: string
+    events: CPUEvent[]
+  }> {
+    const rollbackEvents = cpuLogger.getEventsByType(CPUEventType.OPTIMISTIC_ROLLED_BACK)
+
+    return rollbackEvents.map((event) => ({
+      instructionId: event.instructionId,
+      instructionType: event.instructionType,
+      reason: event.payload.reason,
+      events: cpuLogger.getInstructionTrace(event.instructionId),
+    }))
+  }
+
+  /**
+   * 查询：资源冲突链
+   */
+  getResourceConflictChain(instructionId: string): Array<{
+    instructionId: string
+    instructionType: string
+    blockedBy: string[]
+    waitTime: number
+  }> {
+    const events = cpuLogger.getInstructionTrace(instructionId)
+    const conflictEvents = events.filter(
+      (e) => e.eventType === CPUEventType.SCHEDULER_CONFLICT_DETECTED
+    )
+
+    return conflictEvents.map((event) => ({
+      instructionId: event.instructionId,
+      instructionType: event.instructionType,
+      blockedBy: event.payload.conflictingInstructions,
+      waitTime: event.payload.waitTime,
+    }))
+  }
+
+  /**
+   * 时间旅行：重放指令
+   */
+  replayInstruction(instructionId: string): {
+    success: boolean
+    events: CPUEvent[]
+    timeline: Array<{ time: number; stage: string; event: string }>
+  } {
+    const events = cpuLogger.getInstructionTrace(instructionId)
+
+    const timeline = events.map((event) => ({
+      time: event.timestamp,
+      stage: event.pipelineStage,
+      event: event.eventType,
+    }))
+
+    return {
+      success: events.some((e) => e.eventType === CPUEventType.INSTRUCTION_COMMITTED),
+      events,
+      timeline,
+    }
+  }
+
+  /**
+   * 诊断：分析指令为什么慢
+   */
+  diagnoseSlowInstruction(instructionId: string): {
+    instructionId: string
+    totalDuration: number
+    bottleneck: { stage: string; duration: number; percentage: number }
+    breakdown: Array<{ stage: string; duration: number; percentage: number }>
+    suggestions: string[]
+  } {
+    const events = cpuLogger.getInstructionTrace(instructionId)
+    if (events.length === 0) {
+      throw new Error(`Instruction ${instructionId} not found`)
+    }
+
+    const firstEvent = events[0]!
+    const lastEvent = events[events.length - 1]!
+    const totalDuration = lastEvent.timestamp - firstEvent.timestamp
+
+    // 计算每个阶段的耗时
+    const stageBreakdown = new Map<string, number>()
+    for (let i = 1; i < events.length; i++) {
+      const prevEvent = events[i - 1]
+      const currEvent = events[i]
+      const duration = currEvent.timestamp - prevEvent.timestamp
+      const stage = `${prevEvent.pipelineStage}→${currEvent.pipelineStage}`
+      stageBreakdown.set(stage, (stageBreakdown.get(stage) || 0) + duration)
+    }
+
+    const breakdown = Array.from(stageBreakdown.entries())
+      .map(([stage, duration]) => ({
+        stage,
+        duration,
+        percentage: (duration / totalDuration) * 100,
+      }))
+      .sort((a, b) => b.duration - a.duration)
+
+    const bottleneck = breakdown[0]
+
+    // 生成建议
+    const suggestions: string[] = []
+    if (bottleneck.stage.includes('EX')) {
+      suggestions.push('网络请求耗时较长，考虑优化后端性能或使用缓存')
+    }
+    if (bottleneck.stage.includes('SCH')) {
+      suggestions.push('调度器等待时间较长，存在资源冲突')
+    }
+    if (bottleneck.percentage > 80) {
+      suggestions.push(
+        `${bottleneck.stage} 占总耗时 ${bottleneck.percentage.toFixed(1)}%，是主要瓶颈`
+      )
+    }
+
+    return {
+      instructionId,
+      totalDuration,
+      bottleneck,
+      breakdown,
+      suggestions,
+    }
+  }
+
+  /**
+   * 实时监控：获取最近 N 秒的统计
+   */
+  getRealtimeStats(windowSeconds: number = 5): {
+    instructionsPerSecond: number
+    avgLatency: number
+    errorRate: number
+    topInstructionTypes: Array<{ type: string; count: number }>
+  } {
+    const now = Date.now()
+    const startTime = now - windowSeconds * 1000
+    const recentEvents = cpuLogger.getEventsByTimeRange(startTime, now)
+
+    const instructionIds = new Set(recentEvents.map((e) => e.instructionId))
+    const failedIds = new Set(
+      recentEvents
+        .filter((e) => e.eventType === CPUEventType.INSTRUCTION_FAILED)
+        .map((e) => e.instructionId)
+    )
+
+    const latencies = recentEvents.filter((e) => e.latency !== undefined).map((e) => e.latency!)
+
+    const avgLatency = latencies.reduce((a, b) => a + b, 0) / latencies.length || 0
+
+    const typeCount = new Map<string, number>()
+    for (const event of recentEvents) {
+      if (event.eventType === CPUEventType.INSTRUCTION_CREATED) {
+        typeCount.set(event.instructionType, (typeCount.get(event.instructionType) || 0) + 1)
+      }
+    }
+
+    const topInstructionTypes = Array.from(typeCount.entries())
+      .map(([type, count]) => ({ type, count }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 5)
+
+    return {
+      instructionsPerSecond: instructionIds.size / windowSeconds,
+      avgLatency,
+      errorRate: failedIds.size / instructionIds.size || 0,
+      topInstructionTypes,
+    }
+  }
+}
+
+export const cpuDebugger = new CPUDebugger()
+

package/src/logging/CPUEventCollector.ts

@@ -0,0 +1,418 @@
+/**
+ * CPU 事件采集器
+ *
+ * 职责：
+ * 1. 在流水线各阶段捕获事件
+ * 2. 批量异步发送给 CPULogger
+ * 3. 零侵入、零延迟
+ */
+
+import type { QueuedInstruction } from '../types'
+import { PipelineStage, InstructionStatus } from '../types'
+import { CPUEventType, type CPUEvent } from './types'
+
+export class CPUEventCollector {
+  private eventQueue: CPUEvent[] = []
+  private flushInterval: number = 50 // 50ms 批量刷新
+  private maxBatchSize: number = 100
+  private enabled: boolean = true
+  private flushTimer: ReturnType<typeof setInterval> | null = null
+
+  constructor() {
+    this.startAutoFlush()
+  }
+
+  /**
+   * 启动自动刷新
+   */
+  private startAutoFlush(): void {
+    this.flushTimer = globalThis.setInterval(() => {
+      this.flush()
+    }, this.flushInterval)
+  }
+
+  /**
+   * 停止自动刷新
+   */
+  destroy(): void {
+    if (this.flushTimer !== null) {
+      globalThis.clearInterval(this.flushTimer)
+      this.flushTimer = null
+    }
+    this.flush() // 最后刷新一次
+  }
+
+  /**
+   * 发送事件（异步，不阻塞流水线）
+   */
+  emit(event: Partial<CPUEvent>): void {
+    if (!this.enabled) return
+
+    const fullEvent: CPUEvent = {
+      eventId: this.generateEventId(),
+      timestamp: Date.now(),
+      ...event,
+    } as CPUEvent
+
+    this.eventQueue.push(fullEvent)
+
+    // 触发批量刷新
+    if (this.eventQueue.length >= this.maxBatchSize) {
+      this.flush()
+    }
+  }
+
+  /**
+   * 批量刷新事件
+   */
+  private flush(): void {
+    if (this.eventQueue.length === 0) return
+
+    const batch = this.eventQueue.splice(0, this.maxBatchSize)
+
+    // 异步发送给 Logger（使用 queueMicrotask 确保不阻塞）
+    queueMicrotask(() => {
+      // 动态导入避免循环依赖
+      import('./CPULogger').then(({ cpuLogger }) => {
+        cpuLogger.ingestBatch(batch)
+      })
+    })
+  }
+
+  /**
+   * 便捷方法：指令创建
+   */
+  onInstructionCreated(instruction: QueuedInstruction): void {
+    this.emit({
+      eventType: CPUEventType.INSTRUCTION_CREATED,
+      instructionId: instruction.id,
+      instructionType: instruction.type,
+      correlationId: instruction.context.correlationId,
+      pipelineStage: PipelineStage.IF,
+      instructionStatus: InstructionStatus.PENDING,
+      callSource: instruction.context.callSource, // 🔍 记录调用源
+      payload: {
+        instructionType: instruction.type,
+        payload: instruction.payload,
+        origin: 'user',
+      },
+    })
+  }
+
+  /**
+   * 便捷方法：指令发射
+   */
+  onInstructionIssued(instruction: QueuedInstruction): void {
+    this.emit({
+      eventType: CPUEventType.INSTRUCTION_ISSUED,
+      instructionId: instruction.id,
+      instructionType: instruction.type,
+      correlationId: instruction.context.correlationId,
+      pipelineStage: PipelineStage.SCH,
+      instructionStatus: InstructionStatus.ISSUED,
+      payload: {},
+    })
+  }
+
+  /**
+   * 便捷方法：指令执行
+   */
+  onInstructionExecuting(instruction: QueuedInstruction): void {
+    this.emit({
+      eventType: CPUEventType.INSTRUCTION_EXECUTING,
+      instructionId: instruction.id,
+      instructionType: instruction.type,
+      correlationId: instruction.context.correlationId,
+      pipelineStage: PipelineStage.EX,
+      instructionStatus: InstructionStatus.EXECUTING,
+      payload: {},
+    })
+  }
+
+  /**
+   * 便捷方法：指令完成
+   */
+  onInstructionCommitted(instruction: QueuedInstruction): void {
+    // 计算总执行时间
+    const totalDuration = instruction.timestamps.WB && instruction.timestamps.IF
+      ? instruction.timestamps.WB - instruction.timestamps.IF
+      : undefined
+
+    // 计算各阶段耗时
+    const stageDurations = {
+      ifToSch: instruction.timestamps.SCH && instruction.timestamps.IF
+        ? instruction.timestamps.SCH - instruction.timestamps.IF : undefined,
+      schToEx: instruction.timestamps.EX && instruction.timestamps.SCH
+        ? instruction.timestamps.EX - instruction.timestamps.SCH : undefined,
+      exToWb: instruction.timestamps.WB && instruction.timestamps.EX
+        ? instruction.timestamps.WB - instruction.timestamps.EX : undefined,
+    }
+
+    this.emit({
+      eventType: CPUEventType.INSTRUCTION_COMMITTED,
+      instructionId: instruction.id,
+      instructionType: instruction.type,
+      correlationId: instruction.context.correlationId,
+      pipelineStage: PipelineStage.WB,
+      instructionStatus: InstructionStatus.COMMITTED,
+      callSource: instruction.context.callSource,
+      payload: {
+        // 🔥 包含完整的指令执行信息
+        originalPayload: instruction.payload,
+        result: instruction.result,
+        totalDuration,
+        stageDurations,
+        writeBackExecution: instruction.writeBackExecution,
+        hasOptimisticUpdate: !!instruction.optimisticSnapshot,
+        retryCount: instruction.context.retryCount,
+        timestamps: instruction.timestamps,
+      },
+      latency: totalDuration,
+      metadata: {
+        tags: ['committed', 'success'],
+        ...(instruction.writeBackExecution?.hasCommit && { hasCommit: true }),
+        ...(instruction.optimisticSnapshot && { optimisticUpdate: true }),
+      },
+    })
+  }
+
+  /**
+   * 便捷方法：指令被取消
+   */
+  onInstructionCancelled(instruction: QueuedInstruction): void {
+    // 计算取消时的执行时间
+    const totalDuration = instruction.timestamps.WB && instruction.timestamps.IF
+      ? instruction.timestamps.WB - instruction.timestamps.IF
+      : undefined
+
+    this.emit({
+      eventType: CPUEventType.INSTRUCTION_CANCELLED,
+      instructionId: instruction.id,
+      instructionType: instruction.type,
+      correlationId: instruction.context.correlationId,
+      pipelineStage: PipelineStage.WB,
+      instructionStatus: InstructionStatus.CANCELLED,
+      callSource: instruction.context.callSource,
+      payload: {
+        originalPayload: instruction.payload,
+        cancelReason: instruction.cancelReason,
+        cancelledAt: instruction.cancelledAt,
+        totalDuration,
+      },
+    })
+  }
+
+  /**
+   * 便捷方法：指令失败
+   */
+  onInstructionFailed(instruction: QueuedInstruction, error: Error): void {
+    // 计算总执行时间（失败时也需要记录）
+    const totalDuration = instruction.timestamps.WB && instruction.timestamps.IF
+      ? instruction.timestamps.WB - instruction.timestamps.IF
+      : undefined
+
+    // 计算各阶段耗时
+    const stageDurations = {
+      ifToSch: instruction.timestamps.SCH && instruction.timestamps.IF
+        ? instruction.timestamps.SCH - instruction.timestamps.IF : undefined,
+      schToEx: instruction.timestamps.EX && instruction.timestamps.SCH
+        ? instruction.timestamps.EX - instruction.timestamps.SCH : undefined,
+      exToWb: instruction.timestamps.WB && instruction.timestamps.EX
+        ? instruction.timestamps.WB - instruction.timestamps.EX : undefined,
+    }
+
+    this.emit({
+      eventType: CPUEventType.INSTRUCTION_FAILED,
+      instructionId: instruction.id,
+      instructionType: instruction.type,
+      correlationId: instruction.context.correlationId,
+      pipelineStage: PipelineStage.WB,
+      instructionStatus: InstructionStatus.FAILED,
+      callSource: instruction.context.callSource,
+      payload: {
+        // 🔥 包含完整的指令执行信息
+        originalPayload: instruction.payload,
+        error: error.message,
+        stack: error.stack,
+        totalDuration,
+        stageDurations,
+        writeBackExecution: instruction.writeBackExecution,
+        hasOptimisticUpdate: !!instruction.optimisticSnapshot,
+        rollbackExecuted: instruction.writeBackExecution?.rollbackExecuted,
+        retryCount: instruction.context.retryCount,
+        timestamps: instruction.timestamps,
+      },
+      latency: totalDuration,
+      metadata: {
+        tags: ['error', 'failure'],
+        ...(instruction.writeBackExecution?.rollbackExecuted && { rollbackExecuted: true }),
+        ...(instruction.optimisticSnapshot && { optimisticUpdate: true }),
+      },
+    })
+  }
+
+  /**
+   * 便捷方法：乐观更新应用
+   */
+  onOptimisticApplied(
+    instructionId: string,
+    instructionType: string,
+    correlationId: string,
+    snapshot: any,
+    changes: any
+  ): void {
+    this.emit({
+      eventType: CPUEventType.OPTIMISTIC_APPLIED,
+      instructionId,
+      instructionType,
+      correlationId,
+      pipelineStage: PipelineStage.EX,
+      instructionStatus: InstructionStatus.EXECUTING,
+      payload: { snapshot, changes },
+      metadata: { tags: ['optimistic'] },
+    })
+  }
+
+  /**
+   * 便捷方法：乐观更新回滚
+   */
+  onOptimisticRolledBack(
+    instructionId: string,
+    instructionType: string,
+    correlationId: string,
+    snapshot: any,
+    reason: string,
+    error?: Error
+  ): void {
+    this.emit({
+      eventType: CPUEventType.OPTIMISTIC_ROLLED_BACK,
+      instructionId,
+      instructionType,
+      correlationId,
+      pipelineStage: PipelineStage.WB,
+      instructionStatus: InstructionStatus.FAILED,
+      payload: { snapshot, reason, error: error?.message },
+      metadata: { tags: ['rollback', 'failure'] },
+    })
+  }
+
+  /**
+   * 便捷方法：资源冲突检测
+   */
+  onSchedulerConflict(
+    instructionId: string,
+    instructionType: string,
+    correlationId: string,
+    conflictingInstructions: string[],
+    conflictingResources: string[],
+    waitTime: number
+  ): void {
+    this.emit({
+      eventType: CPUEventType.SCHEDULER_CONFLICT_DETECTED,
+      instructionId,
+      instructionType,
+      correlationId,
+      pipelineStage: PipelineStage.SCH,
+      instructionStatus: InstructionStatus.ISSUED,
+      payload: {
+        conflictingInstructions,
+        conflictingResources,
+        waitTime,
+      },
+      metadata: {
+        resourceIds: conflictingResources,
+        tags: ['conflict', 'scheduler'],
+      },
+    })
+  }
+
+  /**
+   * 便捷方法：网络请求
+   */
+  onNetworkRequest(
+    instructionId: string,
+    instructionType: string,
+    correlationId: string,
+    method: string,
+    url: string
+  ): void {
+    this.emit({
+      eventType: CPUEventType.NETWORK_REQUEST_SENT,
+      instructionId,
+      instructionType,
+      correlationId,
+      pipelineStage: PipelineStage.EX,
+      instructionStatus: InstructionStatus.EXECUTING,
+      payload: { method, url },
+      metadata: { tags: ['network'] },
+    })
+  }
+
+  /**
+   * 便捷方法：网络响应
+   */
+  onNetworkResponse(
+    instructionId: string,
+    instructionType: string,
+    correlationId: string,
+    status: number,
+    latency: number,
+    size: number
+  ): void {
+    this.emit({
+      eventType: CPUEventType.NETWORK_RESPONSE_RECEIVED,
+      instructionId,
+      instructionType,
+      correlationId,
+      pipelineStage: PipelineStage.EX,
+      instructionStatus: InstructionStatus.EXECUTING,
+      payload: { status, latency, size },
+      latency,
+      metadata: { tags: ['network'] },
+    })
+
+    // 🔥 自动检测性能警告
+    if (latency > 1000) {
+      this.emit({
+        eventType: CPUEventType.PERFORMANCE_WARNING,
+        instructionId,
+        instructionType,
+        correlationId,
+        pipelineStage: PipelineStage.EX,
+        instructionStatus: InstructionStatus.EXECUTING,
+        payload: {
+          metric: 'latency',
+          threshold: 1000,
+          actual: latency,
+          suggestion: `网络请求耗时 ${latency}ms，超过阈值 1000ms`,
+        },
+        metadata: { tags: ['performance', 'warning'] },
+      })
+    }
+  }
+
+  /**
+   * 生成事件 ID
+   */
+  private generateEventId(): string {
+    return `evt_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`
+  }
+
+  /**
+   * 启用/禁用采集
+   */
+  enable(): void {
+    this.enabled = true
+  }
+
+  disable(): void {
+    this.enabled = false
+  }
+
+  isEnabled(): boolean {
+    return this.enabled
+  }
+}
+
+// 导出全局单例
+export const cpuEventCollector = new CPUEventCollector()