@principal-ai/subsystems-core 0.29.0

package/src/parsers/OtlpTraceParser.ts

@@ -0,0 +1,401 @@
+/**
+ * OTLP Trace Parser
+ *
+ * Extracts structured data from OTLP traces for scope-based matching.
+ *
+ * Responsibilities:
+ * - Extract resources (service info, attributes)
+ * - Extract scopes (instrumentation libraries)
+ * - Map spans to their scopes
+ * - Extract span events
+ * - Convert OTLP timestamps and IDs to usable formats
+ */
+
+import type {
+  OtelExportTraceServiceRequest,
+  OtelResourceSpansData,
+  OtelScopeSpans,
+  OtelSpanData,
+  OtelSpanEvent,
+  OtelKeyValue,
+  OtelAnyValue,
+} from '../types/otel';
+import type { TraceResource } from '../types/registered-trace';
+
+/**
+ * Extracted span information
+ */
+export interface ExtractedSpan {
+  spanId: string;
+  spanName: string;
+  parentSpanId?: string;
+  traceId: string;
+  startTime: number; // milliseconds
+  endTime: number; // milliseconds
+  duration: number; // milliseconds
+  attributes: Record<string, unknown>;
+  events: ExtractedEvent[];
+  status: {
+    code: number;
+    message?: string;
+  };
+  scopeName: string; // Which scope this span belongs to
+}
+
+/**
+ * Extracted event information
+ */
+export interface ExtractedEvent {
+  name: string;
+  timestamp: number; // milliseconds
+  attributes: Record<string, unknown>;
+}
+
+/**
+ * Parser for OTLP traces
+ */
+export class OtlpTraceParser {
+  /**
+   * Extract all resources from OTLP trace
+   *
+   * Returns array of resources, each with their scopes and span mappings.
+   */
+  extractResources(otlpData: OtelExportTraceServiceRequest): TraceResource[] {
+    const resources: TraceResource[] = [];
+
+    for (const resourceSpan of otlpData.resourceSpans || []) {
+      const resource = this.extractResource(resourceSpan);
+      resources.push(resource);
+    }
+
+    return resources;
+  }
+
+  /**
+   * Extract single resource
+   */
+  private extractResource(resourceSpan: OtelResourceSpansData): TraceResource {
+    const attributes = this.convertAttributes(resourceSpan.resource.attributes);
+
+    // Extract service identifier (for routing)
+    const serviceIdentifier = this.extractServiceIdentifier(attributes);
+
+    // Extract service name
+    const serviceName = (attributes['service.name'] as string) || 'unknown';
+
+    // Extract all scopes within this resource
+    const scopes = this.extractScopes(resourceSpan.scopeSpans || []);
+
+    return {
+      serviceIdentifier,
+      serviceName,
+      attributes,
+      scopes,
+    };
+  }
+
+  /**
+   * Extract service identifier for routing
+   *
+   * Priority: dev.server.url > service.name
+   */
+  private extractServiceIdentifier(attributes: Record<string, unknown>): string {
+    return (
+      (attributes['dev.server.url'] as string) ||
+      (attributes['service.name'] as string) ||
+      'unknown'
+    );
+  }
+
+  /**
+   * Extract all scopes from scopeSpans
+   */
+  private extractScopes(
+    scopeSpans: OtelScopeSpans[]
+  ): TraceResource['scopes'] {
+    const scopes: TraceResource['scopes'] = [];
+
+    for (const scopeSpan of scopeSpans) {
+      const scope = scopeSpan.scope;
+      if (!scope) continue;
+
+      // Extract span IDs for this scope
+      const spanIds = scopeSpan.spans?.map((span) => span.spanId) || [];
+
+      scopes.push({
+        scope: {
+          name: scope.name,
+          version: scope.version || '0.0.0',
+          attributes: scope.attributes
+            ? this.convertAttributes(scope.attributes)
+            : undefined,
+          schemaUrl: scopeSpan.schemaUrl,
+        },
+        spanIds,
+      });
+    }
+
+    return scopes;
+  }
+
+  /**
+   * Get all spans for a specific scope
+   */
+  getSpansForScope(
+    otlpData: OtelExportTraceServiceRequest,
+    scopeName: string
+  ): ExtractedSpan[] {
+    const spans: ExtractedSpan[] = [];
+
+    for (const resourceSpan of otlpData.resourceSpans || []) {
+      for (const scopeSpan of resourceSpan.scopeSpans || []) {
+        if (scopeSpan.scope?.name === scopeName) {
+          for (const span of scopeSpan.spans || []) {
+            spans.push(this.extractSpan(span, scopeName));
+          }
+        }
+      }
+    }
+
+    return spans;
+  }
+
+  /**
+   * Extract span information
+   */
+  private extractSpan(span: OtelSpanData, scopeName: string): ExtractedSpan {
+    const startTime = this.nanoToMillis(span.startTimeUnixNano);
+    const endTime = this.nanoToMillis(span.endTimeUnixNano);
+
+    return {
+      spanId: span.spanId,
+      spanName: span.name,
+      parentSpanId: span.parentSpanId,
+      traceId: span.traceId,
+      startTime,
+      endTime,
+      duration: endTime - startTime,
+      attributes: this.convertAttributes(span.attributes),
+      events: this.extractEvents(span.events || []),
+      status: {
+        code: span.status.code,
+        message: span.status.message,
+      },
+      scopeName,
+    };
+  }
+
+  /**
+   * Extract events from span
+   */
+  extractEvents(events: OtelSpanEvent[]): ExtractedEvent[] {
+    return events.map((event) => ({
+      name: event.name,
+      timestamp: this.nanoToMillis(event.timeUnixNano),
+      attributes: this.convertAttributes(event.attributes || []),
+    }));
+  }
+
+  /**
+   * Extract basic trace information
+   */
+  extractTraceInfo(otlpData: OtelExportTraceServiceRequest): {
+    traceId: string;
+    name: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    spanCount: number;
+    hasErrors: boolean;
+  } {
+    const traceId = this.extractTraceId(otlpData);
+    const name = this.extractTraceName(otlpData);
+    const { startTime, endTime } = this.extractTimeRange(otlpData);
+    const spanCount = this.countSpans(otlpData);
+    const hasErrors = this.detectErrors(otlpData);
+
+    return {
+      traceId,
+      name,
+      startTime,
+      endTime,
+      duration: endTime - startTime,
+      spanCount,
+      hasErrors,
+    };
+  }
+
+  /**
+   * Extract trace ID
+   */
+  private extractTraceId(otlpData: OtelExportTraceServiceRequest): string {
+    const firstSpan = otlpData.resourceSpans?.[0]?.scopeSpans?.[0]?.spans?.[0];
+    return firstSpan?.traceId || 'unknown';
+  }
+
+  /**
+   * Extract trace name (root span name)
+   */
+  private extractTraceName(otlpData: OtelExportTraceServiceRequest): string {
+    // Find root span (no parentSpanId) or use first span
+    const allSpans = this.getAllSpans(otlpData);
+    const rootSpan = allSpans.find((s) => !s.parentSpanId) || allSpans[0];
+    return rootSpan?.name || 'Unknown Trace';
+  }
+
+  /**
+   * Extract time range across all spans
+   */
+  private extractTimeRange(otlpData: OtelExportTraceServiceRequest): {
+    startTime: number;
+    endTime: number;
+  } {
+    let minStart = Number.MAX_SAFE_INTEGER;
+    let maxEnd = 0;
+
+    for (const resourceSpan of otlpData.resourceSpans || []) {
+      for (const scopeSpan of resourceSpan.scopeSpans || []) {
+        for (const span of scopeSpan.spans || []) {
+          const start = this.nanoToMillis(span.startTimeUnixNano);
+          const end = this.nanoToMillis(span.endTimeUnixNano);
+          if (start < minStart) minStart = start;
+          if (end > maxEnd) maxEnd = end;
+        }
+      }
+    }
+
+    return {
+      startTime: minStart === Number.MAX_SAFE_INTEGER ? Date.now() : minStart,
+      endTime: maxEnd || Date.now(),
+    };
+  }
+
+  /**
+   * Count total spans
+   */
+  private countSpans(otlpData: OtelExportTraceServiceRequest): number {
+    let count = 0;
+    for (const resourceSpan of otlpData.resourceSpans || []) {
+      for (const scopeSpan of resourceSpan.scopeSpans || []) {
+        count += scopeSpan.spans?.length || 0;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Detect if any span has errors
+   */
+  private detectErrors(otlpData: OtelExportTraceServiceRequest): boolean {
+    for (const resourceSpan of otlpData.resourceSpans || []) {
+      for (const scopeSpan of resourceSpan.scopeSpans || []) {
+        for (const span of scopeSpan.spans || []) {
+          if (span.status.code === 2) {
+            // ERROR
+            return true;
+          }
+        }
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Get all spans from trace (flattened)
+   */
+  private getAllSpans(otlpData: OtelExportTraceServiceRequest): OtelSpanData[] {
+    const spans: OtelSpanData[] = [];
+    for (const resourceSpan of otlpData.resourceSpans || []) {
+      for (const scopeSpan of resourceSpan.scopeSpans || []) {
+        spans.push(...(scopeSpan.spans || []));
+      }
+    }
+    return spans;
+  }
+
+  /**
+   * Convert OTLP attributes to simple key-value record
+   */
+  convertAttributes(attrs: OtelKeyValue[]): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+
+    for (const attr of attrs || []) {
+      const value = this.extractAttributeValue(attr.value);
+      if (value !== undefined) {
+        result[attr.key] = value;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Extract value from OTLP AnyValue
+   */
+  private extractAttributeValue(value: OtelAnyValue): unknown {
+    if (value.stringValue !== undefined) return value.stringValue;
+    if (value.intValue !== undefined) return value.intValue;
+    if (value.doubleValue !== undefined) return value.doubleValue;
+    if (value.boolValue !== undefined) return value.boolValue;
+
+    // Handle complex types
+    if (value.arrayValue) {
+      return value.arrayValue.values.map((v) => this.extractAttributeValue(v));
+    }
+
+    if (value.kvlistValue) {
+      const obj: Record<string, unknown> = {};
+      for (const kv of value.kvlistValue.values) {
+        obj[kv.key] = this.extractAttributeValue(kv.value);
+      }
+      return obj;
+    }
+
+    if (value.bytesValue) {
+      return value.bytesValue;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Convert nanoseconds to milliseconds
+   */
+  private nanoToMillis(nanos: string | number): number {
+    if (!nanos) return 0;
+    const nanosNum = typeof nanos === 'string' ? parseInt(nanos, 10) : nanos;
+    return Math.floor(nanosNum / 1_000_000);
+  }
+
+  /**
+   * Check if trace is in local development mode
+   */
+  isLocalDevelopment(otlpData: OtelExportTraceServiceRequest): boolean {
+    const resources = this.extractResources(otlpData);
+
+    for (const resource of resources) {
+      // Check for dev.mode flag
+      if (resource.attributes?.['dev.mode'] === true) {
+        return true;
+      }
+
+      // Check for dev workspace path
+      if (resource.attributes?.['dev.workspace.path']) {
+        return true;
+      }
+
+      // Check for dev version patterns in scopes
+      for (const { scope } of resource.scopes) {
+        if (
+          scope.version?.includes('-dev') ||
+          scope.version?.includes('-local') ||
+          scope.version === '0.0.0-dev'
+        ) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+}

package/src/parsers/__tests__/OtlpTraceParser.test.ts

@@ -0,0 +1,197 @@
+/**
+ * Tests for OtlpTraceParser
+ */
+
+import { describe, it, expect } from 'bun:test';
+import { OtlpTraceParser } from '../OtlpTraceParser';
+import type { OtelExportTraceServiceRequest } from '../../types/otel';
+
+describe('OtlpTraceParser', () => {
+  const parser = new OtlpTraceParser();
+
+  // Sample OTLP trace with multiple scopes
+  const sampleTrace: OtelExportTraceServiceRequest = {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [
+            { key: 'service.name', value: { stringValue: 'web-ade' } },
+            { key: 'dev.server.url', value: { stringValue: 'http://localhost:3000' } },
+          ],
+        },
+        scopeSpans: [
+          {
+            scope: {
+              name: 'web-ade-instrumentation',
+              version: '1.0.0',
+            },
+            spans: [
+              {
+                traceId: 'trace123',
+                spanId: 'span1',
+                name: 'handleCheckout',
+                kind: 1,
+                startTimeUnixNano: '1000000000',
+                endTimeUnixNano: '2000000000',
+                attributes: [
+                  { key: 'http.method', value: { stringValue: 'POST' } },
+                ],
+                events: [
+                  {
+                    timeUnixNano: '1500000000',
+                    name: 'checkout.started',
+                    attributes: [],
+                  },
+                ],
+                status: { code: 0 },
+              },
+            ],
+          },
+          {
+            scope: {
+              name: 'auth-library',
+              version: '2.1.0',
+            },
+            spans: [
+              {
+                traceId: 'trace123',
+                spanId: 'span2',
+                name: 'checkPermissions',
+                kind: 1,
+                startTimeUnixNano: '1200000000',
+                endTimeUnixNano: '1800000000',
+                attributes: [],
+                events: [],
+                status: { code: 0 },
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+
+  describe('extractResources', () => {
+    it('should extract all resources with scopes', () => {
+      const resources = parser.extractResources(sampleTrace);
+
+      expect(resources).toHaveLength(1);
+      expect(resources[0].serviceName).toBe('web-ade');
+      expect(resources[0].serviceIdentifier).toBe('http://localhost:3000');
+      expect(resources[0].scopes).toHaveLength(2);
+    });
+
+    it('should extract scope information correctly', () => {
+      const resources = parser.extractResources(sampleTrace);
+      const scopes = resources[0].scopes;
+
+      expect(scopes[0].scope.name).toBe('web-ade-instrumentation');
+      expect(scopes[0].scope.version).toBe('1.0.0');
+      expect(scopes[0].spanIds).toEqual(['span1']);
+
+      expect(scopes[1].scope.name).toBe('auth-library');
+      expect(scopes[1].scope.version).toBe('2.1.0');
+      expect(scopes[1].spanIds).toEqual(['span2']);
+    });
+  });
+
+  describe('getSpansForScope', () => {
+    it('should get spans for a specific scope', () => {
+      const spans = parser.getSpansForScope(sampleTrace, 'web-ade-instrumentation');
+
+      expect(spans).toHaveLength(1);
+      expect(spans[0].spanName).toBe('handleCheckout');
+      expect(spans[0].scopeName).toBe('web-ade-instrumentation');
+    });
+
+    it('should extract span events', () => {
+      const spans = parser.getSpansForScope(sampleTrace, 'web-ade-instrumentation');
+
+      expect(spans[0].events).toHaveLength(1);
+      expect(spans[0].events[0].name).toBe('checkout.started');
+    });
+
+    it('should convert timestamps from nano to millis', () => {
+      const spans = parser.getSpansForScope(sampleTrace, 'web-ade-instrumentation');
+
+      expect(spans[0].startTime).toBe(1000); // 1000000000 / 1000000
+      expect(spans[0].endTime).toBe(2000);
+      expect(spans[0].duration).toBe(1000);
+    });
+  });
+
+  describe('extractTraceInfo', () => {
+    it('should extract basic trace information', () => {
+      const info = parser.extractTraceInfo(sampleTrace);
+
+      expect(info.traceId).toBe('trace123');
+      expect(info.name).toBe('handleCheckout'); // First span
+      expect(info.spanCount).toBe(2);
+      expect(info.hasErrors).toBe(false);
+    });
+  });
+
+  describe('convertAttributes', () => {
+    it('should convert OTLP attributes to key-value record', () => {
+      const attrs = [
+        { key: 'string', value: { stringValue: 'hello' } },
+        { key: 'int', value: { intValue: 42 } },
+        { key: 'bool', value: { boolValue: true } },
+      ];
+
+      const result = parser.convertAttributes(attrs);
+
+      expect(result).toEqual({
+        string: 'hello',
+        int: 42,
+        bool: true,
+      });
+    });
+  });
+
+  describe('isLocalDevelopment', () => {
+    it('should detect dev.mode flag', () => {
+      const devTrace: OtelExportTraceServiceRequest = {
+        resourceSpans: [
+          {
+            resource: {
+              attributes: [
+                { key: 'dev.mode', value: { boolValue: true } },
+              ],
+            },
+            scopeSpans: [],
+          },
+        ],
+      };
+
+      expect(parser.isLocalDevelopment(devTrace)).toBe(true);
+    });
+
+    it('should detect dev version patterns', () => {
+      const devTrace: OtelExportTraceServiceRequest = {
+        resourceSpans: [
+          {
+            resource: {
+              attributes: [],
+            },
+            scopeSpans: [
+              {
+                scope: {
+                  name: 'test-service',
+                  version: '0.0.0-dev',
+                },
+                spans: [],
+              },
+            ],
+          },
+        ],
+      };
+
+      expect(parser.isLocalDevelopment(devTrace)).toBe(true);
+    });
+
+    it('should return false for production traces', () => {
+      expect(parser.isLocalDevelopment(sampleTrace)).toBe(false);
+    });
+  });
+});