genkitx-langfuse/lib/index.d.ts

Genkit AI framework plugin for Langfuse observability and tracing.

import { GenkitPlugin } from 'genkit/plugin';
import { TelemetryConfig } from 'genkit';
import { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
import { ExportResult } from '@opentelemetry/core';

/**
 * Configuration options for the Langfuse plugin.
 */
interface LangfuseConfig {
    /** Langfuse secret key for authentication */
    secretKey: string;
    /** Langfuse public key for authentication */
    publicKey: string;
    /** Langfuse API base URL (defaults to cloud) */
    baseUrl?: string;
    /** Enable debug logging */
    debug?: boolean;
    /** Number of events to batch before sending (default: 20) */
    flushAt?: number;
    /** Interval in ms to flush events (default: 10000) */
    flushInterval?: number;
    /** Custom cost calculation function */
    calculateCost?: (modelName: string, usage: TokenUsage$1) => number;
    /** Filter function to include/exclude spans */
    spanFilter?: (span: SpanData) => boolean;
    /** Force export in development environment (default: false) */
    forceDevExport?: boolean;
    /** Export timeout in milliseconds (default: 30000) */
    exportTimeoutMillis?: number;
    /** Maximum queue size for batch processor (default: 1000) */
    maxQueueSize?: number;
}
/**
 * Token usage information.
 */
interface TokenUsage$1 {
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
}
/**
 * Span data for filtering.
 */
interface SpanData {
    name: string;
    spanType?: string;
    path?: string;
    isRoot?: boolean;
}

/**
 * Telemetry provider that configures OpenTelemetry to export to Langfuse.
 */
declare class LangfuseTelemetryProvider {
    private config;
    private exporter?;
    constructor(config: LangfuseConfig);
    /**
     * Get the telemetry configuration for Genkit.
     */
    getConfig(): TelemetryConfig;
    /**
     * Shutdown the telemetry provider.
     */
    shutdown(): Promise<void>;
    /**
     * Force flush all pending telemetry data.
     */
    flush(): Promise<void>;
    /**
     * Create OpenTelemetry resource with Langfuse-specific attributes.
     */
    private createResource;
    /**
     * Create the span processor with Langfuse exporter.
     */
    private createSpanProcessor;
    /**
     * Validate the configuration.
     */
    private validateConfig;
    /**
     * Get the Langfuse SDK version.
     */
    private getLangfuseVersion;
}

/**
 * Langfuse OpenTelemetry span exporter that sends Genkit traces to Langfuse.
 */
declare class LangfuseExporter implements SpanExporter {
    private langfuse;
    private config;
    private exportCount;
    constructor(config: LangfuseConfig);
    /**
     * Export spans to Langfuse.
     */
    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
    /**
     * Test connection to Langfuse (for debugging).
     */
    private testConnection;
    /**
     * Shutdown the exporter.
     */
    shutdown(): Promise<void>;
    /**
     * Force flush all pending spans.
     */
    forceFlush(): Promise<void>;
    /**
     * Process a single span and send to Langfuse.
     */
    private processSpan;
    /**
     * Determine the Langfuse span type based on Genkit span data.
     */
    private determineSpanType;
    /**
     * Create a Langfuse generation (for LLM calls) using latest SDK v3 patterns.
     */
    private createGeneration;
    /**
     * Create a Langfuse trace (for root spans/flows).
     */
    private createTrace;
    /**
     * Create a Langfuse span (for intermediate operations).
     */
    private createSpan;
    /**
     * Extract model name from Genkit path.
     */
    private extractModelFromPath;
    /**
     * Extract provider name from Genkit path.
     */
    private extractProviderFromPath;
    /**
     * Safely parse JSON string.
     */
    private parseJSON;
}

/**
 * Extracts structured metadata from Genkit OpenTelemetry spans.
 */
declare class SpanMetadataExtractor {
    /**
     * Extract all relevant metadata from a span.
     */
    static extractMetadata(span: ReadableSpan): ExtractedMetadata;
    /**
     * Extract custom metadata from genkit:metadata:* attributes.
     */
    private static extractCustomMetadata;
    /**
     * Check if a span represents an LLM/model call.
     */
    static isModelSpan(span: ReadableSpan): boolean;
    /**
     * Check if a span is a root trace span.
     */
    static isRootSpan(span: ReadableSpan): boolean;
    /**
     * Extract usage information from output.
     */
    static extractUsage(span: ReadableSpan): TokenUsage | null;
    /**
     * Extract model configuration from input.
     */
    static extractModelConfig(span: ReadableSpan): Record<string, any> | null;
}
interface ExtractedMetadata {
    name?: string;
    path?: string;
    spanType?: string;
    input?: string;
    output?: string;
    state?: string;
    isRoot?: boolean;
    sessionId?: string;
    threadName?: string;
    userId?: string;
    metadata?: Record<string, any>;
}
interface TokenUsage {
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
}

/**
 * Langfuse plugin for Genkit that enables observability and tracing.
 *
 * @param config Langfuse configuration options
 * @returns Genkit plugin configuration
 *
 * @example
 * ```typescript
 * import { genkit } from 'genkit';
 * import { langfuse } from 'genkit-langfuse';
 *
 * const ai = genkit({
 *   plugins: [
 *     langfuse({
 *       secretKey: process.env.LANGFUSE_SECRET_KEY!,
 *       publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
 *       baseUrl: process.env.LANGFUSE_BASE_URL, // optional
 *       debug: true, // optional
 *     })
 *   ],
 * });
 * ```
 */
declare function langfuse(config: LangfuseConfig): GenkitPlugin;
/**
 * @deprecated Use `langfuse()` plugin instead
 * Legacy function for backward compatibility.
 */
declare function enableLangfuseTelemetry(config: LangfuseConfig): Promise<void>;
/**
 * Creates a Langfuse telemetry provider without enabling it globally.
 * Useful for custom telemetry setups.
 *
 * @param config Langfuse configuration options
 * @returns LangfuseTelemetryProvider instance
 */
declare function createLangfuseTelemetryProvider(config: LangfuseConfig): LangfuseTelemetryProvider;

export { type LangfuseConfig, LangfuseExporter, LangfuseTelemetryProvider, type SpanData, SpanMetadataExtractor, createLangfuseTelemetryProvider, enableLangfuseTelemetry, langfuse };