@ai-setting/roy-agent-core 1.0.0

package/src/env/log-trace/opentelemetry/tracer-provider.ts

@@ -0,0 +1,612 @@
+/**
+ * @fileoverview OpenTelemetry TracerProvider 实现
+ * 
+ * 提供 OpenTelemetry 风格的追踪能力：
+ * - TracerProvider: 全局 Tracer 管理器
+ * - OTelTracer: 具体 Tracer 实现
+ * - OTelSpan: Span 实现
+ * 
+ * 支持 W3C TraceContext 格式的跨进程上下文传递
+ */
+
+import type { SpanContext, SpanAttributes } from "../types";
+import { SQLiteSpanStorage, type SpanStorage } from "../span-storage";
+import { propagation, type ExtractedContext } from "./propagation";
+import { SpanStatus } from "../types";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Span 选项
+ */
+export interface SpanOptions {
+  /** 父 Span 上下文（可选） */
+  parent?: SpanContext;
+  /** Span 属性 */
+  attributes?: SpanAttributes;
+  /** Span 类型 */
+  kind?: string;
+  /** 指定 traceId（可选，如果不提供则自动生成） */
+  traceId?: string;
+}
+
+/**
+ * OTel Span 接口
+ */
+export interface OTelSpan {
+  readonly name: string;
+  readonly kind: string;
+  readonly spanContext: SpanContext;
+  readonly attributes: SpanAttributes;
+  startTime?: number;
+  endTime?: number;
+  error?: string;
+
+  setAttribute(key: string, value: unknown): void;
+  addEvent(name: string, attributes?: Record<string, unknown>): void;
+  end(result?: unknown, error?: Error): void;
+}
+
+/**
+ * 结束 span 并返回清理函数（用于恢复父上下文）
+ */
+export interface OTelSpanEndResult {
+  /** 结束后的父上下文 */
+  parentContext?: SpanContext;
+  /** traceId（用于显示） */
+  traceId: string;
+}
+
+/**
+ * OTel Span 接口扩展 - 提供 endSpan 方法
+ */
+export interface OTelSpanWithEndSpan extends OTelSpan {
+  /**
+   * 结束 span 并返回父上下文
+   * 用于结束根 span 后恢复之前的上下文
+   */
+  endSpan(): OTelSpanEndResult;
+}
+
+/**
+ * Span 结束时的回调函数类型
+ */
+type SpanEndCallback = (spanId: string, parentSpanId?: string) => void;
+
+/**
+ * OTel Tracer 接口
+ */
+export interface OTelTracer {
+  readonly name: string;
+  readonly version?: string;
+  
+  startSpan(name: string, options?: SpanOptions): OTelSpan;
+  /**
+   * 结束指定 span 并恢复父上下文
+   * @param span 要结束的 span
+   * @returns 结束后的父上下文（用于恢复之前的上下文）
+   */
+  endSpan(span: OTelSpan): SpanContext | undefined;
+  injectToEnv(env: Record<string, string | undefined>): void;
+  getCurrentContext(): SpanContext | undefined;
+  setCurrentContext(context: SpanContext | undefined): void;
+  
+  /**
+   * 生成符合 OTel 格式的 traceId（32 字符 16 进制）
+   */
+  generateTraceId(): string;
+  
+  /**
+   * 生成符合 OTel 格式的 spanId（16 字符 16 进制）
+   */
+  generateSpanId(): string;
+}
+
+// ============================================================================
+// Span Implementation
+// ============================================================================
+
+/**
+ * OTel Span 实现
+ */
+class OTelSpanImpl implements OTelSpan {
+  readonly name: string;
+  readonly kind: string;
+  readonly spanContext: SpanContext;
+  readonly attributes: SpanAttributes = {};
+  startTime?: number;
+  endTime?: number;
+  error?: string;
+  
+  private storage: SpanStorage;
+  private parentSpanContext?: SpanContext;
+  private onEnd?: () => void;
+
+  constructor(
+    name: string,
+    spanContext: SpanContext,
+    storage: SpanStorage,
+    parentSpanContext?: SpanContext,
+    onEnd?: () => void
+  ) {
+    this.name = name;
+    this.kind = "internal";
+    this.spanContext = spanContext;
+    this.parentSpanContext = parentSpanContext;
+    this.startTime = Date.now();
+    this.storage = storage;
+    this.onEnd = onEnd;
+  }
+
+  setAttribute(key: string, value: unknown): void {
+    this.attributes[key] = value as any;
+  }
+
+  addEvent(name: string, attributes?: Record<string, unknown>): void {
+    // 事件暂时存储在 attributes 中
+    const events = (this.attributes as any)._events as Array<{ name: string; attributes?: Record<string, unknown> }> || [];
+    events.push({ name, attributes });
+    (this.attributes as any)._events = events;
+  }
+
+  end(result?: unknown, error?: Error): void {
+    this.endTime = Date.now();
+    if (error) {
+      this.error = error.message;
+    }
+
+    // 保存到存储
+    // 注意：parentSpanId 来自 spanContext.parentSpanId，这是 startSpan 时设置的正确值
+    this.storage.save({
+      traceId: this.spanContext.traceId,
+      spanId: this.spanContext.spanId,
+      parentSpanId: this.spanContext.parentSpanId,
+      name: this.name,
+      kind: this.kind as any,
+      status: error ? SpanStatus.ERROR : SpanStatus.OK,
+      startTime: this.startTime!,
+      endTime: this.endTime,
+      attributes: this.attributes,
+      result,
+      error: this.error,
+    });
+
+    // 调用回调（用于上下文恢复等）
+    this.onEnd?.();
+  }
+}
+
+// ============================================================================
+// Tracer Implementation
+// ============================================================================
+
+/**
+ * OTel Tracer 实现
+ */
+class OTelTracerImpl implements OTelTracer {
+  readonly name: string;
+  readonly version?: string;
+  
+  private storage: SpanStorage;
+  private currentContext: SpanContext | undefined;
+  private activeSpans: Map<string, OTelSpan> = new Map();
+  private onSpanEndCallback?: SpanEndCallback;
+  
+  // 引用到 Provider，用于访问全局 context
+  private provider: OTelTracerProvider;
+
+  constructor(name: string, version: string | undefined, storage: SpanStorage, provider: OTelTracerProvider) {
+    this.name = name;
+    this.version = version;
+    this.storage = storage;
+    this.provider = provider;
+  }
+
+  /**
+   * 设置 span 结束时的回调
+   */
+  setOnSpanEndCallback(callback: SpanEndCallback): void {
+    this.onSpanEndCallback = callback;
+  }
+
+  /**
+   * 获取当前 tracer 的活跃 span 数量（用于调试）
+   */
+  getActiveSpanCount(): number {
+    return this.activeSpans.size;
+  }
+
+  /**
+   * 启动新 Span
+   * 
+   * parentSpanId 确定逻辑：
+   * 1. 跨进程场景（options.parent 显式指定）：
+   *    → options.parent.parentSpanId || options.parent.spanId
+   * 2. 同进程嵌套（隐式继承 currentContext）：
+   *    → currentContext.spanId（忽略 currentContext.parentSpanId）
+   * 3. 无父上下文：parentSpanId = undefined
+   * 
+   * 关键：currentContext.parentSpanId 是当前 span 的父 span，不应该作为新 span 的父 span
+   */
+  startSpan(name: string, options?: SpanOptions): OTelSpan {
+    // 确定 traceId 和 parentContext
+    // 优先级：
+    // 1. options.parent 显式传入（即使值是 undefined）
+    // 2. 当前 tracer 的 currentContext
+    // 3. Provider 全局 context（所有 tracer 共享）
+    // 4. 自动生成新的 traceId
+    const parentFromOptions = options?.parent;
+    // 使用 'in' 操作符检查 parent 是否在 options 中被显式设置
+    const hasExplicitParent = options && 'parent' in options;
+    const globalContext = this.provider.getGlobalContext();
+    
+    // 确定有效的 parent context
+    // 如果显式传入了 parent（即使值是 undefined），优先使用
+    // 否则使用当前 tracer 的 currentContext
+    // 如果都没有，使用全局 context
+    let effectiveParentContext: SpanContext | undefined;
+    if (hasExplicitParent) {
+      // parent 显式传入，使用它（可能是 undefined）
+      effectiveParentContext = parentFromOptions;
+    } else if (this.currentContext) {
+      effectiveParentContext = this.currentContext;
+    } else if (globalContext) {
+      // 全局 context 存在但当前 tracer 没有 context
+      // 使用全局 context 作为 parent
+      effectiveParentContext = globalContext;
+    }
+    
+    const traceId = effectiveParentContext?.traceId || this.generateTraceId();
+    const spanId = this.generateSpanId();
+    
+    // parentSpanId 确定：
+    // 1. 显式 options.parent（跨进程场景）：优先用 parentSpanId
+    // 2. 隐式继承 currentContext（同进程嵌套）：只用 effectiveParentContext.spanId
+    // 3. 无父上下文：undefined
+    let parentSpanId: string | undefined;
+    if (hasExplicitParent && parentFromOptions) {
+      // 跨进程场景：显式传递 parent
+      parentSpanId = parentFromOptions.parentSpanId || parentFromOptions.spanId;
+    } else if (this.currentContext) {
+      // 同进程嵌套：继承 currentContext，忽略 currentContext.parentSpanId
+      parentSpanId = this.currentContext.spanId;
+    } else if (globalContext) {
+      // 使用全局 context 作为 parent
+      parentSpanId = globalContext.spanId;
+    }
+
+    // ⚠️ 关键：创建独立的 spanContext 对象，而不是修改现有对象
+    // 因为 parent?.spanId 可能指向 currentContext.spanContext（span 的 spanContext）
+    // 如果直接赋值，parentContext.spanContext.spanId 会被修改
+    // 使用对象展开确保创建新对象
+    const spanContext = {
+      traceId,
+      spanId,
+      parentSpanId,
+    } as SpanContext;
+
+    // ⚠️ 关键：在创建 Span 之前，先更新 currentContext
+    // 这样子 span 获取 parent 时，currentContext 已经是当前 span 的上下文
+    // 而不是被新 span 的上下文覆盖
+    this.currentContext = {
+      traceId,
+      spanId,
+      parentSpanId,
+    };
+
+    // 创建 Span，传递完整的父上下文（用于存储和上下文恢复）
+    const span = new OTelSpanImpl(
+      name,
+      spanContext,
+      this.storage,
+      effectiveParentContext, // 传递完整父上下文
+      () => this.handleSpanEnd(spanContext.spanId, effectiveParentContext?.spanId)
+    );
+
+    // 设置初始属性
+    if (options?.attributes) {
+      for (const [key, value] of Object.entries(options.attributes)) {
+        span.setAttribute(key, value);
+      }
+    }
+
+    this.activeSpans.set(spanId, span);
+
+    return span;
+  }
+
+  /**
+   * 将当前上下文注入到环境变量
+   */
+  injectToEnv(env: Record<string, string | undefined>): void {
+    if (this.currentContext) {
+      propagation.inject(env, this.currentContext);
+    }
+  }
+
+  /**
+   * 获取当前上下文
+   */
+  getCurrentContext(): SpanContext | undefined {
+    return this.currentContext;
+  }
+
+  /**
+   * 设置当前上下文（用于从外部恢复上下文）
+   */
+  setCurrentContext(context: SpanContext | undefined): void {
+    this.currentContext = context;
+  }
+
+  /**
+   * 结束 Span 并恢复父上下文
+   * 
+   * 关键：需要正确恢复 parentSpanId，使得子 span 可以正确关联到父 span
+   * 
+   * 跨进程场景处理：
+   * - 如果父 span 不存在（可能在另一个进程中），保留 traceId
+   * - 这样子进程创建的 span 能继承 traceId，而不是创建新的根节点
+   * 
+   * @returns 结束后的父上下文（用于恢复之前的上下文）
+   */
+  endSpan(span: OTelSpan): SpanContext | undefined {
+    const spanContext = span.spanContext;
+    this.activeSpans.delete(spanContext.spanId);
+
+    // 保存当前 span 的 traceId（如果存在）
+    const currentTraceId = this.currentContext?.traceId;
+
+    if (spanContext.parentSpanId) {
+      // 尝试找到父 Span 并恢复其上下文
+      const parentSpan = this.activeSpans.get(spanContext.parentSpanId);
+      if (parentSpan) {
+        // 正确恢复完整上下文：包含 parentSpanId（父 span 的 spanId）
+        const parentContext: SpanContext = {
+          traceId: spanContext.traceId,
+          spanId: parentSpan.spanContext.spanId,
+          parentSpanId: parentSpan.spanContext.parentSpanId,
+        };
+        this.currentContext = parentContext;
+        return parentContext;
+      }
+      
+      // 父 span 不存在（跨进程场景）
+      // 保留 traceId，让后续 span 能继承，而不是创建新的根
+      if (currentTraceId) {
+        const parentContext: SpanContext = {
+          traceId: currentTraceId,
+          spanId: spanContext.parentSpanId,
+          parentSpanId: undefined,
+        };
+        this.currentContext = parentContext;
+        return parentContext;
+      }
+    }
+    
+    // 当前 span 没有父 span，清除上下文
+    this.currentContext = undefined;
+    return undefined;
+  }
+
+  generateTraceId(): string {
+    // 生成 32 字符的十六进制 traceId (128 位)
+    const timestamp = Date.now().toString(16).padStart(12, "0");
+    const random = Array.from({ length: 5 }, () => 
+      Math.floor(Math.random() * 0xFFFFFFFF).toString(16).padStart(8, "0")
+    ).join("");
+    return (timestamp + random).slice(0, 32).padStart(32, "0");
+  }
+
+  generateSpanId(): string {
+    // 生成 16 字符的十六进制 spanId (64 位)
+    return Math.floor(Math.random() * 0xFFFFFFFFFFFFFFFF)
+      .toString(16)
+      .padStart(16, "0");
+  }
+
+  /**
+   * 处理 span 结束
+   * 
+   * 当 span 结束时，尝试恢复父 span 的上下文。
+   * 如果当前 span 的父 span 仍然活跃，则恢复父上下文。
+   * 
+   * 跨进程场景处理：
+   * - 如果父 span 不存在（可能在另一个进程中），保留 traceId
+   * - 这样子进程创建的 span 能继承 traceId，而不是创建新的根节点
+   * 
+   * 关键：需要正确恢复 parentSpanId，使得后续 span 可以正确关联
+   */
+  private handleSpanEnd(spanId: string, parentSpanId?: string): void {
+    this.activeSpans.delete(spanId);
+
+    // 保存当前 span 的 traceId（如果存在）
+    const currentTraceId = this.currentContext?.traceId;
+
+    if (parentSpanId) {
+      // 如果父 span 仍然活跃，恢复父上下文
+      const parentSpan = this.activeSpans.get(parentSpanId);
+      if (parentSpan) {
+        this.currentContext = {
+          traceId: parentSpan.spanContext.traceId,
+          spanId: parentSpan.spanContext.spanId,
+          parentSpanId: parentSpan.spanContext.parentSpanId,
+        };
+        return;
+      }
+      
+      // 父 span 不存在（跨进程场景）
+      // 保留 traceId，让后续 span 能继承，而不是创建新的根
+      // parentSpanId 设为 undefined，因为父 span 已经结束
+      if (currentTraceId) {
+        this.currentContext = {
+          traceId: currentTraceId,
+          spanId: parentSpanId, // 保留父 span ID 作为参考
+          parentSpanId: undefined,
+        };
+        return;
+      }
+    }
+    
+    // 当前 span 没有父 span，清除上下文
+    this.currentContext = undefined;
+  }
+}
+
+// ============================================================================
+// TracerProvider Implementation
+// ============================================================================
+
+/**
+ * OpenTelemetry TracerProvider
+ * 
+ * 全局 Tracer 管理器，负责：
+ * - 维护 Tracer 缓存
+ * - 管理存储
+ * - 处理上下文初始化
+ * - 提供全局 context 供所有 tracer 共享
+ */
+export class OTelTracerProvider {
+  private tracers: Map<string, OTelTracerImpl> = new Map();
+  private storage: SpanStorage;
+  private initialized = false;
+  
+  // 全局 context - 所有 tracer 共享
+  // 用于在不同的 tracer 实例之间传递 traceId
+  private globalContext: SpanContext | undefined;
+
+  constructor(storage?: SpanStorage, dbPath?: string) {
+    this.storage = storage || new SQLiteSpanStorage(dbPath || getDefaultDbPath());
+  }
+
+  /**
+   * 初始化 Provider
+   * 
+   * 从环境变量恢复上下文（如 TRACEPARENT）
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    await this.storage.initialize();
+    this.initialized = true;
+  }
+
+  /**
+   * 检查是否已初始化
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * 获取全局 context（所有 tracer 共享）
+   */
+  getGlobalContext(): SpanContext | undefined {
+    return this.globalContext;
+  }
+
+  /**
+   * 设置全局 context（所有 tracer 共享）
+   */
+  setGlobalContext(context: SpanContext | undefined): void {
+    this.globalContext = context;
+  }
+
+  /**
+   * 获取 Tracer
+   */
+  getTracer(name: string, version?: string): OTelTracer {
+    const key = `${name}@${version || "0.0.0"}`;
+    
+    let tracer = this.tracers.get(key);
+    if (!tracer) {
+      tracer = new OTelTracerImpl(name, version, this.storage, this);
+      this.tracers.set(key, tracer);
+
+      // 检查环境变量中是否有父上下文（仅在初始化后）
+      if (this.initialized) {
+        this.restoreFromEnv(tracer);
+      }
+    }
+
+    return tracer;
+  }
+
+  /**
+   * 从环境变量恢复上下文
+   */
+  private restoreFromEnv(tracer: OTelTracerImpl): void {
+    const extracted = propagation.extract(process.env as Record<string, string | undefined>);
+    if (extracted) {
+      // 恢复上下文：设置 spanId 为发送方的 spanId，作为后续 span 的 parentSpanId
+      tracer.setCurrentContext({
+        traceId: extracted.traceId,
+        spanId: extracted.spanId, // 发送方 span ID，用于后续 span 的 parentSpanId
+        parentSpanId: undefined, // 根 span 没有父
+      });
+    }
+  }
+
+  /**
+   * 关闭 Provider
+   */
+  shutdown(): void {
+    for (const tracer of this.tracers.values()) {
+      // 结束所有活跃的 span
+    }
+    this.tracers.clear();
+    this.storage.close();
+    this.initialized = false;
+    // 清除全局 context，确保下次创建 tracer 时不会继承旧上下文
+    this.globalContext = undefined;
+    // 清除环境变量中的 trace context，避免影响后续测试
+    delete process.env['TRACEPARENT'];
+    delete process.env['TRACE_ID'];
+    delete process.env['LOG_TRACE_REQUEST_ID'];
+  }
+
+  /**
+   * 获取存储
+   */
+  getStorage(): SpanStorage {
+    return this.storage;
+  }
+}
+
+// ============================================================================
+// Singleton
+// ============================================================================
+
+let providerInstance: OTelTracerProvider | null = null;
+
+/**
+ * 获取 TracerProvider 单例
+ */
+export function getTracerProvider(): OTelTracerProvider {
+  if (!providerInstance) {
+    providerInstance = new OTelTracerProvider();
+  }
+  return providerInstance;
+}
+
+/**
+ * 重置 TracerProvider（用于测试）
+ */
+export function resetTracerProvider(): void {
+  if (providerInstance) {
+    providerInstance.shutdown();
+    providerInstance = null;
+  }
+}
+
+/**
+ * 获取默认的 SQLite 数据库路径
+ */
+function getDefaultDbPath(): string {
+  const os = require("os");
+  const path = require("path");
+  const home = os.homedir();
+  const dataHome = process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
+  return path.join(dataHome, "roy-agent", "traces.db");
+}