@revmax/agent-sdk/dist/utils/telemetry.d.ts

Official Node.js SDK for RevMax - billing, customer management, and usage tracking

import { Logger } from './logger';
/**
 * Telemetry options for SDK metrics
 */
export interface TelemetryOptions {
    /**
     * Whether telemetry is enabled
     */
    enabled?: boolean;
    /**
     * Custom handler for telemetry events
     */
    handler?: TelemetryHandler;
    /**
     * Sample rate for telemetry (0-1)
     * 1 = track every request, 0.1 = track 10% of requests
     */
    sampleRate?: number;
}
/**
 * Metrics data collected for each request
 */
export interface RequestMetrics {
    /**
     * Unique ID for the request
     */
    requestId: string;
    /**
     * Request method (GET, POST, etc)
     */
    method: string;
    /**
     * Normalized request path
     */
    path: string;
    /**
     * Timestamp when request started
     */
    startTime: number;
    /**
     * Timestamp when request ended
     */
    endTime?: number;
    /**
     * Duration of the request in milliseconds
     */
    duration?: number;
    /**
     * HTTP status code
     */
    statusCode?: number;
    /**
     * Whether the request was successful
     */
    success?: boolean;
    /**
     * Error message if request failed
     */
    errorMessage?: string;
    /**
     * Error type if request failed
     */
    errorType?: string;
    /**
     * Number of retry attempts
     */
    retryCount?: number;
}
/**
 * Telemetry handler function type
 */
export type TelemetryHandler = (metrics: RequestMetrics) => void;
/**
 * Default telemetry handler just logs to the console
 */
export declare const defaultTelemetryHandler: TelemetryHandler;
/**
 * SDK Telemetry class for tracking performance metrics
 */
export declare class Telemetry {
    private readonly enabled;
    private readonly sampleRate;
    private readonly handler;
    private readonly logger;
    private activeRequests;
    private requestCount;
    private successCount;
    private errorCount;
    private totalDuration;
    private errorTypes;
    /**
     * Create a new telemetry instance
     * @param options - Telemetry configuration options
     * @param logger - Logger instance
     */
    constructor(options?: TelemetryOptions, logger?: Logger);
    /**
     * Check if telemetry should be collected for this request
     * @returns Whether to collect telemetry
     */
    private shouldCollect;
    /**
     * Generate a request ID
     * @returns Unique request ID
     */
    generateRequestId(): string;
    /**
     * Normalize API path to remove specific IDs
     * @param path - Raw API path
     * @returns Normalized path
     */
    normalizePath(path: string): string;
    /**
     * Start tracking a request
     * @param method - HTTP method
     * @param path - Request path
     * @param requestId - Optional request ID (generated if not provided)
     * @returns Request ID and whether telemetry is being collected
     */
    startRequest(method: string, path: string, requestId?: string): {
        requestId: string;
        isTracked: boolean;
    };
    /**
     * End tracking a request
     * @param requestId - Request ID
     * @param statusCode - HTTP status code
     * @param error - Error object if request failed
     * @param retryCount - Number of retry attempts
     */
    endRequest(requestId: string, statusCode?: number, error?: Error, retryCount?: number): void;
    /**
     * Get current telemetry statistics
     * @returns Aggregated metrics
     */
    getStats(): {
        requestCount: number;
        successCount: number;
        errorCount: number;
        successRate: number;
        averageDuration: number;
        errorBreakdown: Record<string, number>;
    };
    /**
     * Reset all metrics
     */
    resetStats(): void;
}