@juspay/neurolink 9.24.0 → 9.25.1

package/dist/lib/observability/exporters/datadogExporter.js

@@ -0,0 +1,197 @@
+/**
+ * Datadog Exporter
+ * Exports spans to Datadog APM platform
+ */
+import { logger } from "../../utils/logger.js";
+import { SpanStatus } from "../types/spanTypes.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Datadog exporter for enterprise APM integration
+ * Supports trace correlation and AI-specific custom metrics
+ */
+export class DatadogExporter extends BaseExporter {
+    apiKey;
+    appKey;
+    site;
+    service;
+    source;
+    logsEndpoint;
+    constructor(config) {
+        super("datadog", config);
+        this.apiKey = config.apiKey;
+        this.appKey = config.appKey;
+        this.site = config.site ?? "us1";
+        this.service = config.service ?? "neurolink";
+        this.source = config.source ?? "neurolink-ai";
+        const baseDomain = this.site === "us1" ? "datadoghq.com" : `${this.site}.datadoghq.com`;
+        this.logsEndpoint = `https://http-intake.logs.${baseDomain}/api/v2/logs`;
+    }
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        // Validate API key
+        try {
+            const validateUrl = this.site === "us1"
+                ? "https://api.datadoghq.com/api/v1/validate"
+                : `https://api.${this.site}.datadoghq.com/api/v1/validate`;
+            const response = await fetch(validateUrl, {
+                headers: {
+                    "DD-API-KEY": this.apiKey,
+                    ...(this.appKey && { "DD-APPLICATION-KEY": this.appKey }),
+                },
+            });
+            if (!response.ok) {
+                throw new Error(`Datadog API key validation failed: ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            // Allow initialization to proceed even if API is unreachable
+            logger.warn("[Datadog] Could not verify API connection:", error instanceof Error ? error.message : error);
+        }
+        this.initialized = true;
+        this.startFlushInterval(this.config.flushIntervalMs ?? 10000);
+    }
+    async exportSpan(span) {
+        const startTime = Date.now();
+        try {
+            const log = this.convertToDatadogLog(span);
+            const response = await fetch(this.logsEndpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "DD-API-KEY": this.apiKey,
+                },
+                body: JSON.stringify([log]),
+            });
+            if (!response.ok) {
+                throw new Error(`Export failed: ${response.statusText}`);
+            }
+            return this.createSuccessResult(1, Date.now() - startTime);
+        }
+        catch (error) {
+            return this.createFailureResult([span.spanId], error instanceof Error ? error.message : String(error), Date.now() - startTime);
+        }
+    }
+    async exportBatch(spans) {
+        const startTime = Date.now();
+        try {
+            const logs = spans.map((s) => this.convertToDatadogLog(s));
+            const response = await fetch(this.logsEndpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "DD-API-KEY": this.apiKey,
+                },
+                body: JSON.stringify(logs),
+            });
+            if (!response.ok) {
+                throw new Error(`Batch export failed: ${response.statusText}`);
+            }
+            return this.createSuccessResult(spans.length, Date.now() - startTime);
+        }
+        catch (error) {
+            return this.createFailureResult(spans.map((s) => s.spanId), error instanceof Error ? error.message : String(error), Date.now() - startTime);
+        }
+    }
+    async flush() {
+        if (this.buffer.length > 0) {
+            const spans = [...this.buffer];
+            this.buffer = [];
+            await this.exportBatch(spans);
+        }
+    }
+    async shutdown() {
+        await this.flush();
+        this.stopFlushInterval();
+        this.initialized = false;
+    }
+    async healthCheck() {
+        try {
+            await this.withRetry(() => this.ping(), "health check");
+            return this.createHealthStatus(true);
+        }
+        catch {
+            return this.createHealthStatus(false, ["Health check failed"]);
+        }
+    }
+    /**
+     * Verify connectivity to Datadog API
+     */
+    async ping() {
+        const validateUrl = this.site === "us1"
+            ? "https://api.datadoghq.com/api/v1/validate"
+            : `https://api.${this.site}.datadoghq.com/api/v1/validate`;
+        const response = await fetch(validateUrl, {
+            headers: { "DD-API-KEY": this.apiKey },
+        });
+        if (!response.ok) {
+            throw new Error(`Datadog API validation failed: ${response.status}`);
+        }
+    }
+    /**
+     * Convert span to Datadog log format with trace correlation
+     */
+    convertToDatadogLog(span) {
+        return {
+            ddsource: this.source,
+            ddtags: this.buildTags(span),
+            hostname: process.env.HOSTNAME || "unknown",
+            message: `${span.type}: ${span.name}`,
+            service: this.service,
+            status: span.status === SpanStatus.ERROR ? "error" : "info",
+            timestamp: new Date(span.startTime).getTime(),
+            // Trace correlation
+            dd: {
+                trace_id: span.traceId,
+                span_id: span.spanId,
+            },
+            // AI-specific attributes
+            ai: {
+                provider: span.attributes["ai.provider"],
+                model: span.attributes["ai.model"],
+                tokens: {
+                    input: span.attributes["ai.tokens.input"],
+                    output: span.attributes["ai.tokens.output"],
+                    total: span.attributes["ai.tokens.total"],
+                },
+                cost: span.attributes["ai.cost.total"],
+                duration_ms: span.durationMs,
+            },
+            // User context
+            usr: {
+                id: span.attributes["user.id"],
+                session_id: span.attributes["session.id"],
+            },
+            // Error details
+            ...(span.status === SpanStatus.ERROR && {
+                error: {
+                    message: span.statusMessage,
+                    type: span.attributes["error.type"],
+                    stack: span.attributes["error.stack"],
+                },
+            }),
+        };
+    }
+    /**
+     * Build Datadog tags from span attributes
+     */
+    buildTags(span) {
+        const tags = [
+            `env:${this.config.environment ?? "production"}`,
+            `version:${this.config.version ?? "unknown"}`,
+            `span_type:${span.type}`,
+        ];
+        if (span.attributes["ai.provider"]) {
+            tags.push(`ai_provider:${span.attributes["ai.provider"]}`);
+        }
+        if (span.attributes["ai.model"]) {
+            tags.push(`ai_model:${span.attributes["ai.model"]}`);
+        }
+        if (span.attributes["tool.name"]) {
+            tags.push(`tool:${span.attributes["tool.name"]}`);
+        }
+        return tags.join(",");
+    }
+}
+//# sourceMappingURL=datadogExporter.js.map

package/dist/lib/observability/exporters/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Observability exporters exports
+ */
+export { ArizeExporter } from "./arizeExporter.js";
+export { BaseExporter, NoOpExporter } from "./baseExporter.js";
+export { BraintrustExporter } from "./braintrustExporter.js";
+export { DatadogExporter } from "./datadogExporter.js";
+export { LaminarExporter } from "./laminarExporter.js";
+export { LangfuseExporter } from "./langfuseExporter.js";
+export { LangSmithExporter } from "./langsmithExporter.js";
+export { OtelExporter } from "./otelExporter.js";
+export { PostHogExporter } from "./posthogExporter.js";
+export { SentryExporter } from "./sentryExporter.js";

package/dist/lib/observability/exporters/index.js

@@ -0,0 +1,14 @@
+/**
+ * Observability exporters exports
+ */
+export { ArizeExporter } from "./arizeExporter.js";
+export { BaseExporter, NoOpExporter } from "./baseExporter.js";
+export { BraintrustExporter } from "./braintrustExporter.js";
+export { DatadogExporter } from "./datadogExporter.js";
+export { LaminarExporter } from "./laminarExporter.js";
+export { LangfuseExporter } from "./langfuseExporter.js";
+export { LangSmithExporter } from "./langsmithExporter.js";
+export { OtelExporter } from "./otelExporter.js";
+export { PostHogExporter } from "./posthogExporter.js";
+export { SentryExporter } from "./sentryExporter.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/observability/exporters/laminarExporter.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Laminar Exporter
+ * Exports spans to Laminar LLM tracing platform
+ * @see https://docs.laminar.run/
+ */
+import type { ExporterHealthStatus, ExportResult, LaminarExporterConfig, SpanData } from "../types/index.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Laminar exporter for LLM pipeline tracing and monitoring
+ * Supports detailed traces with input/output tracking
+ */
+export declare class LaminarExporter extends BaseExporter {
+    private readonly apiKey;
+    private readonly projectApiKey?;
+    private readonly baseUrl;
+    constructor(config: LaminarExporterConfig);
+    initialize(): Promise<void>;
+    /**
+     * Get authorization headers
+     */
+    private getHeaders;
+    exportSpan(span: SpanData): Promise<ExportResult>;
+    exportBatch(spans: SpanData[]): Promise<ExportResult>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    healthCheck(): Promise<ExporterHealthStatus>;
+    /**
+     * Verify connectivity to Laminar API
+     */
+    protected ping(): Promise<void>;
+    /**
+     * Convert span to Laminar trace format
+     */
+    private convertToLaminarTrace;
+    /**
+     * Map NeuroLink span type to Laminar type
+     */
+    private mapSpanTypeToLaminarType;
+    /**
+     * Map span status to Laminar status format
+     */
+    private mapSpanStatus;
+    /**
+     * Extract additional metadata from span attributes
+     * Filters out standard attributes that are already handled
+     */
+    private extractMetadata;
+}

package/dist/lib/observability/exporters/laminarExporter.js

@@ -0,0 +1,303 @@
+/**
+ * Laminar Exporter
+ * Exports spans to Laminar LLM tracing platform
+ * @see https://docs.laminar.run/
+ */
+import { logger } from "../../utils/logger.js";
+import { SpanStatus, SpanType } from "../types/spanTypes.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Laminar exporter for LLM pipeline tracing and monitoring
+ * Supports detailed traces with input/output tracking
+ */
+export class LaminarExporter extends BaseExporter {
+    apiKey;
+    projectApiKey;
+    baseUrl;
+    constructor(config) {
+        super("laminar", config);
+        this.apiKey = config.apiKey;
+        this.projectApiKey = config.projectApiKey;
+        this.baseUrl = config.baseUrl ?? "https://api.laminar.run";
+    }
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        // Verify API key by making a test call
+        try {
+            const response = await fetch(`${this.baseUrl}/v1/health`, {
+                headers: this.getHeaders(),
+            });
+            if (!response.ok) {
+                logger.warn("[Laminar] Could not verify API connection:", response.statusText);
+            }
+        }
+        catch (error) {
+            logger.warn("[Laminar] Could not verify API connection:", error instanceof Error ? error.message : error);
+        }
+        this.initialized = true;
+        this.startFlushInterval(this.config.flushIntervalMs ?? 5000);
+    }
+    /**
+     * Get authorization headers
+     */
+    getHeaders() {
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        // Add project API key if provided
+        if (this.projectApiKey) {
+            headers["X-Project-Api-Key"] = this.projectApiKey;
+        }
+        return headers;
+    }
+    async exportSpan(span) {
+        const startTime = Date.now();
+        try {
+            const trace = this.convertToLaminarTrace(span);
+            const response = await fetch(`${this.baseUrl}/v1/traces`, {
+                method: "POST",
+                headers: this.getHeaders(),
+                body: JSON.stringify(trace),
+            });
+            if (!response.ok) {
+                throw new Error(`Export failed: ${response.statusText}`);
+            }
+            return this.createSuccessResult(1, Date.now() - startTime);
+        }
+        catch (error) {
+            return this.createFailureResult([span.spanId], error instanceof Error ? error.message : String(error), Date.now() - startTime);
+        }
+    }
+    async exportBatch(spans) {
+        const startTime = Date.now();
+        try {
+            const traces = spans.map((s) => this.convertToLaminarTrace(s));
+            const response = await fetch(`${this.baseUrl}/v1/traces/batch`, {
+                method: "POST",
+                headers: this.getHeaders(),
+                body: JSON.stringify({ traces }),
+            });
+            if (!response.ok) {
+                throw new Error(`Batch export failed: ${response.statusText}`);
+            }
+            return this.createSuccessResult(spans.length, Date.now() - startTime);
+        }
+        catch (error) {
+            return this.createFailureResult(spans.map((s) => s.spanId), error instanceof Error ? error.message : String(error), Date.now() - startTime);
+        }
+    }
+    async flush() {
+        if (this.buffer.length > 0) {
+            const spans = [...this.buffer];
+            this.buffer = [];
+            await this.exportBatch(spans);
+        }
+    }
+    async shutdown() {
+        await this.flush();
+        this.stopFlushInterval();
+        this.initialized = false;
+    }
+    async healthCheck() {
+        try {
+            await this.withRetry(() => this.ping(), "health check");
+            return this.createHealthStatus(true);
+        }
+        catch {
+            return this.createHealthStatus(false, ["Health check failed"]);
+        }
+    }
+    /**
+     * Verify connectivity to Laminar API
+     */
+    async ping() {
+        const response = await fetch(`${this.baseUrl}/v1/health`, {
+            headers: this.getHeaders(),
+        });
+        if (!response.ok) {
+            throw new Error(`Laminar API unreachable: ${response.status}`);
+        }
+    }
+    /**
+     * Convert span to Laminar trace format
+     */
+    convertToLaminarTrace(span) {
+        return {
+            // Core identifiers
+            trace_id: span.traceId,
+            span_id: span.spanId,
+            parent_span_id: span.parentSpanId,
+            // Trace metadata
+            name: span.name,
+            type: this.mapSpanTypeToLaminarType(span.type),
+            start_time: span.startTime,
+            end_time: span.endTime,
+            duration_ms: span.durationMs,
+            // Status
+            status: this.mapSpanStatus(span.status),
+            status_message: span.statusMessage,
+            // Model information
+            model: {
+                provider: span.attributes["ai.provider"],
+                name: span.attributes["ai.model"],
+                version: span.attributes["ai.model.version"],
+            },
+            // Token usage
+            usage: {
+                input_tokens: span.attributes["ai.tokens.input"],
+                output_tokens: span.attributes["ai.tokens.output"],
+                total_tokens: span.attributes["ai.tokens.total"],
+                cache_read_tokens: span.attributes["ai.tokens.cache_read"],
+                cache_creation_tokens: span.attributes["ai.tokens.cache_creation"],
+                reasoning_tokens: span.attributes["ai.tokens.reasoning"],
+            },
+            // Cost tracking
+            cost: {
+                input: span.attributes["ai.cost.input"],
+                output: span.attributes["ai.cost.output"],
+                total: span.attributes["ai.cost.total"],
+                currency: span.attributes["ai.cost.currency"] || "USD",
+            },
+            // Generation parameters
+            parameters: {
+                temperature: span.attributes["ai.temperature"],
+                max_tokens: span.attributes["ai.max_tokens"],
+                top_p: span.attributes["ai.top_p"],
+                stop_sequences: span.attributes["ai.stop_sequences"],
+            },
+            // Input/Output
+            input: span.attributes["input"],
+            output: span.attributes["output"],
+            // Tool information
+            tool: span.attributes["tool.name"]
+                ? {
+                    name: span.attributes["tool.name"],
+                    server: span.attributes["tool.server"],
+                    success: span.attributes["tool.success"],
+                }
+                : undefined,
+            // Error information
+            error: span.status === SpanStatus.ERROR
+                ? {
+                    type: span.attributes["error.type"],
+                    message: span.attributes["error.message"],
+                    stack: span.attributes["error.stack"],
+                }
+                : undefined,
+            // User and session context
+            context: {
+                user_id: span.attributes["user.id"],
+                session_id: span.attributes["session.id"],
+                environment: span.attributes["deployment.environment"] || this.config.environment,
+                service: {
+                    name: span.attributes["service.name"],
+                    version: span.attributes["service.version"] || this.config.version,
+                },
+            },
+            // Events
+            events: span.events.map((event) => ({
+                name: event.name,
+                timestamp: event.timestamp,
+                attributes: event.attributes,
+            })),
+            // Links to related spans
+            links: span.links.map((link) => ({
+                trace_id: link.traceId,
+                span_id: link.spanId,
+                attributes: link.attributes,
+            })),
+            // Additional metadata
+            metadata: this.extractMetadata(span.attributes),
+        };
+    }
+    /**
+     * Map NeuroLink span type to Laminar type
+     */
+    mapSpanTypeToLaminarType(type) {
+        const typeMap = {
+            [SpanType.AGENT_RUN]: "agent",
+            [SpanType.WORKFLOW_STEP]: "workflow",
+            [SpanType.TOOL_CALL]: "tool",
+            [SpanType.MODEL_GENERATION]: "llm",
+            [SpanType.EMBEDDING]: "embedding",
+            [SpanType.RETRIEVAL]: "retrieval",
+            [SpanType.MEMORY]: "memory",
+            [SpanType.CONTEXT_COMPACTION]: "custom",
+            [SpanType.RAG]: "retrieval",
+            [SpanType.EVALUATION]: "custom",
+            [SpanType.MCP_TRANSPORT]: "tool",
+            [SpanType.MEDIA_GENERATION]: "llm",
+            [SpanType.PPT_GENERATION]: "custom",
+            [SpanType.WORKFLOW]: "workflow",
+            [SpanType.TTS]: "custom",
+            [SpanType.SERVER_REQUEST]: "custom",
+            [SpanType.CUSTOM]: "custom",
+        };
+        return typeMap[type] || "custom";
+    }
+    /**
+     * Map span status to Laminar status format
+     */
+    mapSpanStatus(status) {
+        switch (status) {
+            case SpanStatus.OK:
+                return "success";
+            case SpanStatus.ERROR:
+                return "error";
+            default:
+                return "unset";
+        }
+    }
+    /**
+     * Extract additional metadata from span attributes
+     * Filters out standard attributes that are already handled
+     */
+    extractMetadata(attributes) {
+        const standardKeys = new Set([
+            "service.name",
+            "service.version",
+            "deployment.environment",
+            "user.id",
+            "session.id",
+            "ai.provider",
+            "ai.model",
+            "ai.model.version",
+            "ai.tokens.input",
+            "ai.tokens.output",
+            "ai.tokens.total",
+            "ai.tokens.cache_read",
+            "ai.tokens.cache_creation",
+            "ai.tokens.reasoning",
+            "ai.cost.input",
+            "ai.cost.output",
+            "ai.cost.total",
+            "ai.cost.currency",
+            "ai.temperature",
+            "ai.max_tokens",
+            "ai.top_p",
+            "ai.stop_sequences",
+            "tool.name",
+            "tool.server",
+            "tool.success",
+            "error.type",
+            "error.message",
+            "error.stack",
+            "error",
+            "input",
+            "output",
+            "expected",
+            "scores",
+        ]);
+        const metadata = {};
+        for (const [key, value] of Object.entries(attributes)) {
+            if (!standardKeys.has(key) && value !== undefined) {
+                metadata[key] = value;
+            }
+        }
+        return metadata;
+    }
+}
+//# sourceMappingURL=laminarExporter.js.map

package/dist/lib/observability/exporters/langfuseExporter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Langfuse Exporter
+ * Exports spans to Langfuse observability platform
+ */
+import type { ExporterHealthStatus, ExportResult, LangfuseExporterConfig, SpanData } from "../types/index.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Langfuse exporter for LLM observability
+ * Supports traces, generations, spans, and scores
+ */
+export declare class LangfuseExporter extends BaseExporter {
+    private readonly publicKey;
+    private readonly secretKey;
+    private readonly baseUrl;
+    private readonly release?;
+    constructor(config: LangfuseExporterConfig);
+    initialize(): Promise<void>;
+    exportSpan(span: SpanData): Promise<ExportResult>;
+    exportBatch(spans: SpanData[]): Promise<ExportResult>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    healthCheck(): Promise<ExporterHealthStatus>;
+    /**
+     * Verify connectivity to Langfuse API
+     */
+    protected ping(): Promise<void>;
+    /**
+     * Create a Langfuse trace
+     */
+    private createTrace;
+    /**
+     * Create a Langfuse span
+     */
+    private createSpan;
+    /**
+     * Create a Langfuse generation (for LLM calls)
+     */
+    private createGeneration;
+    /**
+     * Make API call to Langfuse
+     */
+    private apiCall;
+    /**
+     * Extract tags from span attributes
+     */
+    private extractTags;
+}