@ai-setting/roy-agent-core 1.3.9 → 1.3.11

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

@@ -1,612 +0,0 @@
-/**
- * @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");
-}