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

package/dist/core/src/env/log-trace/opentelemetry/propagation.test.js

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview W3C TraceContext Propagation 测试
+ *
+ * 测试 W3C TraceContext 标准的 traceparent 格式：
+ * - 注入 (inject): 将 SpanContext 序列化到环境变量
+ * - 提取 (extract): 从环境变量反序列化 SpanContext
+ * - 序列化 (serialize): SpanContext -> traceparent 字符串
+ * - 反序列化 (parse): traceparent 字符串 -> SpanContext
+ */
+import { describe, test, expect } from 'bun:test';
+import { propagation, serialize, parse, } from "./propagation.js";
+describe('propagation', () => {
+    describe('serialize', () => {
+        test('should serialize basic SpanContext to traceparent format', () => {
+            const context = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: 'b7ad6b7169203331',
+                parentSpanId: undefined,
+            };
+            const result = serialize(context);
+            // W3C TraceContext: 使用 spanId 而非 parentSpanId
+            expect(result).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+        });
+        test('should serialize SpanContext with parentSpanId', () => {
+            const context = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: 'b7ad6b7169203331',
+                parentSpanId: 'a1b2c3d4e5f67890',
+            };
+            const result = serialize(context);
+            // W3C TraceContext: 使用 spanId 而非 parentSpanId
+            expect(result).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+        });
+        test('should pad traceId to 32 characters', () => {
+            const context = {
+                traceId: '1',
+                spanId: 'b7ad6b7169203331',
+                parentSpanId: undefined,
+            };
+            const result = serialize(context);
+            // traceId "1" should be padded to "00000000000000000000000000000001"
+            expect(result).toMatch(/^00-0{31}1-/);
+        });
+        test('should pad spanId to 16 characters', () => {
+            const context = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: '1',
+                parentSpanId: undefined,
+            };
+            const result = serialize(context);
+            // spanId "1" should be padded to "0000000000000001"
+            expect(result).toMatch(/-0{15}1-01$/);
+        });
+    });
+    describe('parse', () => {
+        test('should parse valid traceparent string', () => {
+            const traceparent = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01';
+            const result = parse(traceparent);
+            expect(result).toBeDefined();
+            expect(result.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+            // parse returns ExtractedContext: spanId is the sender's spanId
+            expect(result.spanId).toBe('b7ad6b7169203331');
+        });
+        test('should parse traceparent string', () => {
+            const traceparent = '00-0af7651916cd43dd8448eb211c80319c-a1b2c3d4e5f67890-01';
+            const result = parse(traceparent);
+            expect(result).toBeDefined();
+            expect(result.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+            expect(result.spanId).toBe('a1b2c3d4e5f67890');
+        });
+        test('should return undefined for invalid traceparent format', () => {
+            const invalidTraceparent = 'invalid-format';
+            const result = parse(invalidTraceparent);
+            expect(result).toBeUndefined();
+        });
+        test('should return undefined for wrong version', () => {
+            const wrongVersion = '01-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01';
+            const result = parse(wrongVersion);
+            expect(result).toBeUndefined();
+        });
+        test('should return undefined for traceId wrong length', () => {
+            const wrongLength = '00-0af7651916cd43dd8448eb211c80319-b7ad6b7169203331-01';
+            const result = parse(wrongLength);
+            expect(result).toBeUndefined();
+        });
+        test('should return undefined for spanId wrong length', () => {
+            const wrongLength = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b716920333-01';
+            const result = parse(wrongLength);
+            expect(result).toBeUndefined();
+        });
+    });
+    describe('inject', () => {
+        test('should inject SpanContext to carrier', () => {
+            const carrier = {};
+            const context = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: 'b7ad6b7169203331',
+                parentSpanId: undefined,
+            };
+            propagation.inject(carrier, context);
+            expect(carrier['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+        });
+        test('should inject with parentSpanId', () => {
+            const carrier = {};
+            const context = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: 'b7ad6b7169203331',
+                parentSpanId: 'a1b2c3d4e5f67890',
+            };
+            propagation.inject(carrier, context);
+            // W3C TraceContext: inject uses spanId (sender's span ID)
+            expect(carrier['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+        });
+        test('should overwrite existing TRACEPARENT', () => {
+            const carrier = {
+                TRACEPARENT: '00-old-trace-old-span-old-flags',
+            };
+            const context = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: 'b7ad6b7169203331',
+            };
+            propagation.inject(carrier, context);
+            expect(carrier['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+        });
+    });
+    describe('extract', () => {
+        test('should extract SpanContext from carrier', () => {
+            const carrier = {
+                TRACEPARENT: '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01',
+            };
+            const result = propagation.extract(carrier);
+            expect(result).toBeDefined();
+            expect(result.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+            // extract returns ExtractedContext: spanId is sender's spanId
+            expect(result.spanId).toBe('b7ad6b7169203331');
+        });
+        test('should extract with spanId', () => {
+            const carrier = {
+                TRACEPARENT: '00-0af7651916cd43dd8448eb211c80319c-a1b2c3d4e5f67890-01',
+            };
+            const result = propagation.extract(carrier);
+            expect(result).toBeDefined();
+            expect(result.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+            expect(result.spanId).toBe('a1b2c3d4e5f67890');
+        });
+        test('should return undefined when TRACEPARENT not present', () => {
+            const carrier = {};
+            const result = propagation.extract(carrier);
+            expect(result).toBeUndefined();
+        });
+        test('should return undefined for invalid TRACEPARENT', () => {
+            const carrier = {
+                TRACEPARENT: 'invalid-traceparent',
+            };
+            const result = propagation.extract(carrier);
+            expect(result).toBeUndefined();
+        });
+        test('should handle lowercase traceparent', () => {
+            const carrier = {
+                TRACEPARENT: '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01',
+            };
+            const result = propagation.extract(carrier);
+            expect(result).toBeDefined();
+            expect(result.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+        });
+    });
+    describe('roundtrip', () => {
+        test('should serialize and parse back to same values (traceId and parentSpanId)', () => {
+            const original = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: 'b7ad6b7169203331',
+                parentSpanId: 'a1b2c3d4e5f67890',
+            };
+            const serialized = serialize(original);
+            const parsed = parse(serialized);
+            // parse returns ExtractedContext: spanId is sender's spanId
+            expect(parsed).toBeDefined();
+            expect(parsed.traceId).toBe(original.traceId);
+            expect(parsed.spanId).toBe(original.spanId);
+        });
+        test('should inject and extract back to same values', () => {
+            const original = {
+                traceId: '0af7651916cd43dd8448eb211c80319c',
+                spanId: 'b7ad6b7169203331',
+                parentSpanId: 'a1b2c3d4e5f67890',
+            };
+            const carrier = {};
+            propagation.inject(carrier, original);
+            const extracted = propagation.extract(carrier);
+            // extract returns ExtractedContext (without spanId)
+            expect(extracted).toBeDefined();
+            expect(extracted.traceId).toBe(original.traceId);
+            expect(extracted.spanId).toBe(original.spanId); // injected uses spanId
+        });
+    });
+});
+//# sourceMappingURL=propagation.test.js.map

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

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview OTelTracerImpl 上下文管理测试
+ *
+ * 验证 OTelTracerImpl 的 startSpan/endSpan 正确维护 currentContext
+ * 以及嵌套 span 的父子关系建立
+ */
+export {};
+//# sourceMappingURL=tracer-provider-context.test.d.ts.map

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

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview OTelTracerImpl 上下文管理测试
+ *
+ * 验证 OTelTracerImpl 的 startSpan/endSpan 正确维护 currentContext
+ * 以及嵌套 span 的父子关系建立
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { getTracerProvider, resetTracerProvider, } from "./tracer-provider.js";
+import { join } from 'path';
+describe('OTelTracerImpl Context Management', () => {
+    const dbPath = join('/tmp', `test-otel-context-${Date.now()}.db`);
+    beforeEach(() => {
+        resetTracerProvider();
+    });
+    afterEach(() => {
+        resetTracerProvider();
+    });
+    describe('startSpan/endSpan context lifecycle', () => {
+        test('should set currentContext after startSpan', async () => {
+            const provider = getTracerProvider();
+            await provider.initialize();
+            const tracer = provider.getTracer('test-context');
+            const span = tracer.startSpan('test-span');
+            expect(tracer.getCurrentContext()).toBeDefined();
+            expect(tracer.getCurrentContext().traceId).toBeDefined();
+            expect(tracer.getCurrentContext().spanId).toBe(span.spanContext.spanId);
+        });
+        test('should clear currentContext after endSpan', async () => {
+            const provider = getTracerProvider();
+            await provider.initialize();
+            const tracer = provider.getTracer('test-context');
+            const span = tracer.startSpan('test-span');
+            expect(tracer.getCurrentContext()).toBeDefined();
+            // 调用 end 方法
+            span.end();
+            // 对于根 span，end 后 currentContext 应该为 undefined
+            expect(tracer.getCurrentContext()).toBeUndefined();
+        });
+        test('should maintain currentContext after endSpan when parent exists', async () => {
+            const provider = getTracerProvider();
+            await provider.initialize();
+            const tracer = provider.getTracer('test-context');
+            // 创建父 span
+            const parentSpan = tracer.startSpan('parent');
+            const parentContext = tracer.getCurrentContext();
+            expect(parentContext).toBeDefined();
+            // 创建子 span
+            const childSpan = tracer.startSpan('child');
+            expect(tracer.getCurrentContext().spanId).toBe(childSpan.spanContext.spanId);
+            expect(tracer.getCurrentContext().parentSpanId).toBe(parentSpan.spanContext.spanId);
+            // 结束子 span，应该恢复到父上下文
+            childSpan.end();
+            // ⚠️ 这里会失败，因为当前实现有问题
+            expect(tracer.getCurrentContext().spanId).toBe(parentSpan.spanContext.spanId);
+            expect(tracer.getCurrentContext().parentSpanId).toBe(parentContext.parentSpanId);
+        });
+    });
+    describe('nested span parent-child relationship', () => {
+        test('should create child span with correct parentSpanId', async () => {
+            const provider = getTracerProvider();
+            await provider.initialize();
+            const tracer = provider.getTracer('test-nested');
+            // 父 span
+            const parentSpan = tracer.startSpan('parent');
+            const parentSpanId = parentSpan.spanContext.spanId;
+            const traceId = parentSpan.spanContext.traceId;
+            // 子 span - 应该继承 traceId，parentSpanId 指向父 span
+            const childSpan = tracer.startSpan('child');
+            expect(childSpan.spanContext.traceId).toBe(traceId);
+            expect(childSpan.spanContext.parentSpanId).toBe(parentSpanId);
+        });
+        test('should build correct span tree in storage', async () => {
+            const provider = getTracerProvider();
+            await provider.initialize();
+            const tracer = provider.getTracer('test-tree');
+            const storage = provider.getStorage();
+            // 创建嵌套 span
+            const parent = tracer.startSpan('parent');
+            const parentId = parent.spanContext.spanId;
+            const parentTraceId = parent.spanContext.traceId;
+            const child1 = tracer.startSpan('child1');
+            child1.end();
+            const child2 = tracer.startSpan('child2');
+            child2.end();
+            parent.end();
+            // 验证存储中的 span - SQLiteSpanStorage 返回树结构根节点
+            // 需要直接查询所有 span
+            const rootSpans = storage.findByTraceId(parentTraceId);
+            // 树中应该有 1 个根 span（parent），children 包含 child1 和 child2
+            expect(rootSpans.length).toBeGreaterThanOrEqual(1);
+            const parentStored = rootSpans.find(s => s.spanId === parentId);
+            expect(parentStored).toBeDefined();
+            // 根 span 的 parentSpanId 应该是 undefined 或 null
+            expect(parentStored.parentSpanId || undefined).toBeUndefined();
+            // 验证子 span 存在（通过 flatten）
+            function flattenSpans(span) {
+                const result = [];
+                if (span.children) {
+                    for (const child of span.children) {
+                        result.push(child);
+                        result.push(...flattenSpans(child));
+                    }
+                }
+                return result;
+            }
+            const flatSpans = rootSpans.flatMap(s => [s, ...flattenSpans(s)]);
+            expect(flatSpans.length).toBeGreaterThanOrEqual(3);
+        });
+    });
+    describe('async span context', () => {
+        test('should maintain context across async boundaries', async () => {
+            const provider = getTracerProvider();
+            await provider.initialize();
+            const tracer = provider.getTracer('test-async');
+            const span = tracer.startSpan('async-parent');
+            const traceId = span.spanContext.traceId;
+            // 在异步操作中
+            await new Promise(resolve => setTimeout(resolve, 10));
+            // 应该仍然能访问到相同的 traceId
+            const currentContext = tracer.getCurrentContext();
+            expect(currentContext).toBeDefined();
+            expect(currentContext.traceId).toBe(traceId);
+            span.end();
+        });
+    });
+});
+//# sourceMappingURL=tracer-provider-context.test.js.map

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

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview OpenTelemetry TracerProvider 实现
+ *
+ * 提供 OpenTelemetry 风格的追踪能力：
+ * - TracerProvider: 全局 Tracer 管理器
+ * - OTelTracer: 具体 Tracer 实现
+ * - OTelSpan: Span 实现
+ *
+ * 支持 W3C TraceContext 格式的跨进程上下文传递
+ */
+import type { SpanContext, SpanAttributes } from "../types";
+import { type SpanStorage } from "../span-storage";
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * OpenTelemetry TracerProvider
+ *
+ * 全局 Tracer 管理器，负责：
+ * - 维护 Tracer 缓存
+ * - 管理存储
+ * - 处理上下文初始化
+ * - 提供全局 context 供所有 tracer 共享
+ */
+export declare class OTelTracerProvider {
+    private tracers;
+    private storage;
+    private initialized;
+    private globalContext;
+    constructor(storage?: SpanStorage, dbPath?: string);
+    /**
+     * 初始化 Provider
+     *
+     * 从环境变量恢复上下文（如 TRACEPARENT）
+     */
+    initialize(): Promise<void>;
+    /**
+     * 检查是否已初始化
+     */
+    isInitialized(): boolean;
+    /**
+     * 获取全局 context（所有 tracer 共享）
+     */
+    getGlobalContext(): SpanContext | undefined;
+    /**
+     * 设置全局 context（所有 tracer 共享）
+     */
+    setGlobalContext(context: SpanContext | undefined): void;
+    /**
+     * 获取 Tracer
+     */
+    getTracer(name: string, version?: string): OTelTracer;
+    /**
+     * 从环境变量恢复上下文
+     */
+    private restoreFromEnv;
+    /**
+     * 关闭 Provider
+     */
+    shutdown(): void;
+    /**
+     * 获取存储
+     */
+    getStorage(): SpanStorage;
+}
+/**
+ * 获取 TracerProvider 单例
+ */
+export declare function getTracerProvider(): OTelTracerProvider;
+/**
+ * 重置 TracerProvider（用于测试）
+ */
+export declare function resetTracerProvider(): void;
+//# sourceMappingURL=tracer-provider.d.ts.map