@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/types/otel.ts

@@ -1,620 +0,0 @@
-/**
- * OpenTelemetry Types for Log Association and Trace Matching
- *
- * This module provides:
- * 1. Re-exports of official OTLP types from @opentelemetry/otlp-transformer
- * 2. Helper functions for working with OTLP data structures
- * 3. Application-level types (TraceInfo, WorkflowMatchInfo)
- * 4. Simplified types for logs and basic telemetry (backward compatible)
- *
- * @see https://opentelemetry.io/docs/specs/otel/protocol/otlp/
- * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/
- * @see https://opentelemetry.io/docs/specs/otel/resource/semantic_conventions/
- */
-
-// =============================================================================
-// OTLP Data Structures (JSON Format)
-// =============================================================================
-
-/**
- * OTLP attribute value
- *
- * Based on OTLP/JSON specification. Represents a single value which can be
- * a primitive type or a complex structure (array, key-value list).
- */
-export interface OtelAnyValue {
-  stringValue?: string;
-  intValue?: number;
-  doubleValue?: number;
-  boolValue?: boolean;
-  arrayValue?: { values: OtelAnyValue[] };
-  kvlistValue?: { values: OtelKeyValue[] };
-  bytesValue?: Uint8Array;
-}
-
-/**
- * OTLP key-value pair (attribute)
- */
-export interface OtelKeyValue {
-  key: string;
-  value: OtelAnyValue;
-}
-
-/**
- * OTLP resource
- *
- * Describes the entity producing telemetry (service, pod, host, etc.)
- */
-export interface OtelResourceData {
-  attributes: OtelKeyValue[];
-  droppedAttributesCount?: number;
-}
-
-/**
- * OTLP span event
- */
-export interface OtelSpanEvent {
-  timeUnixNano: string;
-  name: string;
-  attributes: OtelKeyValue[];
-  droppedAttributesCount?: number;
-}
-
-/**
- * OTLP span link
- */
-export interface OtelLink {
-  traceId: string | Uint8Array;
-  spanId: string | Uint8Array;
-  traceState?: string;
-  attributes: OtelKeyValue[];
-  droppedAttributesCount?: number;
-}
-
-/**
- * OTLP span status
- */
-export interface OtelSpanStatus {
-  code: number; // 0 = UNSET, 1 = OK, 2 = ERROR
-  message?: string;
-}
-
-/**
- * OTLP span
- *
- * Represents a unit of work in a distributed trace.
- */
-export interface OtelSpanData {
-  traceId: string;
-  spanId: string;
-  parentSpanId?: string;
-  name: string;
-  kind: number; // ESpanKind enum (0-5)
-  startTimeUnixNano: string;
-  endTimeUnixNano: string;
-  attributes: OtelKeyValue[];
-  droppedAttributesCount?: number;
-  events: OtelSpanEvent[];
-  droppedEventsCount?: number;
-  links?: OtelLink[];
-  droppedLinksCount?: number;
-  status: OtelSpanStatus;
-}
-
-/**
- * OTLP instrumentation scope
- */
-export interface OtelInstrumentationScope {
-  name: string;
-  version?: string;
-  attributes?: OtelKeyValue[];
-  droppedAttributesCount?: number;
-}
-
-/**
- * OTLP scope spans
- */
-export interface OtelScopeSpans {
-  scope?: OtelInstrumentationScope;
-  spans: OtelSpanData[];
-  schemaUrl?: string;
-}
-
-/**
- * OTLP resource spans
- */
-export interface OtelResourceSpansData {
-  resource: OtelResourceData;
-  scopeSpans: OtelScopeSpans[];
-  schemaUrl?: string;
-}
-
-/**
- * OTLP export trace service request
- */
-export interface OtelExportTraceServiceRequest {
-  resourceSpans: OtelResourceSpansData[];
-}
-
-// =============================================================================
-// Helper Functions for OTLP Data
-// =============================================================================
-
-/**
- * Extract string value from OTEL attribute value
- *
- * @param value - OTEL attribute value
- * @returns String value if present, undefined otherwise
- */
-export function getAttributeStringValue(value: OtelAnyValue): string | undefined {
-  return value.stringValue ?? undefined;
-}
-
-/**
- * Find attribute by key in attribute array
- *
- * @param attributes - Array of OTEL attributes
- * @param key - Attribute key to find
- * @returns Attribute if found, undefined otherwise
- */
-export function findAttribute(
-  attributes: OtelKeyValue[] | undefined,
-  key: string
-): OtelKeyValue | undefined {
-  return attributes?.find((attr) => attr.key === key);
-}
-
-/**
- * Get attribute value by key
- *
- * Supports string, number, and boolean values. For complex types
- * (arrays, maps), returns undefined.
- *
- * @param attributes - Array of OTEL attributes
- * @param key - Attribute key to get
- * @returns Attribute value if found and is a primitive type
- *
- * @example
- * ```typescript
- * const attrs: OtelKeyValue[] = [
- *   { key: 'http.method', value: { stringValue: 'GET' } },
- *   { key: 'http.status_code', value: { intValue: 200 } }
- * ];
- *
- * getAttributeValue(attrs, 'http.method'); // 'GET'
- * getAttributeValue(attrs, 'http.status_code'); // 200
- * ```
- */
-export function getAttributeValue(
-  attributes: OtelKeyValue[] | undefined,
-  key: string
-): string | number | boolean | undefined {
-  const attr = findAttribute(attributes, key);
-  if (!attr) return undefined;
-
-  return (
-    attr.value.stringValue ??
-    attr.value.intValue ??
-    attr.value.doubleValue ??
-    attr.value.boolValue ??
-    undefined
-  );
-}
-
-/**
- * Convert resource attributes to flat string map
- *
- * Only includes string-valued attributes. Useful for matching
- * and filtering operations.
- *
- * @param resource - OTEL resource
- * @returns Flat object with string key-value pairs
- *
- * @example
- * ```typescript
- * const resource: OtelResourceData = {
- *   attributes: [
- *     { key: 'service.name', value: { stringValue: 'checkout-api' } },
- *     { key: 'deployment.environment', value: { stringValue: 'production' } }
- *   ]
- * };
- *
- * flattenResourceAttributes(resource);
- * // { 'service.name': 'checkout-api', 'deployment.environment': 'production' }
- * ```
- */
-export function flattenResourceAttributes(resource: OtelResourceData): Record<string, string> {
-  const result: Record<string, string> = {};
-
-  if (!resource.attributes) return result;
-
-  for (const attr of resource.attributes) {
-    const value = getAttributeStringValue(attr.value);
-    if (value !== undefined) {
-      result[attr.key] = value;
-    }
-  }
-
-  return result;
-}
-
-/**
- * Parse OTEL nanosecond timestamp to milliseconds
- *
- * OTLP uses string representation for nanosecond timestamps in JSON format.
- * This converts them to JavaScript milliseconds (standard Date format).
- *
- * @param nanos - Nanosecond timestamp as string
- * @returns Milliseconds since Unix epoch
- *
- * @example
- * ```typescript
- * parseNanoTime('1737835200000000000'); // 1737835200000
- * ```
- */
-export function parseNanoTime(nanos: string | number): number {
-  const nanosNum = typeof nanos === 'string' ? parseInt(nanos, 10) : nanos;
-  return nanosNum / 1_000_000;
-}
-
-/**
- * Calculate span duration in milliseconds
- *
- * @param span - OTEL span
- * @returns Duration in milliseconds
- */
-export function getSpanDuration(span: OtelSpanData): number {
-  const start = parseInt(span.startTimeUnixNano, 10);
-  const end = parseInt(span.endTimeUnixNano, 10);
-  return (end - start) / 1_000_000;
-}
-
-// =============================================================================
-// Application-Level Types
-// =============================================================================
-
-/**
- * Workflow matching metadata extracted from trace resource attributes
- *
- * Traces can be correlated to storyboards, workflows, and scenarios
- * via resource attributes like pv.storyboard.id, pv.workflow.id, etc.
- */
-export interface WorkflowMatchInfo {
-  /** Storyboard ID */
-  storyboardId: string;
-  /** Storyboard name */
-  storyboardName: string;
-  /** Workflow ID (optional) */
-  workflowId?: string;
-  /** Workflow name (optional) */
-  workflowName?: string;
-  /** Scenario ID (optional) */
-  scenarioId?: string;
-  /** Scenario name (optional) */
-  scenarioName?: string;
-  /** Canvas node IDs that matched this trace */
-  matchedNodeIds?: string[];
-}
-
-/**
- * Aggregated trace information
- *
- * Represents a complete trace with metadata extracted from all its spans.
- * This is a higher-level view than individual spans, useful for trace lists,
- * filtering, and visualization.
- *
- * @example
- * ```typescript
- * const trace: TraceInfo = {
- *   traceId: 'abc123',
- *   name: 'POST /api/checkout',
- *   startTime: 1737835200000,
- *   duration: 150,
- *   spanCount: 5,
- *   serviceNames: ['checkout-api', 'payment-service'],
- *   hasErrors: false,
- *   rootSpanId: 'span1'
- * };
- * ```
- */
-export interface TraceInfo {
-  /** Trace ID */
-  traceId: string;
-  /** Trace name (usually root span name) */
-  name: string;
-  /** Start timestamp in milliseconds */
-  startTime: number;
-  /** Duration in milliseconds */
-  duration: number;
-  /** Number of spans in trace */
-  spanCount: number;
-  /** Unique service names across all spans */
-  serviceNames: string[];
-  /** True if any span has error status */
-  hasErrors: boolean;
-  /** Root span ID (if identifiable) */
-  rootSpanId?: string;
-  /** Workflow matching metadata (if matched) */
-  matchedWorkflow?: WorkflowMatchInfo;
-}
-
-// =============================================================================
-// Simplified Types (Backward Compatible)
-// =============================================================================
-
-/**
- * @deprecated Use IAnyValue and helper functions instead
- */
-
-/**
- * OpenTelemetry attribute value type per OTEL spec
- * @see https://opentelemetry.io/docs/specs/otel/common/attribute-naming/
- */
-export type OtelAttributeValue = string | number | boolean | string[] | number[] | boolean[];
-
-/**
- * OpenTelemetry attributes (key-value pairs)
- */
-export type OtelAttributes = Record<string, OtelAttributeValue>;
-
-/**
- * OTEL Resource - describes the entity producing telemetry
- *
- * Resources are immutable metadata about the source of telemetry.
- * Common attributes follow semantic conventions.
- *
- * @example
- * ```typescript
- * const resource: OtelResource = {
- *   'service.name': 'checkout-api',
- *   'service.namespace': 'checkout',
- *   'deployment.environment': 'production',
- *   'k8s.pod.name': 'checkout-api-7d8f9c6b5d-x2j4k'
- * };
- * ```
- */
-export interface OtelResource {
-  // Service identification (most common)
-  'service.name'?: string;
-  'service.namespace'?: string;
-  'service.instance.id'?: string;
-  'service.version'?: string;
-
-  // Kubernetes
-  'k8s.pod.name'?: string;
-  'k8s.pod.uid'?: string;
-  'k8s.deployment.name'?: string;
-  'k8s.namespace.name'?: string;
-  'k8s.node.name'?: string;
-  'k8s.container.name'?: string;
-  'k8s.replicaset.name'?: string;
-
-  // Cloud
-  'cloud.provider'?: string;
-  'cloud.region'?: string;
-  'cloud.availability_zone'?: string;
-  'cloud.account.id'?: string;
-
-  // Deployment
-  'deployment.environment'?: string;
-
-  // Host
-  'host.name'?: string;
-  'host.id'?: string;
-  'host.type'?: string;
-
-  // Process
-  'process.pid'?: number;
-  'process.executable.name'?: string;
-  'process.runtime.name'?: string;
-  'process.runtime.version'?: string;
-
-  // Database (for DB spans/logs)
-  'db.system'?: string;
-  'db.name'?: string;
-  'db.user'?: string;
-
-  // Messaging (for queue spans/logs)
-  'messaging.system'?: string;
-  'messaging.destination.name'?: string;
-
-  // Allow arbitrary attributes
-  [key: string]: string | number | boolean | undefined;
-}
-
-/**
- * OTEL Severity levels
- *
- * Can be either text names or numeric values (1-24).
- * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber
- */
-export type OtelSeverityText = 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
-export type OtelSeverityNumber =
-  | 1
-  | 2
-  | 3
-  | 4
-  | 5
-  | 6
-  | 7
-  | 8
-  | 9
-  | 10
-  | 11
-  | 12
-  | 13
-  | 14
-  | 15
-  | 16
-  | 17
-  | 18
-  | 19
-  | 20
-  | 21
-  | 22
-  | 23
-  | 24;
-export type OtelSeverity = OtelSeverityText | OtelSeverityNumber;
-
-/**
- * OTEL Log Record
- *
- * Represents a single log entry with resource context and optional trace correlation.
- *
- * @example
- * ```typescript
- * const log: OtelLog = {
- *   timestamp: Date.now(),
- *   severity: 'INFO',
- *   body: 'Payment processed successfully',
- *   resource: {
- *     'service.name': 'payment-service',
- *     'deployment.environment': 'production'
- *   },
- *   attributes: {
- *     'payment.id': 'pay_123',
- *     'payment.amount': 99.99
- *   },
- *   traceId: 'abc123',
- *   spanId: 'def456'
- * };
- * ```
- */
-export interface OtelLog {
-  /** Timestamp in milliseconds, nanoseconds, or ISO string */
-  timestamp: number | string;
-
-  /** Observed timestamp (when collector received it) */
-  observedTimestamp?: number | string;
-
-  /** Severity number (1-24) */
-  severity?: OtelSeverity;
-
-  /** Severity text (DEBUG, INFO, etc.) */
-  severityText?: string;
-
-  /** Log body - the actual message or structured content */
-  body: string | Record<string, unknown>;
-
-  /** Resource describing the source entity */
-  resource: OtelResource;
-
-  /** Log attributes (structured data specific to this log) */
-  attributes?: OtelAttributes;
-
-  /** Trace ID for correlation */
-  traceId?: string;
-
-  /** Span ID for correlation */
-  spanId?: string;
-
-  /** Trace flags */
-  traceFlags?: number;
-
-  /**
-   * Source location (for path-based matching)
-   * This extends OTEL with source file information for code coverage analysis.
-   */
-  source?: {
-    file?: string;
-    line?: number;
-    function?: string;
-  };
-}
-
-/**
- * OTEL Span Kind
- */
-export type OtelSpanKind = 'INTERNAL' | 'SERVER' | 'CLIENT' | 'PRODUCER' | 'CONSUMER';
-
-/**
- * OTEL Span Status (simplified, for backward compatibility)
- *
- * @deprecated Use OtelSpanStatus from OTLP data structures instead
- */
-export interface OtelSimplifiedSpanStatus {
-  code: 'UNSET' | 'OK' | 'ERROR';
-  message?: string;
-}
-
-/**
- * OTEL Span
- *
- * Represents a unit of work in a distributed trace.
- * Used for trace-based edge derivation between canvas nodes.
- *
- * @example
- * ```typescript
- * const span: OtelSpan = {
- *   traceId: 'abc123',
- *   spanId: 'span1',
- *   parentSpanId: 'span0',
- *   name: 'POST /api/checkout',
- *   kind: 'SERVER',
- *   startTime: Date.now(),
- *   resource: {
- *     'service.name': 'checkout-api'
- *   }
- * };
- * ```
- */
-export interface OtelSpan {
-  /** Trace ID this span belongs to */
-  traceId: string;
-
-  /** Unique span ID */
-  spanId: string;
-
-  /** Parent span ID (undefined for root spans) */
-  parentSpanId?: string;
-
-  /** Span name (usually operation name) */
-  name: string;
-
-  /** Span kind */
-  kind: OtelSpanKind;
-
-  /** Start time in milliseconds, nanoseconds, or ISO string */
-  startTime: number | string;
-
-  /** End time (undefined if span is still active) */
-  endTime?: number | string;
-
-  /** Resource describing the source entity */
-  resource: OtelResource;
-
-  /** Span attributes */
-  attributes?: OtelAttributes;
-
-  /** Span status */
-  status?: OtelSimplifiedSpanStatus;
-
-  /** Events (logs within the span) */
-  events?: Array<{
-    name: string;
-    timestamp: number | string;
-    attributes?: OtelAttributes;
-  }>;
-}
-
-/**
- * Type guard: Check if severity indicates an error
- */
-export function isErrorSeverity(severity: OtelSeverity | undefined): boolean {
-  if (severity === undefined) return false;
-  if (typeof severity === 'string') {
-    return severity === 'ERROR' || severity === 'FATAL';
-  }
-  return severity >= 17; // ERROR starts at 17 in OTEL spec
-}
-
-/**
- * Type guard: Check if severity indicates a warning
- */
-export function isWarnSeverity(severity: OtelSeverity | undefined): boolean {
-  if (severity === undefined) return false;
-  if (typeof severity === 'string') {
-    return severity === 'WARN';
-  }
-  return severity >= 13 && severity <= 16; // WARN is 13-16 in OTEL spec
-}