@vorionsys/platform-core 0.1.0

package/dist/common/telemetry/spans.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Span Utilities for OpenTelemetry
+ *
+ * Provides helper functions for creating spans, wrapping async functions,
+ * adding attributes, and recording errors with proper context propagation.
+ *
+ * @packageDocumentation
+ */
+import { SpanKind, type Span, type Tracer, type Context, type Attributes, type Link, type TimeInput } from '@opentelemetry/api';
+/**
+ * Span creation options
+ */
+export interface CreateSpanOptions {
+    /** Span kind (default: INTERNAL) */
+    kind?: SpanKind;
+    /** Initial attributes */
+    attributes?: Attributes;
+    /** Links to related spans */
+    links?: Link[];
+    /** Start time (default: now) */
+    startTime?: TimeInput;
+    /** Parent context (default: active context) */
+    parentContext?: Context;
+    /** Root span (ignores parent context) */
+    root?: boolean;
+}
+/**
+ * Create a new span with automatic context propagation
+ *
+ * @param tracer - Tracer instance or tracer name
+ * @param name - Span name
+ * @param options - Span options
+ * @returns Created span
+ *
+ * @example
+ * ```typescript
+ * const span = createSpan(getIntentTracer(), 'process-intent', {
+ *   attributes: { 'intent.id': intentId },
+ *   kind: SpanKind.INTERNAL,
+ * });
+ *
+ * try {
+ *   // Do work...
+ *   span.setStatus({ code: SpanStatusCode.OK });
+ * } catch (error) {
+ *   recordException(span, error);
+ * } finally {
+ *   span.end();
+ * }
+ * ```
+ */
+export declare function createSpan(tracer: Tracer | string, name: string, options?: CreateSpanOptions): Span;
+/**
+ * Execute a function within a span context
+ *
+ * Automatically handles span lifecycle including error recording
+ * and status setting.
+ *
+ * @param tracer - Tracer instance or tracer name
+ * @param name - Span name
+ * @param fn - Async function to execute within the span
+ * @param options - Span options
+ * @returns Result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = await withSpan(
+ *   'vorion.intent',
+ *   'validate-intent',
+ *   async (span) => {
+ *     span.setAttribute('intent.type', intentType);
+ *     return await validateIntent(intent);
+ *   },
+ *   { attributes: { 'intent.id': intent.id } }
+ * );
+ * ```
+ */
+export declare function withSpan<T>(tracer: Tracer | string, name: string, fn: (span: Span) => Promise<T>, options?: CreateSpanOptions): Promise<T>;
+/**
+ * Execute a synchronous function within a span context
+ *
+ * @param tracer - Tracer instance or tracer name
+ * @param name - Span name
+ * @param fn - Synchronous function to execute within the span
+ * @param options - Span options
+ * @returns Result of the function
+ */
+export declare function withSpanSync<T>(tracer: Tracer | string, name: string, fn: (span: Span) => T, options?: CreateSpanOptions): T;
+/**
+ * Add attributes to a span
+ *
+ * @param span - Span to add attributes to
+ * @param attributes - Attributes to add
+ *
+ * @example
+ * ```typescript
+ * addSpanAttributes(span, {
+ *   'intent.id': intent.id,
+ *   'intent.type': intent.type,
+ *   'tenant.id': tenantId,
+ *   'trust.level': trustLevel,
+ * });
+ * ```
+ */
+export declare function addSpanAttributes(span: Span, attributes: Attributes): void;
+/**
+ * Add a single attribute to a span
+ *
+ * @param span - Span to add attribute to
+ * @param key - Attribute key
+ * @param value - Attribute value
+ */
+export declare function addSpanAttribute(span: Span, key: string, value: string | number | boolean | string[] | number[] | boolean[]): void;
+/**
+ * Record an exception on a span
+ *
+ * Sets the span status to ERROR and records exception details.
+ *
+ * @param span - Span to record exception on
+ * @param error - Error to record
+ * @param attributes - Additional attributes for the exception event
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await processIntent(intent);
+ * } catch (error) {
+ *   recordException(span, error, {
+ *     'error.category': 'validation',
+ *     'intent.id': intent.id,
+ *   });
+ *   throw error;
+ * }
+ * ```
+ */
+export declare function recordException(span: Span, error: unknown, attributes?: Attributes): void;
+/**
+ * Add an event to a span
+ *
+ * @param span - Span to add event to
+ * @param name - Event name
+ * @param attributes - Event attributes
+ * @param timestamp - Event timestamp
+ *
+ * @example
+ * ```typescript
+ * addSpanEvent(span, 'trust.evaluation.complete', {
+ *   'trust.level': trustLevel,
+ *   'trust.score': trustScore,
+ *   'trust.factors': JSON.stringify(factors),
+ * });
+ * ```
+ */
+export declare function addSpanEvent(span: Span, name: string, attributes?: Attributes, timestamp?: TimeInput): void;
+/**
+ * Create a link to another span
+ *
+ * Used to link related spans that are not in a parent-child relationship.
+ *
+ * @param traceId - Trace ID of the linked span
+ * @param spanId - Span ID of the linked span
+ * @param attributes - Link attributes
+ * @returns Link object
+ *
+ * @example
+ * ```typescript
+ * const link = createSpanLink(originalTraceId, originalSpanId, {
+ *   'link.type': 'retry',
+ *   'link.attempt': 2,
+ * });
+ *
+ * const span = createSpan(tracer, 'retry-operation', {
+ *   links: [link],
+ * });
+ * ```
+ */
+export declare function createSpanLink(traceId: string, spanId: string, attributes?: Attributes): Link;
+/**
+ * Create multiple links to related spans
+ *
+ * @param links - Array of link specifications
+ * @returns Array of Link objects
+ */
+export declare function createSpanLinks(links: Array<{
+    traceId: string;
+    spanId: string;
+    attributes?: Attributes;
+}>): Link[];
+/**
+ * Get the current active span
+ *
+ * @returns Active span or undefined
+ */
+export declare function getActiveSpan(): Span | undefined;
+/**
+ * Get the current span context
+ *
+ * @returns Span context with trace and span IDs
+ */
+export declare function getSpanContext(): {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+} | null;
+/**
+ * Run a function with a specific context
+ *
+ * @param ctx - Context to use
+ * @param fn - Function to run
+ * @returns Result of the function
+ */
+export declare function runWithContext<T>(ctx: Context, fn: () => T): T;
+/**
+ * Get the current active context
+ *
+ * @returns Active context
+ */
+export declare function getActiveContext(): Context;
+/**
+ * Vorion-specific span attributes
+ */
+export declare const VorionSpanAttributes: {
+    readonly INTENT_ID: "vorion.intent.id";
+    readonly INTENT_TYPE: "vorion.intent.type";
+    readonly INTENT_STATUS: "vorion.intent.status";
+    readonly INTENT_PRIORITY: "vorion.intent.priority";
+    readonly TENANT_ID: "vorion.tenant.id";
+    readonly ENTITY_ID: "vorion.entity.id";
+    readonly TRUST_LEVEL: "vorion.trust.level";
+    readonly TRUST_SCORE: "vorion.trust.score";
+    readonly TRUST_FACTORS: "vorion.trust.factors";
+    readonly POLICY_ID: "vorion.policy.id";
+    readonly POLICY_ACTION: "vorion.policy.action";
+    readonly POLICY_NAMESPACE: "vorion.policy.namespace";
+    readonly SECURITY_EVENT: "vorion.security.event";
+    readonly SECURITY_RISK: "vorion.security.risk";
+    readonly SECURITY_VIOLATION: "vorion.security.violation";
+    readonly ESCALATION_ID: "vorion.escalation.id";
+    readonly ESCALATION_REASON: "vorion.escalation.reason";
+    readonly ESCALATION_STATUS: "vorion.escalation.status";
+    readonly QUEUE_NAME: "vorion.queue.name";
+    readonly JOB_ID: "vorion.job.id";
+    readonly JOB_ATTEMPT: "vorion.job.attempt";
+    readonly DB_OPERATION: "vorion.db.operation";
+    readonly DB_TABLE: "vorion.db.table";
+    readonly DB_ROWS_AFFECTED: "vorion.db.rows_affected";
+    readonly CACHE_HIT: "vorion.cache.hit";
+    readonly CACHE_KEY: "vorion.cache.key";
+    readonly WEBHOOK_ID: "vorion.webhook.id";
+    readonly WEBHOOK_EVENT: "vorion.webhook.event";
+    readonly WEBHOOK_STATUS: "vorion.webhook.status";
+};
+/**
+ * Span event names for Vorion operations
+ */
+export declare const VorionSpanEvents: {
+    readonly INTENT_SUBMITTED: "vorion.intent.submitted";
+    readonly INTENT_VALIDATED: "vorion.intent.validated";
+    readonly INTENT_EVALUATED: "vorion.intent.evaluated";
+    readonly INTENT_DECIDED: "vorion.intent.decided";
+    readonly INTENT_COMPLETED: "vorion.intent.completed";
+    readonly TRUST_EVALUATED: "vorion.trust.evaluated";
+    readonly TRUST_GATE_PASSED: "vorion.trust.gate_passed";
+    readonly TRUST_GATE_FAILED: "vorion.trust.gate_failed";
+    readonly POLICY_MATCHED: "vorion.policy.matched";
+    readonly POLICY_EVALUATED: "vorion.policy.evaluated";
+    readonly POLICY_DENIED: "vorion.policy.denied";
+    readonly SECURITY_VIOLATION_DETECTED: "vorion.security.violation_detected";
+    readonly AUTH_SUCCESS: "vorion.auth.success";
+    readonly AUTH_FAILURE: "vorion.auth.failure";
+    readonly ESCALATION_CREATED: "vorion.escalation.created";
+    readonly ESCALATION_RESOLVED: "vorion.escalation.resolved";
+    readonly ESCALATION_TIMEOUT: "vorion.escalation.timeout";
+};
+/**
+ * Create an intent span with standard attributes
+ */
+export declare function withIntentSpan<T>(name: string, intentId: string, tenantId: string, fn: (span: Span) => Promise<T>, additionalAttributes?: Attributes): Promise<T>;
+/**
+ * Create a security span with standard attributes
+ */
+export declare function withSecuritySpan<T>(name: string, fn: (span: Span) => Promise<T>, attributes?: Attributes): Promise<T>;
+/**
+ * Create a policy evaluation span
+ */
+export declare function withPolicySpan<T>(intentId: string, tenantId: string, namespace: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Create a database operation span
+ */
+export declare function withDatabaseSpan<T>(operation: string, table: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Create a cache operation span
+ */
+export declare function withCacheSpan<T>(operation: string, key: string, fn: (span: Span) => Promise<T>): Promise<T>;
+//# sourceMappingURL=spans.d.ts.map

package/dist/common/telemetry/spans.d.ts.map

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