/**
 * 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