@pingops/otel 0.1.0

package/dist/span-processor.js

@@ -0,0 +1,272 @@
+/**
+ * PingopsSpanProcessor - OpenTelemetry SpanProcessor implementation
+ * Observes finished spans and sends eligible ones to PingOps backend
+ *
+ * This processor provides:
+ * - Automatic filtering of spans (CLIENT spans with HTTP/GenAI attributes only)
+ * - Domain and header filtering based on configuration
+ * - Batched or immediate export modes using OTLP exporters
+ * - Fire-and-forget transport (never blocks application)
+ *
+ * @example
+ * ```typescript
+ * import { NodeSDK } from '@opentelemetry/sdk-node';
+ * import { PingopsSpanProcessor } from '@pingops/otel';
+ *
+ * const sdk = new NodeSDK({
+ *   spanProcessors: [
+ *     new PingopsSpanProcessor({
+ *       apiKey: 'your-api-key',
+ *       baseUrl: 'https://api.pingops.com',
+ *       serviceName: 'my-service',
+ *       exportMode: 'batched', // or 'immediate'
+ *       domainAllowList: [
+ *         { domain: 'api.example.com' }
+ *       ]
+ *     })
+ *   ]
+ * });
+ *
+ * sdk.start();
+ * ```
+ */
+import { BatchSpanProcessor, SimpleSpanProcessor, } from "@opentelemetry/sdk-trace-base";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { isSpanEligible, shouldCaptureSpan, createLogger, getPropagatedAttributesFromContext, extractSpanPayload, } from "@pingops/core";
+const log = createLogger("[PingOps Processor]");
+/**
+ * Creates a filtered span wrapper that applies header filtering to attributes
+ *
+ * This wrapper applies both domain-specific and global header filtering:
+ * - Uses domain allow list to determine domain-specific header rules
+ * - Applies global header allow/deny lists
+ * - Filters headers from http.request.header and http.response.header attributes
+ *
+ * Uses a Proxy to automatically forward all properties and methods to the original span,
+ * except for 'attributes' which returns the filtered version. This approach is future-proof
+ * and will work with any new methods or properties added to ReadableSpan.
+ *
+ * This allows us to filter headers before the span is serialized by OTLP exporter
+ */
+function createFilteredSpan(span, domainAllowList, globalHeadersAllowList, globalHeadersDenyList) {
+    // Use extractSpanPayload to get filtered attributes
+    // This handles both domain-specific header rules and global header filtering
+    const payload = extractSpanPayload(span, domainAllowList, globalHeadersAllowList, globalHeadersDenyList);
+    const filteredAttributes = (payload?.attributes ??
+        span.attributes);
+    log.debug("Payload", { payload });
+    // Create a Proxy that intercepts 'attributes' access and forwards everything else
+    return new Proxy(span, {
+        get(target, prop) {
+            // Intercept 'attributes' to return filtered version
+            if (prop === "attributes") {
+                return filteredAttributes;
+            }
+            // Forward all other property/method access to the original span
+            const value = target[prop];
+            // If it's a function, bind it to the original target to preserve 'this' context
+            if (typeof value === "function") {
+                return value.bind(target);
+            }
+            return value;
+        },
+    });
+}
+/**
+ * OpenTelemetry span processor for sending spans to PingOps backend.
+ *
+ * This processor wraps OpenTelemetry's built-in processors (BatchSpanProcessor or SimpleSpanProcessor)
+ * and applies filtering before passing spans to the OTLP exporter.
+ */
+export class PingopsSpanProcessor {
+    processor;
+    config;
+    /**
+     * Creates a new PingopsSpanProcessor instance.
+     *
+     * @param config - Configuration parameters for the processor
+     */
+    constructor(config) {
+        const exportMode = config.exportMode ?? "batched";
+        // Get API key from config or environment
+        const apiKey = config.apiKey || process.env.PINGOPS_API_KEY || "";
+        // Create OTLP exporter pointing to PingOps backend
+        const exporter = new OTLPTraceExporter({
+            url: `${config.baseUrl}/v1/traces`,
+            headers: {
+                Authorization: apiKey ? `Bearer ${apiKey}` : "",
+                "Content-Type": "application/json",
+            },
+            timeoutMillis: 5000,
+        });
+        // Create underlying processor based on export mode
+        if (exportMode === "immediate") {
+            this.processor = new SimpleSpanProcessor(exporter);
+        }
+        else {
+            this.processor = new BatchSpanProcessor(exporter, {
+                maxExportBatchSize: config.batchSize ?? 50,
+                scheduledDelayMillis: config.batchTimeout ?? 5000,
+            });
+        }
+        this.config = {
+            debug: config.debug ?? false,
+            headersAllowList: config.headersAllowList,
+            headersDenyList: config.headersDenyList,
+            domainAllowList: config.domainAllowList,
+            domainDenyList: config.domainDenyList,
+        };
+        log.info("Initialized PingopsSpanProcessor", {
+            baseUrl: config.baseUrl,
+            exportMode,
+            batchSize: config.batchSize,
+            batchTimeout: config.batchTimeout,
+            hasDomainAllowList: !!config.domainAllowList && config.domainAllowList.length > 0,
+            hasDomainDenyList: !!config.domainDenyList && config.domainDenyList.length > 0,
+            hasHeadersAllowList: !!config.headersAllowList && config.headersAllowList.length > 0,
+            hasHeadersDenyList: !!config.headersDenyList && config.headersDenyList.length > 0,
+        });
+    }
+    /**
+     * Called when a span starts - extracts parent attributes from context and adds them to the span
+     */
+    onStart(span, parentContext) {
+        const spanContext = span.spanContext();
+        log.debug("Span started", {
+            spanName: span.name,
+            spanId: spanContext.spanId,
+            traceId: spanContext.traceId,
+        });
+        // Extract propagated attributes from context and set them on the span
+        const propagatedAttributes = getPropagatedAttributesFromContext(parentContext);
+        if (Object.keys(propagatedAttributes).length > 0) {
+            for (const [key, value] of Object.entries(propagatedAttributes)) {
+                // Type guard: value must be string or string[] for OpenTelemetry attributes
+                if (typeof value === "string" || Array.isArray(value)) {
+                    span.setAttribute(key, value);
+                }
+            }
+            log.debug("Set propagated attributes on span", {
+                spanName: span.name,
+                attributeKeys: Object.keys(propagatedAttributes),
+            });
+        }
+        this.processor.onStart(span, parentContext);
+    }
+    /**
+     * Called when a span ends. Filters the span and passes it to the underlying processor if eligible.
+     *
+     * This method:
+     * 1. Checks if the span is eligible (CLIENT + HTTP/GenAI attributes)
+     * 2. Applies domain filtering (determines if span should be exported)
+     * 3. Applies header filtering via FilteredSpan wrapper (domain-specific and global rules)
+     * 4. If eligible, passes filtered span to underlying OTLP processor for export
+     */
+    onEnd(span) {
+        const spanContext = span.spanContext();
+        log.debug("Span ended, processing", {
+            spanName: span.name,
+            spanId: spanContext.spanId,
+            traceId: spanContext.traceId,
+            spanKind: span.kind,
+        });
+        try {
+            // Step 1: Check if span is eligible (CLIENT + HTTP/GenAI attributes)
+            if (!isSpanEligible(span)) {
+                log.debug("Span not eligible, skipping", {
+                    spanName: span.name,
+                    spanId: spanContext.spanId,
+                    reason: "not CLIENT or missing HTTP/GenAI attributes",
+                });
+                return;
+            }
+            // Step 2: Extract URL for domain filtering
+            const attributes = span.attributes;
+            const url = attributes["http.url"] ||
+                attributes["url.full"] ||
+                (attributes["server.address"]
+                    ? `https://${String(attributes["server.address"])}`
+                    : "");
+            log.debug("Extracted URL for domain filtering", {
+                spanName: span.name,
+                url,
+                hasHttpUrl: !!attributes["http.url"],
+                hasUrlFull: !!attributes["url.full"],
+                hasServerAddress: !!attributes["server.address"],
+            });
+            // Step 3: Apply domain filtering
+            if (url) {
+                const shouldCapture = shouldCaptureSpan(url, this.config.domainAllowList, this.config.domainDenyList);
+                if (!shouldCapture) {
+                    log.info("Span filtered out by domain rules", {
+                        spanName: span.name,
+                        spanId: spanContext.spanId,
+                        url,
+                    });
+                    return;
+                }
+            }
+            else {
+                log.debug("No URL found for domain filtering, proceeding", {
+                    spanName: span.name,
+                });
+            }
+            // Step 4: Apply filtering (header filtering with domain-specific rules) by wrapping the span
+            const filteredSpan = createFilteredSpan(span, this.config.domainAllowList, this.config.headersAllowList, this.config.headersDenyList);
+            // Step 5: Span passed all filters, pass filtered span to underlying processor for export
+            this.processor.onEnd(filteredSpan);
+            log.info("Span passed all filters and queued for export", {
+                spanName: span.name,
+                spanId: spanContext.spanId,
+                traceId: spanContext.traceId,
+                url,
+                hasHeaderFiltering: !!(this.config.headersAllowList || this.config.headersDenyList),
+            });
+        }
+        catch (error) {
+            // Defensive error handling - never crash the app
+            log.error("Error processing span", {
+                spanName: span.name,
+                spanId: spanContext.spanId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Forces an immediate flush of all pending spans.
+     *
+     * @returns Promise that resolves when all pending operations are complete
+     */
+    async forceFlush() {
+        log.info("Force flushing spans");
+        try {
+            await this.processor.forceFlush();
+            log.info("Force flush complete");
+        }
+        catch (error) {
+            log.error("Error during force flush", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    /**
+     * Gracefully shuts down the processor, ensuring all pending operations are completed.
+     *
+     * @returns Promise that resolves when shutdown is complete
+     */
+    async shutdown() {
+        log.info("Shutting down processor");
+        try {
+            await this.processor.shutdown();
+            log.info("Processor shutdown complete");
+        }
+        catch (error) {
+            log.error("Error during processor shutdown", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=span-processor.js.map

package/dist/span-processor.js.map

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

package/dist/span-wrapper.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Span wrapper for PingOps SDK
+ *
+ * Provides PingopsSpan class similar to LangfuseSpan for wrapping OpenTelemetry spans
+ * with PingOps-specific functionality.
+ */
+import { TimeInput, Span, SpanContext } from '@opentelemetry/api';
+import type { Attributes } from '@opentelemetry/api';
+import type { SpanAttributes } from './tracer-provider';
+/**
+ * Base class for PingOps span wrappers
+ *
+ * Provides common functionality for wrapping OpenTelemetry spans with PingOps-specific features.
+ */
+declare abstract class PingopsBaseSpan {
+    /** The underlying OpenTelemetry span */
+    readonly otelSpan: Span;
+    /** The span ID from the OpenTelemetry span context */
+    id: string;
+    /** The trace ID from the OpenTelemetry span context */
+    traceId: string;
+    constructor(otelSpan: Span);
+    /**
+     * Ends the span, marking it as complete.
+     *
+     * @param endTime - Optional end time, defaults to current time
+     */
+    end(endTime?: TimeInput): void;
+    /**
+     * Updates the span with new attributes.
+     *
+     * @param attributes - Span attributes to set
+     * @returns This span for method chaining
+     */
+    update(attributes: SpanAttributes): PingopsSpan;
+}
+/**
+ * PingOps span wrapper for tracking operations
+ *
+ * Provides a convenient wrapper around OpenTelemetry spans with PingOps-specific
+ * attribute handling and lifecycle management.
+ */
+export declare class PingopsSpan extends PingopsBaseSpan {
+    constructor(otelSpan: Span);
+}
+/**
+ * Creates an OpenTelemetry span with the PingOps tracer.
+ *
+ * @param params - Parameters for span creation
+ * @returns The created OpenTelemetry span
+ * @internal
+ */
+export declare function createOtelSpan(params: {
+    name: string;
+    startTime?: TimeInput;
+    parentSpanContext?: SpanContext;
+    attributes?: Attributes;
+}): Span;
+export {};
+//# sourceMappingURL=span-wrapper.d.ts.map

package/dist/span-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-wrapper.d.ts","sourceRoot":"","sources":["../src/span-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAkB,SAAS,EAAE,IAAI,EAAE,WAAW,EAAW,MAAM,oBAAoB,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;GAIG;AACH,uBAAe,eAAe;IAC5B,wCAAwC;IACxC,SAAgB,QAAQ,EAAE,IAAI,CAAC;IAC/B,sDAAsD;IAC/C,EAAE,EAAE,MAAM,CAAC;IAClB,uDAAuD;IAChD,OAAO,EAAE,MAAM,CAAC;gBAEX,QAAQ,EAAE,IAAI;IAO1B;;;;OAIG;IACI,GAAG,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,IAAI;IAIrC;;;;;OAKG;IACI,MAAM,CAAC,UAAU,EAAE,cAAc,GAAG,WAAW;CA8CvD;AAED;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,eAAe;gBAClC,QAAQ,EAAE,IAAI;CAG3B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,iBAAiB,CAAC,EAAE,WAAW,CAAC;IAChC,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,IAAI,CAYP"}

package/dist/span-wrapper.js

@@ -0,0 +1,118 @@
+/**
+ * Span wrapper for PingOps SDK
+ *
+ * Provides PingopsSpan class similar to LangfuseSpan for wrapping OpenTelemetry spans
+ * with PingOps-specific functionality.
+ */
+import { trace, context } from '@opentelemetry/api';
+import { getPingopsTracerProvider } from './tracer-provider';
+/**
+ * Base class for PingOps span wrappers
+ *
+ * Provides common functionality for wrapping OpenTelemetry spans with PingOps-specific features.
+ */
+class PingopsBaseSpan {
+    /** The underlying OpenTelemetry span */
+    otelSpan;
+    /** The span ID from the OpenTelemetry span context */
+    id;
+    /** The trace ID from the OpenTelemetry span context */
+    traceId;
+    constructor(otelSpan) {
+        this.otelSpan = otelSpan;
+        const spanContext = otelSpan.spanContext();
+        this.id = spanContext.spanId;
+        this.traceId = spanContext.traceId;
+    }
+    /**
+     * Ends the span, marking it as complete.
+     *
+     * @param endTime - Optional end time, defaults to current time
+     */
+    end(endTime) {
+        this.otelSpan.end(endTime);
+    }
+    /**
+     * Updates the span with new attributes.
+     *
+     * @param attributes - Span attributes to set
+     * @returns This span for method chaining
+     */
+    update(attributes) {
+        const otelAttributes = {};
+        // Handle nested attributes object
+        if (attributes.attributes) {
+            Object.assign(otelAttributes, attributes.attributes);
+        }
+        // Handle input/output
+        if (attributes.input !== undefined) {
+            otelAttributes['span.input'] =
+                typeof attributes.input === 'string'
+                    ? attributes.input
+                    : JSON.stringify(attributes.input);
+        }
+        if (attributes.output !== undefined) {
+            otelAttributes['span.output'] =
+                typeof attributes.output === 'string'
+                    ? attributes.output
+                    : JSON.stringify(attributes.output);
+        }
+        // Handle metadata
+        if (attributes.metadata !== undefined) {
+            for (const [key, value] of Object.entries(attributes.metadata)) {
+                otelAttributes[`span.metadata.${key}`] =
+                    typeof value === 'string' ? value : JSON.stringify(value);
+            }
+        }
+        // Add any other custom attributes (excluding the special keys)
+        for (const [key, value] of Object.entries(attributes)) {
+            if (key !== 'attributes' &&
+                key !== 'input' &&
+                key !== 'output' &&
+                key !== 'metadata') {
+                otelAttributes[key] = value;
+            }
+        }
+        this.otelSpan.setAttributes(otelAttributes);
+        return this;
+    }
+}
+/**
+ * PingOps span wrapper for tracking operations
+ *
+ * Provides a convenient wrapper around OpenTelemetry spans with PingOps-specific
+ * attribute handling and lifecycle management.
+ */
+export class PingopsSpan extends PingopsBaseSpan {
+    constructor(otelSpan) {
+        super(otelSpan);
+    }
+}
+/**
+ * Creates an OpenTelemetry span with the PingOps tracer.
+ *
+ * @param params - Parameters for span creation
+ * @returns The created OpenTelemetry span
+ * @internal
+ */
+export function createOtelSpan(params) {
+    const provider = getPingopsTracerProvider();
+    const tracer = provider.getTracer('@pingops/sdk', '0.1.0');
+    return tracer.startSpan(params.name, {
+        startTime: params.startTime,
+        attributes: params.attributes,
+    }, createParentContext(params.parentSpanContext));
+}
+/**
+ * Creates a parent context from a span context.
+ *
+ * @param parentSpanContext - The span context to use as parent
+ * @returns The created context or undefined if no parent provided
+ * @internal
+ */
+function createParentContext(parentSpanContext) {
+    if (!parentSpanContext)
+        return undefined;
+    return trace.setSpanContext(context.active(), parentSpanContext);
+}
+//# sourceMappingURL=span-wrapper.js.map

package/dist/span-wrapper.js.map

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

package/dist/tracer-provider.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Tracer Provider with global state and isolated TracerProvider architecture
+ *
+ * This module provides an isolated TracerProvider that shares the same
+ * span processors (like PingopsSpanProcessor) with the main OpenTelemetry SDK.
+ * This ensures manual spans created via startSpan are properly processed.
+ *
+ * Architecture follows Langfuse's pattern with global state management.
+ */
+import type { TracerProvider } from "@opentelemetry/api";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+/**
+ * Sets an isolated TracerProvider for PingOps tracing operations.
+ *
+ * This allows PingOps to use its own TracerProvider instance, separate from
+ * the global OpenTelemetry TracerProvider. This is useful for avoiding conflicts
+ * with other OpenTelemetry instrumentation in the application.
+ *
+ * @param provider - The TracerProvider instance to use, or null to clear the isolated provider
+ * @public
+ */
+export declare function setPingopsTracerProvider(provider: TracerProvider | null): void;
+/**
+ * Gets the TracerProvider for PingOps tracing operations.
+ *
+ * Returns the isolated TracerProvider if one has been set via setPingopsTracerProvider(),
+ * otherwise falls back to the global OpenTelemetry TracerProvider.
+ *
+ * @returns The TracerProvider instance to use for PingOps tracing
+ * @public
+ */
+export declare function getPingopsTracerProvider(): TracerProvider;
+/**
+ * Initializes the isolated TracerProvider with the given span processors
+ *
+ * This creates a separate TracerProvider that shares the same span processors
+ * (like PingopsSpanProcessor) with the main SDK. This ensures manual spans
+ * are processed correctly.
+ *
+ * @param spanProcessors - Array of span processors to use (e.g., PingopsSpanProcessor)
+ * @param serviceName - Service name for resource attributes
+ * @deprecated Use setPingopsTracerProvider instead
+ */
+export declare function initializeTracerProvider(spanProcessors: SpanProcessor[], serviceName: string): void;
+/**
+ * Gets the isolated TracerProvider instance
+ *
+ * @returns The TracerProvider instance, or null if not initialized
+ * @deprecated Use getPingopsTracerProvider instead
+ */
+export declare function getTracerProvider(): NodeTracerProvider | null;
+/**
+ * Shuts down the TracerProvider and flushes remaining spans
+ */
+export declare function shutdownTracerProvider(): Promise<void>;
+//# sourceMappingURL=tracer-provider.d.ts.map

package/dist/tracer-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer-provider.d.ts","sourceRoot":"","sources":["../src/tracer-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AA4EnE;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAC9B,IAAI,CAcN;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,cAAc,CAezD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,aAAa,EAAE,EAC/B,WAAW,EAAE,MAAM,GAClB,IAAI,CA4BN;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,kBAAkB,GAAG,IAAI,CAG7D;AAED;;GAEG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CA6B5D"}