@ai-setting/roy-agent-core 1.0.0

package/src/env/log-trace/opentelemetry/propagation.ts

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview W3C TraceContext Propagation
+ * 
+ * 实现 W3C Trace Context 标准中的 traceparent 格式：
+ * https://www.w3.org/TR/trace-context/#traceparent-header
+ * 
+ * 格式: 00-{traceId}-{parentSpanId}-{flags}
+ * - version: 2字符，固定 "00"
+ * - traceId: 32字符，128位追踪ID
+ * - parentSpanId: 16字符，64位父Span ID
+ * - flags: 2字符，采样标志（当前固定 "01"）
+ */
+
+import type { SpanContext } from "../types";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** W3C TraceContext 版本号 */
+const TRACE_CONTEXT_VERSION = "00";
+
+/** 采样标志（01 = sampled） */
+const TRACE_FLAGS_SAMPLED = "01";
+
+/** traceparent 字段名 */
+const TRACEPARENT_HEADER = "TRACEPARENT";
+
+/** 版本号长度 */
+const VERSION_LENGTH = 2;
+
+/** traceId 长度 */
+const TRACE_ID_LENGTH = 32;
+
+/** parentSpanId 长度 */
+const PARENT_SPAN_ID_LENGTH = 16;
+
+/** flags 长度 */
+const FLAGS_LENGTH = 2;
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * 左补零到指定长度
+ */
+function padLeft(str: string, length: number): string {
+  return str.padStart(length, "0");
+}
+
+/**
+ * 验证是否为有效的十六进制字符串
+ */
+function isValidHex(str: string): boolean {
+  return /^[0-9a-f]+$/i.test(str);
+}
+
+// ============================================================================
+// Serialization (SpanContext -> traceparent)
+// ============================================================================
+
+/**
+ * 将 SpanContext 序列化为 traceparent 字符串
+ * 
+ * W3C TraceContext 语义：
+ * - traceparent 中的 spanId 是"发送方 span"的 ID
+ * - 接收方会将其作为新 span 的 parentSpanId
+ * - 所以应该使用 context.spanId，而非 parentSpanId
+ * 
+ * @param context SpanContext
+ * @returns traceparent 格式字符串
+ */
+export function serialize(context: SpanContext): string {
+  const traceId = padLeft(context.traceId.toLowerCase(), TRACE_ID_LENGTH);
+  const spanId = padLeft(context.spanId.toLowerCase(), PARENT_SPAN_ID_LENGTH);
+
+  // 格式: 00-{traceId}-{spanId}-{flags}
+  // 注意：使用 spanId 而非 parentSpanId，因为这是发送方 span 的 ID
+  const parts = [
+    TRACE_CONTEXT_VERSION,
+    traceId,
+    spanId,
+    TRACE_FLAGS_SAMPLED,
+  ];
+
+  return parts.join("-");
+}
+
+// ============================================================================
+// Deserialization (traceparent -> SpanContext)
+// ============================================================================
+
+/**
+ * 提取的 Trace Context
+ * 
+ * W3C TraceContext 格式: 00-{traceId}-{spanId}-{flags}
+ * - {spanId} 是发送方 span 的 ID
+ * - 接收方应将其作为新 span 的 parentSpanId
+ */
+export interface ExtractedContext {
+  traceId: string;
+  /** 发送方 span 的 ID，接收方应作为新 span 的 parentSpanId */
+  spanId: string;
+}
+
+/**
+ * 将 traceparent 字符串反序列化为 ExtractedContext
+ * 
+ * W3C TraceContext 语义：
+ * - traceparent 中的 "span-id" 是发送方 span 的 ID
+ * - 接收方应该：
+ *   - 使用提取的 traceId
+ *   - 将提取的 spanId 作为 parentSpanId
+ *   - 生成自己的新 spanId
+ * 
+ * @param traceparent traceparent 格式字符串
+ * @returns 接收方 ExtractedContext 或 undefined（格式无效）
+ */
+export function parse(traceparent: string): ExtractedContext | undefined {
+  if (!traceparent || typeof traceparent !== "string") {
+    return undefined;
+  }
+
+  const trimmed = traceparent.trim();
+  const parts = trimmed.split("-");
+
+  // 必须有 4 个部分
+  if (parts.length !== 4) {
+    return undefined;
+  }
+
+  const [version, traceId, senderSpanId, flags] = parts;
+
+  // 验证版本（当前只支持 "00"）
+  if (version !== TRACE_CONTEXT_VERSION) {
+    // 未来版本兼容：对于 "ff" 及以上的未来版本，忽略
+    if (version > TRACE_CONTEXT_VERSION) {
+      return undefined;
+    }
+  }
+
+  // 验证 traceId 长度和格式
+  if (traceId.length !== TRACE_ID_LENGTH || !isValidHex(traceId)) {
+    return undefined;
+  }
+
+  // 验证 spanId 长度和格式（W3C 标准中叫 span-id，但这是发送方 span 的 ID）
+  if (senderSpanId.length !== PARENT_SPAN_ID_LENGTH || !isValidHex(senderSpanId)) {
+    return undefined;
+  }
+
+  // 验证 flags 长度（当前忽略 flags 值，只验证格式）
+  if (flags.length !== FLAGS_LENGTH || !isValidHex(flags)) {
+    return undefined;
+  }
+
+  // 返回提取的上下文
+  // - traceId: 保持不变
+  // - spanId: 发送方 span 的 ID（接收方应作为新 span 的 parentSpanId）
+  return {
+    traceId: traceId.toLowerCase(),
+    spanId: senderSpanId.toLowerCase(),
+  };
+}
+
+// ============================================================================
+// Propagation Interface
+// ============================================================================
+
+/**
+ * W3C TraceContext Propagation 实现
+ * 
+ * 用于在进程间传递 trace 上下文：
+ * - inject: 将 SpanContext 注入到 carrier（环境变量）
+ * - extract: 从 carrier（环境变量）提取 SpanContext
+ */
+export const propagation = {
+  /**
+   * 将 SpanContext 注入到 carrier
+   * 
+   * @param carrier 载体对象（通常是环境变量对象）
+   * @param context Span 上下文
+   */
+  inject(carrier: Record<string, string | undefined>, context: SpanContext): void {
+    carrier[TRACEPARENT_HEADER] = serialize(context);
+  },
+
+  /**
+   * 从 carrier 提取 SpanContext
+   * 
+   * @param carrier 载体对象（通常是环境变量对象）
+   * @returns ExtractedContext 或 undefined
+   */
+  extract(carrier: Record<string, string | undefined>): ExtractedContext | undefined {
+    const traceparent = carrier[TRACEPARENT_HEADER];
+    if (!traceparent) {
+      return undefined;
+    }
+    return parse(traceparent);
+  },
+
+  /**
+   * 获取 traceparent 字段名
+   */
+  getTraceparentHeader(): string {
+    return TRACEPARENT_HEADER;
+  },
+};
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type { SpanContext } from "../types";

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

@@ -0,0 +1,166 @@
+/**
+ * @fileoverview OTelTracerImpl 上下文管理测试
+ * 
+ * 验证 OTelTracerImpl 的 startSpan/endSpan 正确维护 currentContext
+ * 以及嵌套 span 的父子关系建立
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { 
+  OTelTracerProvider, 
+  getTracerProvider, 
+  resetTracerProvider,
+  type OTelTracer,
+  type OTelSpan,
+} from './tracer-provider';
+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: any): any[] {
+        const result: any[] = [];
+        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();
+    });
+  });
+});