@ai-setting/roy-agent-cli 1.3.15 → 1.3.17

package/dist/core/src/env/log-trace/opentelemetry/tracer-provider.js

@@ -0,0 +1,451 @@
+/**
+ * @fileoverview OpenTelemetry TracerProvider 实现
+ *
+ * 提供 OpenTelemetry 风格的追踪能力：
+ * - TracerProvider: 全局 Tracer 管理器
+ * - OTelTracer: 具体 Tracer 实现
+ * - OTelSpan: Span 实现
+ *
+ * 支持 W3C TraceContext 格式的跨进程上下文传递
+ */
+import { SQLiteSpanStorage } from "../span-storage.js";
+import { propagation } from "./propagation.js";
+import { SpanStatus } from "../types.js";
+// ============================================================================
+// Span Implementation
+// ============================================================================
+/**
+ * OTel Span 实现
+ */
+class OTelSpanImpl {
+    name;
+    kind;
+    spanContext;
+    attributes = {};
+    startTime;
+    endTime;
+    error;
+    storage;
+    parentSpanContext;
+    onEnd;
+    constructor(name, spanContext, storage, parentSpanContext, onEnd) {
+        this.name = name;
+        this.kind = "internal";
+        this.spanContext = spanContext;
+        this.parentSpanContext = parentSpanContext;
+        this.startTime = Date.now();
+        this.storage = storage;
+        this.onEnd = onEnd;
+    }
+    setAttribute(key, value) {
+        this.attributes[key] = value;
+    }
+    addEvent(name, attributes) {
+        // 事件暂时存储在 attributes 中
+        const events = this.attributes._events || [];
+        events.push({ name, attributes });
+        this.attributes._events = events;
+    }
+    end(result, error) {
+        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,
+            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 {
+    name;
+    version;
+    storage;
+    currentContext;
+    activeSpans = new Map();
+    onSpanEndCallback;
+    // 引用到 Provider，用于访问全局 context
+    provider;
+    constructor(name, version, storage, provider) {
+        this.name = name;
+        this.version = version;
+        this.storage = storage;
+        this.provider = provider;
+    }
+    /**
+     * 设置 span 结束时的回调
+     */
+    setOnSpanEndCallback(callback) {
+        this.onSpanEndCallback = callback;
+    }
+    /**
+     * 获取当前 tracer 的活跃 span 数量（用于调试）
+     */
+    getActiveSpanCount() {
+        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, options) {
+        // 确定 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;
+        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;
+        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,
+        };
+        // ⚠️ 关键：在创建 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) {
+        if (this.currentContext) {
+            propagation.inject(env, this.currentContext);
+        }
+    }
+    /**
+     * 获取当前上下文
+     */
+    getCurrentContext() {
+        return this.currentContext;
+    }
+    /**
+     * 设置当前上下文（用于从外部恢复上下文）
+     */
+    setCurrentContext(context) {
+        this.currentContext = context;
+    }
+    /**
+     * 结束 Span 并恢复父上下文
+     *
+     * 关键：需要正确恢复 parentSpanId，使得子 span 可以正确关联到父 span
+     *
+     * 跨进程场景处理：
+     * - 如果父 span 不存在（可能在另一个进程中），保留 traceId
+     * - 这样子进程创建的 span 能继承 traceId，而不是创建新的根节点
+     *
+     * @returns 结束后的父上下文（用于恢复之前的上下文）
+     */
+    endSpan(span) {
+        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 = {
+                    traceId: spanContext.traceId,
+                    spanId: parentSpan.spanContext.spanId,
+                    parentSpanId: parentSpan.spanContext.parentSpanId,
+                };
+                this.currentContext = parentContext;
+                return parentContext;
+            }
+            // 父 span 不存在（跨进程场景）
+            // 保留 traceId，让后续 span 能继承，而不是创建新的根
+            if (currentTraceId) {
+                const parentContext = {
+                    traceId: currentTraceId,
+                    spanId: spanContext.parentSpanId,
+                    parentSpanId: undefined,
+                };
+                this.currentContext = parentContext;
+                return parentContext;
+            }
+        }
+        // 当前 span 没有父 span，清除上下文
+        this.currentContext = undefined;
+        return undefined;
+    }
+    generateTraceId() {
+        // 生成 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() {
+        // 生成 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 可以正确关联
+     */
+    handleSpanEnd(spanId, parentSpanId) {
+        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 {
+    tracers = new Map();
+    storage;
+    initialized = false;
+    // 全局 context - 所有 tracer 共享
+    // 用于在不同的 tracer 实例之间传递 traceId
+    globalContext;
+    constructor(storage, dbPath) {
+        this.storage = storage || new SQLiteSpanStorage(dbPath || getDefaultDbPath());
+    }
+    /**
+     * 初始化 Provider
+     *
+     * 从环境变量恢复上下文（如 TRACEPARENT）
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        await this.storage.initialize();
+        this.initialized = true;
+    }
+    /**
+     * 检查是否已初始化
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * 获取全局 context（所有 tracer 共享）
+     */
+    getGlobalContext() {
+        return this.globalContext;
+    }
+    /**
+     * 设置全局 context（所有 tracer 共享）
+     */
+    setGlobalContext(context) {
+        this.globalContext = context;
+    }
+    /**
+     * 获取 Tracer
+     */
+    getTracer(name, version) {
+        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;
+    }
+    /**
+     * 从环境变量恢复上下文
+     */
+    restoreFromEnv(tracer) {
+        const extracted = propagation.extract(process.env);
+        if (extracted) {
+            // 恢复上下文：设置 spanId 为发送方的 spanId，作为后续 span 的 parentSpanId
+            tracer.setCurrentContext({
+                traceId: extracted.traceId,
+                spanId: extracted.spanId, // 发送方 span ID，用于后续 span 的 parentSpanId
+                parentSpanId: undefined, // 根 span 没有父
+            });
+        }
+    }
+    /**
+     * 关闭 Provider
+     */
+    shutdown() {
+        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() {
+        return this.storage;
+    }
+}
+// ============================================================================
+// Singleton
+// ============================================================================
+let providerInstance = null;
+/**
+ * 获取 TracerProvider 单例
+ */
+export function getTracerProvider() {
+    if (!providerInstance) {
+        providerInstance = new OTelTracerProvider();
+    }
+    return providerInstance;
+}
+/**
+ * 重置 TracerProvider（用于测试）
+ */
+export function resetTracerProvider() {
+    if (providerInstance) {
+        providerInstance.shutdown();
+        providerInstance = null;
+    }
+}
+/**
+ * 获取默认的 SQLite 数据库路径
+ */
+function getDefaultDbPath() {
+    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");
+}
+//# sourceMappingURL=tracer-provider.js.map

package/dist/core/src/env/log-trace/opentelemetry/tracer-provider.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview OTelTracerProvider 测试
+ *
+ * 测试 OpenTelemetry TracerProvider 实现：
+ * - 单例模式
+ * - 获取 Tracer
+ * - 启动/结束 Span
+ * - 上下文注入环境变量
+ */
+export {};
+//# sourceMappingURL=tracer-provider.test.d.ts.map