@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/utils/registeredTraceHelpers.ts

@@ -1,251 +0,0 @@
-/**
- * Helper utilities for working with RegisteredTrace
- *
- * These helpers provide convenient access to scope and match information
- * from the multi-resource, multi-scope RegisteredTrace structure.
- */
-
-import type {
-  RegisteredTrace,
-  ScenarioMatch,
-  StoryboardMatch,
-  UnmatchedSpan,
-} from '../types/registered-trace';
-
-/**
- * Scope information extracted from trace or match
- */
-export interface ScopeInfo {
-  name: string;
-  version: string;
-}
-
-/**
- * Get scope info from a ScenarioMatch
- */
-export function getScopeFromScenarioMatch(match: ScenarioMatch): ScopeInfo {
-  return {
-    name: match.scopeName,
-    version: match.scopeVersion || 'unknown',
-  };
-}
-
-/**
- * Get scope info from a StoryboardMatch
- */
-export function getScopeFromStoryboardMatch(match: StoryboardMatch): ScopeInfo {
-  return {
-    name: match.scopeName,
-    version: match.scopeVersion || 'unknown',
-  };
-}
-
-/**
- * Get scope info from an UnmatchedSpan
- */
-export function getScopeFromUnmatchedSpan(span: UnmatchedSpan): ScopeInfo {
-  return {
-    name: span.scopeName,
-    version: span.scopeVersion || 'unknown',
-  };
-}
-
-/**
- * Get primary scope from trace resources
- * Returns the first scope from the first resource
- */
-export function getPrimaryScope(trace: RegisteredTrace): ScopeInfo | null {
-  const firstScope = trace.resources?.[0]?.scopes?.[0];
-  if (!firstScope) return null;
-  return {
-    name: firstScope.scope.name,
-    version: firstScope.scope.version || 'unknown',
-  };
-}
-
-/**
- * Get all unique scopes from trace resources
- * Deduplicates by scope name
- */
-export function getAllScopes(trace: RegisteredTrace): ScopeInfo[] {
-  const scopeMap = new Map<string, ScopeInfo>();
-
-  for (const resource of trace.resources || []) {
-    for (const scopeInfo of resource.scopes || []) {
-      // Use name as key for deduplication
-      if (!scopeMap.has(scopeInfo.scope.name)) {
-        scopeMap.set(scopeInfo.scope.name, {
-          name: scopeInfo.scope.name,
-          version: scopeInfo.scope.version || 'unknown',
-        });
-      }
-    }
-  }
-
-  return Array.from(scopeMap.values());
-}
-
-/**
- * Get all unique scopes that have scenario matches
- * These are scopes where spans fully matched workflows and scenarios
- */
-export function getMatchedScopes(trace: RegisteredTrace): ScopeInfo[] {
-  const scopeMap = new Map<string, ScopeInfo>();
-
-  for (const match of trace.scenarioMatches || []) {
-    if (!scopeMap.has(match.scopeName)) {
-      scopeMap.set(match.scopeName, {
-        name: match.scopeName,
-        version: match.scopeVersion || 'unknown',
-      });
-    }
-  }
-
-  return Array.from(scopeMap.values());
-}
-
-/**
- * Get all unique scopes that have storyboard matches (partial matches)
- * These are scopes where spans matched workflows but not scenarios
- */
-export function getPartialMatchedScopes(trace: RegisteredTrace): ScopeInfo[] {
-  const scopeMap = new Map<string, ScopeInfo>();
-
-  for (const match of trace.storyboardMatches || []) {
-    if (!scopeMap.has(match.scopeName)) {
-      scopeMap.set(match.scopeName, {
-        name: match.scopeName,
-        version: match.scopeVersion || 'unknown',
-      });
-    }
-  }
-
-  return Array.from(scopeMap.values());
-}
-
-/**
- * Get all unique scopes from unmatched spans
- */
-export function getUnmatchedScopes(trace: RegisteredTrace): ScopeInfo[] {
-  const scopeMap = new Map<string, ScopeInfo>();
-
-  for (const span of trace.unmatchedSpans?.spans || []) {
-    if (!scopeMap.has(span.scopeName)) {
-      scopeMap.set(span.scopeName, {
-        name: span.scopeName,
-        version: span.scopeVersion || 'unknown',
-      });
-    }
-  }
-
-  return Array.from(scopeMap.values());
-}
-
-/**
- * Find scope info by name from trace resources
- */
-export function findScopeByName(
-  trace: RegisteredTrace,
-  scopeName: string
-): ScopeInfo | null {
-  for (const resource of trace.resources || []) {
-    for (const scopeInfo of resource.scopes || []) {
-      if (scopeInfo.scope.name === scopeName) {
-        return {
-          name: scopeInfo.scope.name,
-          version: scopeInfo.scope.version || 'unknown',
-        };
-      }
-    }
-  }
-  return null;
-}
-
-/**
- * Get span count for a specific scope
- */
-export function getSpanCountForScope(
-  trace: RegisteredTrace,
-  scopeName: string
-): number {
-  let count = 0;
-
-  for (const resource of trace.resources || []) {
-    for (const scopeInfo of resource.scopes || []) {
-      if (scopeInfo.scope.name === scopeName) {
-        count += scopeInfo.spanIds.length;
-      }
-    }
-  }
-
-  return count;
-}
-
-/**
- * Get the scope with the most spans (likely the "primary" scope)
- */
-export function getScopeWithMostSpans(trace: RegisteredTrace): ScopeInfo | null {
-  let maxSpans = 0;
-  let primaryScope: ScopeInfo | null = null;
-
-  for (const resource of trace.resources || []) {
-    for (const scopeInfo of resource.scopes || []) {
-      const spanCount = scopeInfo.spanIds.length;
-      if (spanCount > maxSpans) {
-        maxSpans = spanCount;
-        primaryScope = {
-          name: scopeInfo.scope.name,
-          version: scopeInfo.scope.version || 'unknown',
-        };
-      }
-    }
-  }
-
-  return primaryScope;
-}
-
-/**
- * Check if a scope has any matches (scenario or storyboard)
- */
-export function scopeHasMatches(
-  trace: RegisteredTrace,
-  scopeName: string
-): boolean {
-  const hasScenarioMatch = trace.scenarioMatches?.some(
-    (m) => m.scopeName === scopeName
-  );
-  const hasStoryboardMatch = trace.storyboardMatches?.some(
-    (m) => m.scopeName === scopeName
-  );
-
-  return hasScenarioMatch || hasStoryboardMatch || false;
-}
-
-/**
- * Get match summary for a scope
- */
-export function getScopeMatchSummary(
-  trace: RegisteredTrace,
-  scopeName: string
-): {
-  scenarioMatches: number;
-  storyboardMatches: number;
-  unmatchedSpans: number;
-  totalSpans: number;
-} {
-  const scenarioMatches =
-    trace.scenarioMatches?.filter((m) => m.scopeName === scopeName).length || 0;
-  const storyboardMatches =
-    trace.storyboardMatches?.filter((m) => m.scopeName === scopeName).length || 0;
-  const unmatchedSpans =
-    trace.unmatchedSpans?.spans.filter((s) => s.scopeName === scopeName).length ||
-    0;
-  const totalSpans = getSpanCountForScope(trace, scopeName);
-
-  return {
-    scenarioMatches,
-    storyboardMatches,
-    unmatchedSpans,
-    totalSpans,
-  };
-}

package/src/utils/traceAggregation.test.ts

@@ -1,385 +0,0 @@
-import { describe, it, expect } from 'bun:test';
-import { groupSpansByTrace } from './traceAggregation';
-import type { OtelResourceSpansData } from '../types/otel';
-
-describe('groupSpansByTrace', () => {
-  it('should group spans by trace ID', () => {
-    const resourceSpans: OtelResourceSpansData[] = [
-      {
-        resource: {
-          attributes: [
-            { key: 'service.name', value: { stringValue: 'checkout-api' } },
-          ],
-        },
-        scopeSpans: [
-          {
-            scope: { name: 'test-tracer', version: '1.0.0' },
-            spans: [
-              {
-                traceId: 'trace1',
-                spanId: 'span1',
-                name: 'GET /api/checkout',
-                kind: 2,
-                startTimeUnixNano: '1737835200000000000',
-                endTimeUnixNano: '1737835200100000000',
-                attributes: [],
-                events: [],
-                status: { code: 1 },
-              },
-              {
-                traceId: 'trace1',
-                spanId: 'span2',
-                parentSpanId: 'span1',
-                name: 'query database',
-                kind: 3,
-                startTimeUnixNano: '1737835200010000000',
-                endTimeUnixNano: '1737835200090000000',
-                attributes: [],
-                events: [],
-                status: { code: 1 },
-              },
-            ],
-          },
-        ],
-      },
-    ];
-
-    const traces = groupSpansByTrace(resourceSpans);
-
-    expect(traces).toHaveLength(1);
-    expect(traces[0].traceId).toBe('trace1');
-    expect(traces[0].spanCount).toBe(2);
-    expect(traces[0].name).toBe('GET /api/checkout'); // root span name
-  });
-
-  it('should calculate trace duration correctly', () => {
-    const resourceSpans: OtelResourceSpansData[] = [
-      {
-        resource: {
-          attributes: [{ key: 'service.name', value: { stringValue: 'api' } }],
-        },
-        scopeSpans: [
-          {
-            scope: { name: 'test', version: '1.0.0' },
-            spans: [
-              {
-                traceId: 'trace1',
-                spanId: 'span1',
-                name: 'operation',
-                kind: 2,
-                startTimeUnixNano: '1000000000000', // 1000ms = 1 second
-                endTimeUnixNano: '1000100000000', // 100ms later
-                attributes: [],
-                events: [],
-                status: { code: 1 },
-              },
-              {
-                traceId: 'trace1',
-                spanId: 'span2',
-                name: 'operation2',
-                kind: 2,
-                startTimeUnixNano: '1000050000000', // 50ms after start
-                endTimeUnixNano: '1000200000000', // 200ms after start
-                attributes: [],
-                events: [],
-                status: { code: 1 },
-              },
-            ],
-          },
-        ],
-      },
-    ];
-
-    const traces = groupSpansByTrace(resourceSpans);
-
-    expect(traces[0].startTime).toBe(1000000); // earliest start
-    expect(traces[0].duration).toBe(200); // 200ms duration
-  });
-
-  it('should detect errors in traces', () => {
-    const resourceSpans: OtelResourceSpansData[] = [
-      {
-        resource: {
-          attributes: [{ key: 'service.name', value: { stringValue: 'api' } }],
-        },
-        scopeSpans: [
-          {
-            scope: { name: 'test', version: '1.0.0' },
-            spans: [
-              {
-                traceId: 'trace1',
-                spanId: 'span1',
-                name: 'success',
-                kind: 2,
-                startTimeUnixNano: '1000000000',
-                endTimeUnixNano: '2000000000',
-                attributes: [],
-                events: [],
-                status: { code: 1 }, // OK
-              },
-              {
-                traceId: 'trace1',
-                spanId: 'span2',
-                name: 'error',
-                kind: 2,
-                startTimeUnixNano: '1000000000',
-                endTimeUnixNano: '2000000000',
-                attributes: [],
-                events: [],
-                status: { code: 2 }, // ERROR
-              },
-            ],
-          },
-        ],
-      },
-    ];
-
-    const traces = groupSpansByTrace(resourceSpans);
-
-    expect(traces[0].hasErrors).toBe(true);
-  });
-
-  it('should extract service names from resources', () => {
-    const resourceSpans: OtelResourceSpansData[] = [
-      {
-        resource: {
-          attributes: [
-            { key: 'service.name', value: { stringValue: 'checkout-api' } },
-          ],
-        },
-        scopeSpans: [
-          {
-            scope: { name: 'test', version: '1.0.0' },
-            spans: [
-              {
-                traceId: 'trace1',
-                spanId: 'span1',
-                name: 'op1',
-                kind: 2,
-                startTimeUnixNano: '1000000000',
-                endTimeUnixNano: '2000000000',
-                attributes: [],
-                events: [],
-                status: { code: 1 },
-              },
-            ],
-          },
-        ],
-      },
-      {
-        resource: {
-          attributes: [
-            { key: 'service.name', value: { stringValue: 'payment-service' } },
-          ],
-        },
-        scopeSpans: [
-          {
-            scope: { name: 'test', version: '1.0.0' },
-            spans: [
-              {
-                traceId: 'trace1',
-                spanId: 'span2',
-                name: 'op2',
-                kind: 3,
-                startTimeUnixNano: '1000000000',
-                endTimeUnixNano: '2000000000',
-                attributes: [],
-                events: [],
-                status: { code: 1 },
-              },
-            ],
-          },
-        ],
-      },
-    ];
-
-    const traces = groupSpansByTrace(resourceSpans);
-
-    expect(traces[0].serviceNames).toContain('checkout-api');
-    expect(traces[0].serviceNames).toContain('payment-service');
-    expect(traces[0].serviceNames).toHaveLength(2);
-  });
-
-  it('should extract workflow matching metadata', () => {
-    const resourceSpans: OtelResourceSpansData[] = [
-      {
-        resource: {
-          attributes: [
-            { key: 'service.name', value: { stringValue: 'api' } },
-            { key: 'pv.storyboard.id', value: { stringValue: 'storyboard-1' } },
-            {
-              key: 'pv.storyboard.name',
-              value: { stringValue: 'Checkout Flow' },
-            },
-            { key: 'pv.workflow.id', value: { stringValue: 'workflow-1' } },
-            { key: 'pv.workflow.name', value: { stringValue: 'Happy Path' } },
-            { key: 'pv.scenario.id', value: { stringValue: 'scenario-1' } },
-            {
-              key: 'pv.scenario.name',
-              value: { stringValue: 'Successful Payment' },
-            },
-          ],
-        },
-        scopeSpans: [
-          {
-            scope: { name: 'test', version: '1.0.0' },
-            spans: [
-              {
-                traceId: 'trace1',
-                spanId: 'span1',
-                name: 'operation',
-                kind: 2,
-                startTimeUnixNano: '1000000000',
-                endTimeUnixNano: '2000000000',
-                attributes: [],
-                events: [],
-                status: { code: 1 },
-              },
-            ],
-          },
-        ],
-      },
-    ];
-
-    const traces = groupSpansByTrace(resourceSpans);
-
-    expect(traces[0].matchedWorkflow).toBeDefined();
-    expect(traces[0].matchedWorkflow?.storyboardId).toBe('storyboard-1');
-    expect(traces[0].matchedWorkflow?.storyboardName).toBe('Checkout Flow');
-    expect(traces[0].matchedWorkflow?.workflowId).toBe('workflow-1');
-    expect(traces[0].matchedWorkflow?.workflowName).toBe('Happy Path');
-    expect(traces[0].matchedWorkflow?.scenarioId).toBe('scenario-1');
-    expect(traces[0].matchedWorkflow?.scenarioName).toBe('Successful Payment');
-  });
-
-  it('should not extract workflow metadata if storyboard fields are missing', () => {
-    const resourceSpans: OtelResourceSpansData[] = [
-      {
-        resource: {
-          attributes: [
-            { key: 'service.name', value: { stringValue: 'api' } },
-            { key: 'pv.workflow.id', value: { stringValue: 'workflow-1' } },
-          ],
-        },
-        scopeSpans: [
-          {
-            scope: { name: 'test', version: '1.0.0' },
-            spans: [
-              {
-                traceId: 'trace1',
-                spanId: 'span1',
-                name: 'operation',
-                kind: 2,
-                startTimeUnixNano: '1000000000',
-                endTimeUnixNano: '2000000000',
-                attributes: [],
-                events: [],
-                status: { code: 1 },
-              },
-            ],
-          },
-        ],
-      },
-    ];
-
-    const traces = groupSpansByTrace(resourceSpans);
-
-    expect(traces[0].matchedWorkflow).toBeUndefined();
-  });
-
-  it('should handle multiple traces', () => {
-    const resourceSpans: OtelResourceSpansData[] = [
-      {
-        resource: {
-          attributes: [{ key: 'service.name', value: { stringValue: 'api' } }],
-        },
-        scopeSpans: [
-          {
-            scope: { name: 'test', version: '1.0.0' },
-            spans: [
-              {
-                traceId: 'trace1',
-                spanId: 'span1',
-                name: 'op1',
-                kind: 2,
-                startTimeUnixNano: '1000000000',
-                endTimeUnixNano: '2000000000',
-                attributes: [],
-                events: [],
-                status: { code: 1 },
-              },
-              {
-                traceId: 'trace2',
-                spanId: 'span2',
-                name: 'op2',
-                kind: 2,
-                startTimeUnixNano: '3000000000',
-                endTimeUnixNano: '4000000000',
-                attributes: [],
-                events: [],
-                status: { code: 1 },
-              },
-            ],
-          },
-        ],
-      },
-    ];
-
-    const traces = groupSpansByTrace(resourceSpans);
-
-    expect(traces).toHaveLength(2);
-    // Should be sorted by start time (newest first)
-    expect(traces[0].traceId).toBe('trace2');
-    expect(traces[1].traceId).toBe('trace1');
-  });
-
-  it('should handle empty resource spans', () => {
-    const traces = groupSpansByTrace([]);
-    expect(traces).toEqual([]);
-  });
-
-  it('should identify root span correctly', () => {
-    const resourceSpans: OtelResourceSpansData[] = [
-      {
-        resource: {
-          attributes: [{ key: 'service.name', value: { stringValue: 'api' } }],
-        },
-        scopeSpans: [
-          {
-            scope: { name: 'test', version: '1.0.0' },
-            spans: [
-              {
-                traceId: 'trace1',
-                spanId: 'span2',
-                parentSpanId: 'span1',
-                name: 'child operation',
-                kind: 3,
-                startTimeUnixNano: '1000000000',
-                endTimeUnixNano: '2000000000',
-                attributes: [],
-                events: [],
-                status: { code: 1 },
-              },
-              {
-                traceId: 'trace1',
-                spanId: 'span1',
-                name: 'root operation',
-                kind: 2,
-                startTimeUnixNano: '1000000000',
-                endTimeUnixNano: '3000000000',
-                attributes: [],
-                events: [],
-                status: { code: 1 },
-              },
-            ],
-          },
-        ],
-      },
-    ];
-
-    const traces = groupSpansByTrace(resourceSpans);
-
-    expect(traces[0].name).toBe('root operation');
-    expect(traces[0].rootSpanId).toBe('span1');
-  });
-});