spinal-obs-node/dist/index.d.ts

WithSpinal cost-aware OpenTelemetry SDK for Node.js

import { DiagLogLevel } from '@opentelemetry/api';

interface Scrubber {
    scrubAttributes(attributes: Record<string, unknown>): Record<string, unknown>;
}
interface ConfigureOptions {
    endpoint?: string;
    apiKey?: string;
    headers?: Record<string, string>;
    timeoutMs?: number;
    maxQueueSize?: number;
    maxExportBatchSize?: number;
    scheduleDelayMs?: number;
    exportTimeoutMs?: number;
    scrubber?: Scrubber;
    opentelemetryLogLevel?: DiagLogLevel;
    mode?: 'cloud' | 'local';
    localStorePath?: string;
    disableLocalMode?: boolean;
}
interface SpinalConfig extends Required<Omit<ConfigureOptions, 'scrubber' | 'opentelemetryLogLevel'>> {
    scrubber: Scrubber;
    opentelemetryLogLevel: DiagLogLevel;
}
declare function configure$1(opts?: ConfigureOptions): SpinalConfig;

declare function tag$1(tags?: Record<string, string | number | undefined> & {
    aggregationId?: string | number;
}): {
    dispose(): void;
};

declare function instrumentOpenAI$1(): Promise<void>;

declare function instrumentHTTP$1(): void;

declare function estimateCost(params: {
    model?: string;
    inputTokens?: number;
    outputTokens?: number;
}): number;

declare function shutdown(): Promise<void>;
declare function forceFlush(): Promise<void>;

declare const configure: typeof configure$1;
declare const tag: typeof tag$1;
declare const instrumentOpenAI: typeof instrumentOpenAI$1;
declare const instrumentHTTP: typeof instrumentHTTP$1;

declare function displayLocalData(options?: {
    limit?: number;
    format?: 'table' | 'json' | 'summary';
}): Promise<void>;

interface Span {
    name: string;
    trace_id: string;
    span_id: string;
    parent_span_id: string | null;
    start_time: [number, number];
    end_time: [number, number];
    status: {
        code: number;
    };
    attributes: Record<string, any>;
    events: any[];
    links: any[];
    instrumentation_info: {
        name: string;
        version: string;
    };
}
interface AnalyticsOptions {
    since?: string;
    format?: 'table' | 'json' | 'csv' | 'summary';
    byModel?: boolean;
    byAggregation?: boolean;
    trends?: boolean;
}
interface CostAnalysis {
    totalCost: number;
    totalCalls: number;
    averageCostPerCall: number;
    costByModel: Record<string, {
        cost: number;
        calls: number;
        percentage: number;
    }>;
    costByAggregation: Record<string, {
        cost: number;
        calls: number;
        percentage: number;
    }>;
    costTrends: Array<{
        date: string;
        cost: number;
        calls: number;
    }>;
}
interface UsageAnalysis {
    totalCalls: number;
    totalTokens: number;
    inputTokens: number;
    outputTokens: number;
    usageByModel: Record<string, {
        calls: number;
        tokens: number;
        percentage: number;
    }>;
    usageByAggregation: Record<string, {
        calls: number;
        tokens: number;
        percentage: number;
    }>;
    tokenEfficiency: {
        averageInputTokensPerCall: number;
        averageOutputTokensPerCall: number;
        tokenRatio: number;
    };
}
interface PerformanceAnalysis {
    totalRequests: number;
    successful: number;
    failed: number;
    successRate: number;
    responseTimes: {
        average: number;
        median: number;
        p95: number;
        fastest: number;
        slowest: number;
    };
    errors: {
        rateLimit: number;
        authentication: number;
        network: number;
        other: number;
    };
}
interface ModelAnalysis {
    models: Record<string, {
        calls: number;
        totalCost: number;
        avgCostPerCall: number;
        avgResponseTime: number;
        successRate: number;
        totalTokens: number;
    }>;
}
interface AggregationAnalysis {
    aggregations: Record<string, {
        calls: number;
        totalCost: number;
        avgCostPerCall: number;
        successRate: number;
        totalTokens: number;
    }>;
}
interface TrendsAnalysis {
    usageTrends: {
        dailyAverageCalls: number;
        peakUsage: {
            date: string;
            calls: number;
        };
        growthRate: number;
    };
    costTrends: {
        dailyAverageCost: number;
        peakCost: {
            date: string;
            cost: number;
        };
        costPerCallTrend: 'increasing' | 'decreasing' | 'stable';
    };
    performanceTrends: {
        responseTimeTrend: 'improving' | 'degrading' | 'stable';
        errorRateTrend: 'improving' | 'degrading' | 'stable';
        successRateTrend: 'improving' | 'degrading' | 'stable';
    };
}
interface OptimizationRecommendations {
    costOptimization: string[];
    performanceOptimization: string[];
    usageOptimization: string[];
}
interface ResponseAnalysis {
    totalResponses: number;
    averageResponseSize: number;
    responseSizeDistribution: {
        small: number;
        medium: number;
        large: number;
    };
    contentPatterns: {
        averageResponseLength: number;
        commonPhrases: string[];
        responseTypes: Record<string, number>;
    };
    errorAnalysis: {
        totalErrors: number;
        errorTypes: Record<string, number>;
        errorMessages: string[];
        successRate: number;
    };
    modelResponseQuality: Record<string, {
        averageResponseLength: number;
        averageResponseSize: number;
        successRate: number;
        commonErrors: string[];
    }>;
}
interface ContentInsights {
    responsePatterns: {
        shortResponses: number;
        mediumResponses: number;
        longResponses: number;
    };
    finishReasons: Record<string, number>;
    responseQuality: {
        averageTokensPerCharacter: number;
        responseEfficiency: number;
    };
    commonErrors: {
        rateLimit: number;
        authentication: number;
        modelNotFound: number;
        other: number;
    };
}
declare class Analytics {
    private spans;
    private spansPath;
    constructor(spansPath?: string);
    private loadSpans;
    private filterSpansByTime;
    private isOpenAISpan;
    private getSpanDuration;
    analyzeCosts(options?: AnalyticsOptions): CostAnalysis;
    analyzeUsage(options?: AnalyticsOptions): UsageAnalysis;
    analyzePerformance(options?: AnalyticsOptions): PerformanceAnalysis;
    analyzeModels(options?: AnalyticsOptions): ModelAnalysis;
    analyzeAggregations(options?: AnalyticsOptions): AggregationAnalysis;
    analyzeTrends(options?: AnalyticsOptions): TrendsAnalysis;
    getOptimizationRecommendations(options?: AnalyticsOptions): OptimizationRecommendations;
    analyzeResponses(options?: AnalyticsOptions): ResponseAnalysis;
    getContentInsights(options?: AnalyticsOptions): ContentInsights;
    private calculateCostTrends;
}

export { type AggregationAnalysis, Analytics, type AnalyticsOptions, type ConfigureOptions, type ContentInsights, type CostAnalysis, type ModelAnalysis, type OptimizationRecommendations, type PerformanceAnalysis, type ResponseAnalysis, type Scrubber, type Span, type TrendsAnalysis, type UsageAnalysis, configure, displayLocalData, estimateCost, forceFlush, instrumentHTTP, instrumentOpenAI, shutdown, tag };