@principal-ai/subsystems-core 0.29.0 → 0.30.0

package/src/parsers/OtlpTraceParser.ts

@@ -1,401 +0,0 @@
-/**
- * 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

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