@respan/tracing 1.0.45

package/dist/utils/span.js

@@ -0,0 +1,269 @@
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+import { RESPAN_PACKAGE_NAME } from "../constants/index.js";
+import { RespanParamsSchema, RespanSpanAttributes, RESPAN_SPAN_ATTRIBUTES_MAP, } from "@respan/respan-sdk";
+// Global tracer instance (singleton)
+let _tracer;
+/**
+ * Gets the singleton tracer instance.
+ * The tracer is responsible for creating and managing spans.
+ *
+ * @returns The global tracer instance
+ */
+export const getTracer = () => {
+    if (!_tracer) {
+        // Create tracer with a unique name for this SDK
+        _tracer = trace.getTracer(RESPAN_PACKAGE_NAME);
+    }
+    return _tracer;
+};
+/**
+ * Gets the currently active span from the context.
+ * This is the span that's currently being executed.
+ *
+ * @returns The active span or undefined if no span is active
+ */
+export const getCurrentSpan = () => {
+    return trace.getActiveSpan();
+};
+/**
+ * Update the current active span with new information.
+ * This is the JavaScript equivalent of the Python update_current_span method.
+ *
+ * @param options - Configuration object for updating the span
+ * @returns True if the span was updated successfully, False otherwise
+ */
+export const updateCurrentSpan = (options = {}) => {
+    const currentSpan = getCurrentSpan();
+    if (!currentSpan) {
+        console.debug("[Respan Debug] No active span found. Cannot update span.");
+        return false;
+    }
+    try {
+        const { respanParams, attributes, status, statusDescription, name } = options;
+        console.debug("[Respan Debug] Updating current span with:", {
+            hasRespanParams: !!respanParams,
+            respanParamsKeys: respanParams
+                ? Object.keys(respanParams)
+                : [],
+            hasAttributes: !!attributes,
+            attributesKeys: attributes ? Object.keys(attributes) : [],
+            hasStatus: status !== undefined,
+            status,
+            statusDescription,
+            newName: name,
+        });
+        // Update span name if provided
+        if (name) {
+            currentSpan.updateName(name);
+            console.debug(`[Respan Debug] Updated span name to: ${name}`);
+        }
+        // Set Respan-specific attributes
+        if (respanParams) {
+            setRespanAttributes(currentSpan, respanParams);
+        }
+        // Set generic attributes
+        if (attributes) {
+            Object.entries(attributes).forEach(([key, value]) => {
+                try {
+                    currentSpan.setAttribute(key, value);
+                    console.debug(`[Respan Debug] Set attribute: ${key}=${value}`);
+                }
+                catch (error) {
+                    console.warn(`[Respan Debug] Failed to set attribute ${key}=${value}:`, error);
+                }
+            });
+        }
+        // Set status
+        if (status !== undefined) {
+            currentSpan.setStatus({
+                code: status,
+                message: statusDescription,
+            });
+            console.debug(`[Respan Debug] Set span status: ${status}${statusDescription ? ` (${statusDescription})` : ""}`);
+        }
+        return true;
+    }
+    catch (error) {
+        console.error("[Respan Debug] Failed to update span:", error);
+        return false;
+    }
+};
+/**
+ * Set Respan-specific attributes on a span.
+ * This is the JavaScript equivalent of the Python _set_respan_attributes method.
+ * Uses the imported RESPAN_SPAN_ATTRIBUTES_MAP and validates with RespanParamsSchema.
+ *
+ * @param span - The span to set attributes on
+ * @param respanParams - Respan parameters to set as span attributes
+ */
+const setRespanAttributes = (span, respanParams) => {
+    try {
+        console.debug("[Respan Debug] Setting Respan attributes:", respanParams);
+        // Validate parameters using the imported schema
+        let validatedParams;
+        try {
+            validatedParams = RespanParamsSchema.parse(respanParams);
+            console.debug("[Respan Debug] Parameters validated successfully");
+        }
+        catch (validationError) {
+            console.warn("[Respan Debug] Failed to validate Respan params:", validationError);
+            // Use original params if validation fails, but continue processing
+            validatedParams = respanParams;
+        }
+        // Set attributes based on the imported mapping
+        Object.entries(validatedParams).forEach(([key, value]) => {
+            if (key in RESPAN_SPAN_ATTRIBUTES_MAP && key !== "metadata") {
+                try {
+                    const attributeKey = RESPAN_SPAN_ATTRIBUTES_MAP[key];
+                    span.setAttribute(attributeKey, value);
+                    console.debug(`[Respan Debug] Set Respan attribute: ${attributeKey}=${value}`);
+                }
+                catch (error) {
+                    console.warn(`[Respan Debug] Failed to set span attribute ${RESPAN_SPAN_ATTRIBUTES_MAP[key]}=${value}:`, error);
+                }
+            }
+            // Handle metadata specially using the proper enum
+            if (key === "metadata" && typeof value === "object" && value !== null) {
+                console.debug("[Respan Debug] Setting metadata attributes:", value);
+                Object.entries(value).forEach(([metadataKey, metadataValue]) => {
+                    try {
+                        const fullKey = `${RespanSpanAttributes.RESPAN_METADATA}.${metadataKey}`;
+                        span.setAttribute(fullKey, metadataValue);
+                        console.debug(`[Respan Debug] Set metadata attribute: ${fullKey}=${metadataValue}`);
+                    }
+                    catch (error) {
+                        console.warn(`[Respan Debug] Failed to set metadata attribute ${metadataKey}=${metadataValue}:`, error);
+                    }
+                });
+            }
+        });
+    }
+    catch (error) {
+        console.error("[Respan Debug] Unexpected error setting Respan attributes:", error);
+    }
+};
+/**
+ * Adds an event to the currently active span.
+ * Events are timestamped messages that provide additional context.
+ *
+ * @param name - Name of the event
+ * @param attributes - Optional attributes for the event
+ * @returns true if event was added, false if no active span
+ */
+export const addSpanEvent = (name, attributes) => {
+    const currentSpan = getCurrentSpan();
+    if (!currentSpan) {
+        console.warn("No active span to add event to");
+        return false;
+    }
+    try {
+        currentSpan.addEvent(name, attributes);
+        return true;
+    }
+    catch (error) {
+        console.error("Error adding span event:", error);
+        return false;
+    }
+};
+/**
+ * Records an exception in the currently active span.
+ * This is useful for capturing errors that don't necessarily end the span.
+ *
+ * @param exception - The error/exception to record
+ * @returns true if exception was recorded, false if no active span
+ */
+export const recordSpanException = (exception) => {
+    const currentSpan = getCurrentSpan();
+    if (!currentSpan) {
+        console.warn("No active span to record exception in");
+        return false;
+    }
+    try {
+        currentSpan.recordException(exception);
+        return true;
+    }
+    catch (error) {
+        console.error("Error recording span exception:", error);
+        return false;
+    }
+};
+/**
+ * Sets the status of the currently active span.
+ * This indicates whether the operation succeeded or failed.
+ *
+ * @param status - The status to set (OK or ERROR)
+ * @param message - Optional message describing the status
+ * @returns true if status was set, false if no active span
+ */
+export const setSpanStatus = (status, message) => {
+    const currentSpan = getCurrentSpan();
+    if (!currentSpan) {
+        console.warn("No active span to set status on");
+        return false;
+    }
+    try {
+        currentSpan.setStatus({
+            code: status === "OK" ? SpanStatusCode.OK : SpanStatusCode.ERROR,
+            message,
+        });
+        return true;
+    }
+    catch (error) {
+        console.error("Error setting span status:", error);
+        return false;
+    }
+};
+/**
+ * Creates a manual span for custom tracing.
+ * This is useful when you need to trace operations that aren't wrapped by withEntity.
+ *
+ * @param name - Name of the span
+ * @param fn - Function to execute within the span
+ * @param attributes - Optional attributes for the span
+ * @returns The result of the function
+ */
+export const withManualSpan = (name, fn, attributes) => {
+    return getTracer().startActiveSpan(name, {}, (span) => {
+        try {
+            // Add attributes if provided
+            if (attributes) {
+                Object.entries(attributes).forEach(([key, value]) => {
+                    span.setAttribute(key, value);
+                });
+            }
+            const result = fn(span);
+            // Handle promises
+            if (result instanceof Promise) {
+                return result
+                    .then((res) => {
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    span.end();
+                    return res;
+                })
+                    .catch((error) => {
+                    span.recordException(error);
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error.message,
+                    });
+                    span.end();
+                    throw error;
+                });
+            }
+            // Handle synchronous results
+            span.setStatus({ code: SpanStatusCode.OK });
+            span.end();
+            return result;
+        }
+        catch (error) {
+            span.recordException(error);
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error.message,
+            });
+            span.end();
+            throw error;
+        }
+    });
+};
+//# sourceMappingURL=span.js.map

package/dist/utils/span.js.map

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

package/dist/utils/spanBuffer.d.ts

@@ -0,0 +1,94 @@
+import { SpanKind } from "@opentelemetry/api";
+import { ReadableSpan } from "@opentelemetry/sdk-trace-base";
+/**
+ * Interface for managing buffered spans.
+ *
+ * SpanBuffer provides manual control over span creation and export timing.
+ * Unlike automatic tracing, spans are buffered locally and only exported
+ * when you explicitly call processSpans().
+ *
+ * Key features:
+ * - Manual span creation with attributes
+ * - Local buffering (no automatic export)
+ * - Transportable spans (extract and process anywhere)
+ * - Context isolation
+ *
+ * @example
+ * ```typescript
+ * const client = getClient();
+ * let collectedSpans: ReadableSpan[] = [];
+ *
+ * // Collect spans during execution
+ * with (client.getSpanBuffer("trace-123")) {
+ *   buffer.createSpan("step1", { status: "completed" });
+ *   buffer.createSpan("step2", { status: "completed" });
+ *   collectedSpans = buffer.getAllSpans();
+ * }
+ *
+ * // Process later based on business logic
+ * if (shouldExport) {
+ *   client.processSpans(collectedSpans);
+ * }
+ * ```
+ */
+export interface SpanBuffer {
+    /**
+     * Create a span in the buffer
+     * @param name - Span name
+     * @param attributes - Optional span attributes
+     * @param kind - Optional span kind (default: INTERNAL)
+     */
+    createSpan(name: string, attributes?: Record<string, any>, kind?: SpanKind): void;
+    /**
+     * Get all buffered spans as ReadableSpan objects
+     * @returns Array of all buffered spans
+     */
+    getAllSpans(): ReadableSpan[];
+    /**
+     * Get the count of buffered spans
+     * @returns Number of spans in the buffer
+     */
+    getSpanCount(): number;
+    /**
+     * Clear all buffered spans without processing them
+     */
+    clearSpans(): void;
+}
+/**
+ * Manager for span buffers with context isolation.
+ *
+ * This class provides:
+ * - Context-isolated span buffering
+ * - Manual span processing through OTEL pipeline
+ * - Support for transportable spans
+ */
+export declare class SpanBufferManager {
+    /**
+     * Create a new span buffer with the given trace ID
+     * @param traceId - Trace ID for all spans in this buffer
+     * @returns A new SpanBuffer instance
+     */
+    createBuffer(traceId: string): SpanBuffer;
+    /**
+     * Process spans through the OpenTelemetry processor pipeline.
+     * This sends the spans to all configured processors.
+     *
+     * @param spans - Array of ReadableSpan objects or a SpanBuffer
+     * @returns Promise<boolean> - True if processing succeeded
+     *
+     * @example
+     * ```typescript
+     * const manager = new SpanBufferManager();
+     * const buffer = manager.createBuffer("trace-123");
+     * buffer.createSpan("task", { result: "success" });
+     *
+     * const spans = buffer.getAllSpans();
+     * await manager.processSpans(spans);
+     * ```
+     */
+    processSpans(spans: ReadableSpan[] | SpanBuffer): Promise<boolean>;
+}
+/**
+ * Get the span buffer manager instance
+ */
+export declare function getSpanBufferManager(): SpanBufferManager;

package/dist/utils/spanBuffer.js

@@ -0,0 +1,147 @@
+import { trace, SpanKind, ROOT_CONTEXT } from "@opentelemetry/api";
+import { hrTime } from "@opentelemetry/core";
+/**
+ * Context key for span buffer
+ */
+const SPAN_BUFFER_KEY = Symbol("respan.span_buffer");
+/**
+ * Implementation of SpanBuffer
+ */
+class SpanBufferImpl {
+    spans = [];
+    traceId;
+    tracer = trace.getTracer("@respan/tracing");
+    constructor(traceId) {
+        this.traceId = traceId;
+    }
+    createSpan(name, attributes, kind = SpanKind.INTERNAL) {
+        // Create a span context for this buffered span
+        const spanContext = {
+            traceId: this.traceId,
+            spanId: this.generateSpanId(),
+            traceFlags: 1, // Sampled
+        };
+        // Create the span
+        const span = this.tracer.startSpan(name, {
+            kind,
+            startTime: hrTime(),
+        }, ROOT_CONTEXT);
+        // Set attributes
+        if (attributes) {
+            for (const [key, value] of Object.entries(attributes)) {
+                span.setAttribute(key, value);
+            }
+        }
+        // End the span immediately (we're creating historical spans)
+        span.end();
+        // Add to buffer
+        // @ts-ignore - Access internal span for buffering
+        this.spans.push(span);
+        console.debug(`[Respan] Buffered span: ${name} (total: ${this.spans.length})`);
+    }
+    getAllSpans() {
+        return [...this.spans];
+    }
+    getSpanCount() {
+        return this.spans.length;
+    }
+    clearSpans() {
+        const count = this.spans.length;
+        this.spans = [];
+        console.debug(`[Respan] Cleared ${count} buffered spans`);
+    }
+    generateSpanId() {
+        // Generate a random 16-character hex string for span ID
+        return Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join("");
+    }
+}
+/**
+ * Manager for span buffers with context isolation.
+ *
+ * This class provides:
+ * - Context-isolated span buffering
+ * - Manual span processing through OTEL pipeline
+ * - Support for transportable spans
+ */
+export class SpanBufferManager {
+    /**
+     * Create a new span buffer with the given trace ID
+     * @param traceId - Trace ID for all spans in this buffer
+     * @returns A new SpanBuffer instance
+     */
+    createBuffer(traceId) {
+        return new SpanBufferImpl(traceId);
+    }
+    /**
+     * Process spans through the OpenTelemetry processor pipeline.
+     * This sends the spans to all configured processors.
+     *
+     * @param spans - Array of ReadableSpan objects or a SpanBuffer
+     * @returns Promise<boolean> - True if processing succeeded
+     *
+     * @example
+     * ```typescript
+     * const manager = new SpanBufferManager();
+     * const buffer = manager.createBuffer("trace-123");
+     * buffer.createSpan("task", { result: "success" });
+     *
+     * const spans = buffer.getAllSpans();
+     * await manager.processSpans(spans);
+     * ```
+     */
+    async processSpans(spans) {
+        try {
+            const spanArray = Array.isArray(spans) ? spans : spans.getAllSpans();
+            if (spanArray.length === 0) {
+                console.debug("[Respan] No spans to process");
+                return true;
+            }
+            console.debug(`[Respan] Processing ${spanArray.length} buffered spans`);
+            // Get the SDK instance to access processors
+            const { getClient } = await import("./tracing.js");
+            const sdk = getClient();
+            if (!sdk) {
+                console.warn("[Respan] SDK not initialized, cannot process spans");
+                return false;
+            }
+            // Access the tracer provider and processors
+            // @ts-ignore - Access internal SDK structure
+            const tracerProvider = sdk._tracerProvider;
+            if (!tracerProvider) {
+                console.warn("[Respan] TracerProvider not found");
+                return false;
+            }
+            // Get active span processors
+            // @ts-ignore - Access internal structure
+            const activeSpanProcessor = tracerProvider.activeSpanProcessor;
+            if (!activeSpanProcessor) {
+                console.warn("[Respan] No active span processor found");
+                return false;
+            }
+            // Process each span through the pipeline
+            for (const span of spanArray) {
+                activeSpanProcessor.onEnd(span);
+            }
+            console.debug("[Respan] Successfully processed buffered spans");
+            return true;
+        }
+        catch (error) {
+            console.error("[Respan] Error processing spans:", error);
+            return false;
+        }
+    }
+}
+/**
+ * Global span buffer manager instance
+ */
+let _bufferManager;
+/**
+ * Get the span buffer manager instance
+ */
+export function getSpanBufferManager() {
+    if (!_bufferManager) {
+        _bufferManager = new SpanBufferManager();
+    }
+    return _bufferManager;
+}
+//# sourceMappingURL=spanBuffer.js.map

package/dist/utils/spanBuffer.js.map

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

package/dist/utils/tracing.d.ts

@@ -0,0 +1,31 @@
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { RespanOptions, ProcessorConfig } from "../types/clientTypes.js";
+/**
+ * Helper function to resolve and clean up the base URL
+ */
+export declare const _resolveBaseURL: (baseURL: string) => string;
+/**
+ * Initializes the OpenTelemetry SDK with Respan-specific configuration.
+ * This sets up the entire tracing pipeline: collection, processing, and export.
+ *
+ * @param options - Configuration options for the tracing setup
+ */
+export declare const startTracing: (options: RespanOptions) => Promise<void>;
+/**
+ * Enhanced error logging for forceFlush
+ */
+export declare const forceFlush: () => Promise<void>;
+/**
+ * Gets the current SDK instance.
+ * Useful for advanced configuration or checking if tracing is initialized.
+ *
+ * @returns The NodeSDK instance or undefined if not initialized
+ */
+export declare const getClient: () => NodeSDK | undefined;
+/**
+ * Add a processor to the SDK for routing spans.
+ * This allows routing spans to different destinations based on processor names.
+ *
+ * @param config - Processor configuration
+ */
+export declare const addProcessorToSDK: (config: ProcessorConfig) => void;