@principal-ai/subsystems-core 0.29.0

package/dist/types/otel.d.ts

@@ -0,0 +1,465 @@
+/**
+ * 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 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;
+    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;
+    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[];
+}
+/**
+ * Extract string value from OTEL attribute value
+ *
+ * @param value - OTEL attribute value
+ * @returns String value if present, undefined otherwise
+ */
+export declare function getAttributeStringValue(value: OtelAnyValue): string | 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 declare function findAttribute(attributes: OtelKeyValue[] | undefined, key: string): OtelKeyValue | undefined;
+/**
+ * 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 declare function getAttributeValue(attributes: OtelKeyValue[] | undefined, key: string): string | number | boolean | 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 declare function flattenResourceAttributes(resource: OtelResourceData): Record<string, string>;
+/**
+ * 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 declare function parseNanoTime(nanos: string | number): number;
+/**
+ * Calculate span duration in milliseconds
+ *
+ * @param span - OTEL span
+ * @returns Duration in milliseconds
+ */
+export declare function getSpanDuration(span: OtelSpanData): number;
+/**
+ * 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;
+}
+/**
+ * @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.name'?: string;
+    'service.namespace'?: string;
+    'service.instance.id'?: string;
+    'service.version'?: string;
+    '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.provider'?: string;
+    'cloud.region'?: string;
+    'cloud.availability_zone'?: string;
+    'cloud.account.id'?: string;
+    'deployment.environment'?: string;
+    'host.name'?: string;
+    'host.id'?: string;
+    'host.type'?: string;
+    'process.pid'?: number;
+    'process.executable.name'?: string;
+    'process.runtime.name'?: string;
+    'process.runtime.version'?: string;
+    'db.system'?: string;
+    'db.name'?: string;
+    'db.user'?: string;
+    'messaging.system'?: string;
+    'messaging.destination.name'?: string;
+    [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 declare function isErrorSeverity(severity: OtelSeverity | undefined): boolean;
+/**
+ * Type guard: Check if severity indicates a warning
+ */
+export declare function isWarnSeverity(severity: OtelSeverity | undefined): boolean;
+//# sourceMappingURL=otel.d.ts.map

package/dist/types/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../../src/types/otel.ts"],"names":[],"mappings":"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"}

package/dist/types/otel.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * 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/
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWarnSeverity = exports.isErrorSeverity = exports.getSpanDuration = exports.parseNanoTime = exports.flattenResourceAttributes = exports.getAttributeValue = exports.findAttribute = exports.getAttributeStringValue = void 0;
+// =============================================================================
+// Helper Functions for OTLP Data
+// =============================================================================
+/**
+ * Extract string value from OTEL attribute value
+ *
+ * @param value - OTEL attribute value
+ * @returns String value if present, undefined otherwise
+ */
+function getAttributeStringValue(value) {
+    return value.stringValue ?? undefined;
+}
+exports.getAttributeStringValue = getAttributeStringValue;
+/**
+ * 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
+ */
+function findAttribute(attributes, key) {
+    return attributes?.find((attr) => attr.key === key);
+}
+exports.findAttribute = findAttribute;
+/**
+ * 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
+ * ```
+ */
+function getAttributeValue(attributes, key) {
+    const attr = findAttribute(attributes, key);
+    if (!attr)
+        return undefined;
+    return (attr.value.stringValue ??
+        attr.value.intValue ??
+        attr.value.doubleValue ??
+        attr.value.boolValue ??
+        undefined);
+}
+exports.getAttributeValue = getAttributeValue;
+/**
+ * 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' }
+ * ```
+ */
+function flattenResourceAttributes(resource) {
+    const result = {};
+    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;
+}
+exports.flattenResourceAttributes = flattenResourceAttributes;
+/**
+ * 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
+ * ```
+ */
+function parseNanoTime(nanos) {
+    const nanosNum = typeof nanos === 'string' ? parseInt(nanos, 10) : nanos;
+    return nanosNum / 1000000;
+}
+exports.parseNanoTime = parseNanoTime;
+/**
+ * Calculate span duration in milliseconds
+ *
+ * @param span - OTEL span
+ * @returns Duration in milliseconds
+ */
+function getSpanDuration(span) {
+    const start = parseInt(span.startTimeUnixNano, 10);
+    const end = parseInt(span.endTimeUnixNano, 10);
+    return (end - start) / 1000000;
+}
+exports.getSpanDuration = getSpanDuration;
+/**
+ * Type guard: Check if severity indicates an error
+ */
+function isErrorSeverity(severity) {
+    if (severity === undefined)
+        return false;
+    if (typeof severity === 'string') {
+        return severity === 'ERROR' || severity === 'FATAL';
+    }
+    return severity >= 17; // ERROR starts at 17 in OTEL spec
+}
+exports.isErrorSeverity = isErrorSeverity;
+/**
+ * Type guard: Check if severity indicates a warning
+ */
+function isWarnSeverity(severity) {
+    if (severity === undefined)
+        return false;
+    if (typeof severity === 'string') {
+        return severity === 'WARN';
+    }
+    return severity >= 13 && severity <= 16; // WARN is 13-16 in OTEL spec
+}
+exports.isWarnSeverity = isWarnSeverity;
+//# sourceMappingURL=otel.js.map

package/dist/types/otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.js","sourceRoot":"","sources":["../../src/types/otel.ts"],"names":[],"mappings":"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"}