Telemetry and Monitoring

/**
 * Telemetry target destinations
 */
enum TelemetryTarget {
  /** Google Cloud Platform */
  GCP = 'gcp',
  /** Local telemetry collection */
  LOCAL = 'local'
}

/**
 * Initialize telemetry system
 * @param target - Telemetry target destination
 * @param options - Additional initialization options
 */
function initializeTelemetry(
  target: TelemetryTarget,
  options?: {
    endpoint?: string;
    apiKey?: string;
    sampleRate?: number;
    enableTracing?: boolean;
    enableMetrics?: boolean;
    enableLogging?: boolean;
  }
): void;

/**
 * Shutdown telemetry system and flush pending data
 */
function shutdownTelemetry(): Promise<void>;

/**
 * Check if telemetry SDK is initialized
 * @returns True if telemetry is initialized
 */
function isTelemetrySdkInitialized(): boolean;

/**
 * Default telemetry target
 */
const DEFAULT_TELEMETRY_TARGET: TelemetryTarget;

/**
 * Default OTLP endpoint for telemetry
 */
const DEFAULT_OTLP_ENDPOINT: string;

/**
 * Log CLI configuration settings
 * @param config - Configuration object
 * @param metadata - Additional metadata
 */
function logCliConfiguration(
  config: any,
  metadata?: Record<string, any>
): void;

/**
 * Log user prompt interaction
 * @param prompt - User prompt text
 * @param metadata - Additional metadata
 */
function logUserPrompt(
  prompt: string,
  metadata?: {
    length?: number;
    language?: string;
    sessionId?: string;
  }
): void;

/**
 * Log tool call execution
 * @param toolName - Name of the tool
 * @param params - Tool parameters
 * @param result - Tool execution result
 * @param metadata - Additional metadata
 */
function logToolCall(
  toolName: string,
  params: any,
  result?: any,
  metadata?: {
    duration?: number;
    success?: boolean;
    error?: string;
  }
): void;

/**
 * Log API request to AI services
 * @param model - Model name
 * @param request - Request details
 * @param metadata - Additional metadata
 */
function logApiRequest(
  model: string,
  request: any,
  metadata?: {
    tokens?: number;
    endpoint?: string;
    requestId?: string;
  }
): void;

/**
 * Log API error responses
 * @param error - Error details
 * @param context - Error context
 */
function logApiError(
  error: any,
  context?: {
    model?: string;
    endpoint?: string;
    requestId?: string;
  }
): void;

/**
 * Log API response details
 * @param response - Response details
 * @param metadata - Additional metadata
 */
function logApiResponse(
  response: any,
  metadata?: {
    tokens?: number;
    duration?: number;
    model?: string;
  }
): void;

/**
 * Log flash fallback usage
 * @param originalModel - Original model that failed
 * @param fallbackModel - Fallback model used
 * @param reason - Reason for fallback
 */
function logFlashFallback(
  originalModel: string,
  fallbackModel: string,
  reason: string
): void;

/**
 * Log slash command usage
 * @param command - Slash command name
 * @param args - Command arguments
 * @param metadata - Additional metadata
 */
function logSlashCommand(
  command: string,
  args: any[],
  metadata?: {
    success?: boolean;
    duration?: number;
  }
): void;

/**
 * Log conversation finished event
 * @param sessionId - Session identifier
 * @param metadata - Conversation metadata
 */
function logConversationFinishedEvent(
  sessionId: string,
  metadata?: {
    duration?: number;
    messageCount?: number;
    toolCallCount?: number;
  }
): void;

/**
 * Log kitty sequence overflow events
 * @param sequenceLength - Length of the sequence
 * @param metadata - Additional metadata
 */
function logKittySequenceOverflow(
  sequenceLength: number,
  metadata?: Record<string, any>
): void;

/**
 * Log chat compression events
 * @param originalTokens - Original token count
 * @param compressedTokens - Compressed token count
 * @param compressionRatio - Compression ratio
 */
function logChatCompression(
  originalTokens: number,
  compressedTokens: number,
  compressionRatio: number
): void;

/**
 * Base event class for telemetry
 */
abstract class TelemetryEvent {
  constructor(
    public readonly eventType: string,
    public readonly timestamp: Date = new Date()
  );
  
  abstract toJson(): Record<string, any>;
}

/**
 * End session event
 */
class EndSessionEvent extends TelemetryEvent {
  constructor(
    public readonly sessionId: string,
    public readonly duration: number,
    public readonly metadata?: Record<string, any>
  );
  
  toJson(): Record<string, any>;
}

/**
 * User prompt event
 */
class UserPromptEvent extends TelemetryEvent {
  constructor(
    public readonly prompt: string,
    public readonly length: number,
    public readonly sessionId?: string
  );
  
  toJson(): Record<string, any>;
}

/**
 * API request event
 */
class ApiRequestEvent extends TelemetryEvent {
  constructor(
    public readonly model: string,
    public readonly endpoint: string,
    public readonly requestSize: number,
    public readonly requestId?: string
  );
  
  toJson(): Record<string, any>;
}

/**
 * API error event
 */
class ApiErrorEvent extends TelemetryEvent {
  constructor(
    public readonly error: string,
    public readonly statusCode: number,
    public readonly model?: string,
    public readonly requestId?: string
  );
  
  toJson(): Record<string, any>;
}

/**
 * API response event
 */
class ApiResponseEvent extends TelemetryEvent {
  constructor(
    public readonly model: string,
    public readonly responseSize: number,
    public readonly duration: number,
    public readonly tokens?: number
  );
  
  toJson(): Record<string, any>;
}

/**
 * Flash fallback event
 */
class FlashFallbackEvent extends TelemetryEvent {
  constructor(
    public readonly originalModel: string,
    public readonly fallbackModel: string,
    public readonly reason: string
  );
  
  toJson(): Record<string, any>;
}

/**
 * Start session event
 */
class StartSessionEvent extends TelemetryEvent {
  constructor(
    public readonly sessionId: string,
    public readonly metadata?: Record<string, any>
  );
  
  toJson(): Record<string, any>;
}

/**
 * Tool call event
 */
class ToolCallEvent extends TelemetryEvent {
  constructor(
    public readonly toolName: string,
    public readonly parameters: any,
    public readonly result?: any,
    public readonly duration?: number,
    public readonly success?: boolean
  );
  
  toJson(): Record<string, any>;
}

/**
 * Conversation finished event
 */
class ConversationFinishedEvent extends TelemetryEvent {
  constructor(
    public readonly sessionId: string,
    public readonly messageCount: number,
    public readonly duration: number,
    public readonly toolCallCount?: number
  );
  
  toJson(): Record<string, any>;
}

/**
 * Kitty sequence overflow event
 */
class KittySequenceOverflowEvent extends TelemetryEvent {
  constructor(
    public readonly sequenceLength: number,
    public readonly metadata?: Record<string, any>
  );
  
  toJson(): Record<string, any>;
}

/**
 * High water mark tracker for monitoring peak values
 */
class HighWaterMarkTracker {
  constructor(
    private readonly metricName: string,
    private readonly reportingInterval: number = 60000
  );
  
  /**
   * Record a new value
   * @param value - Value to record
   */
  record(value: number): void;
  
  /**
   * Get current high water mark
   * @returns Current peak value
   */
  getHighWaterMark(): number;
  
  /**
   * Reset high water mark
   */
  reset(): void;
  
  /**
   * Start automatic reporting
   */
  startReporting(): void;
  
  /**
   * Stop automatic reporting
   */
  stopReporting(): void;
}

/**
 * Rate limiter for telemetry events
 */
class RateLimiter {
  constructor(
    private readonly maxEvents: number,
    private readonly windowMs: number
  );
  
  /**
   * Check if event should be allowed
   * @param eventKey - Event identifier
   * @returns True if event should be allowed
   */
  shouldAllow(eventKey: string): boolean;
  
  /**
   * Get current rate limit status
   * @param eventKey - Event identifier
   * @returns Rate limit status
   */
  getStatus(eventKey: string): {
    remainingEvents: number;
    resetTime: Date;
  };
  
  /**
   * Reset rate limit for event
   * @param eventKey - Event identifier
   */
  reset(eventKey: string): void;
}

/**
 * Get current session identifier
 * @returns Session ID string
 */
const sessionId: string;

/**
 * Generate new session identifier
 * @returns New session ID
 */
function generateSessionId(): string;

/**
 * Set current session identifier
 * @param id - Session ID to set
 */
function setSessionId(id: string): void;

/**
 * Browser detection and utilities
 */
namespace BrowserUtils {
  /**
   * Check if running in browser environment
   * @returns True if in browser
   */
  function isBrowser(): boolean;
  
  /**
   * Get browser information
   * @returns Browser details
   */
  function getBrowserInfo(): {
    name: string;
    version: string;
    platform: string;
    userAgent: string;
  };
  
  /**
   * Get page performance metrics
   * @returns Performance metrics
   */
  function getPerformanceMetrics(): {
    loadTime: number;
    domContentLoaded: number;
    firstPaint: number;
    firstContentfulPaint: number;
  };
  
  /**
   * Track page view
   * @param page - Page identifier
   * @param metadata - Additional metadata
   */
  function trackPageView(
    page: string,
    metadata?: Record<string, any>
  ): void;
}

// Re-exported OpenTelemetry APIs
export * from '@opentelemetry/api';
export * from '@opentelemetry/semantic-conventions';

/**
 * Get OpenTelemetry tracer instance
 * @param name - Tracer name
 * @returns Tracer instance
 */
function getTracer(name: string): any; // Tracer type from @opentelemetry/api

/**
 * Get OpenTelemetry meter instance
 * @param name - Meter name
 * @returns Meter instance
 */
function getMeter(name: string): any; // Meter type from @opentelemetry/api

/**
 * Create custom span
 * @param name - Span name
 * @param operation - Operation to trace
 * @returns Operation result
 */
function withSpan<T>(
  name: string,
  operation: (span: any) => T
): T;

import { 
  initializeTelemetry,
  TelemetryTarget,
  logUserPrompt,
  logToolCall,
  logApiRequest,
  UserPromptEvent,
  HighWaterMarkTracker,
  sessionId
} from '@google/gemini-cli-core';

// Initialize telemetry
initializeTelemetry(TelemetryTarget.GCP, {
  endpoint: 'https://telemetry.example.com',
  sampleRate: 0.1,
  enableTracing: true,
  enableMetrics: true
});

// Log user interactions
logUserPrompt('What files are in my project?', {
  length: 28,
  sessionId: sessionId,
  language: 'english'
});

// Log tool executions
const startTime = Date.now();
// ... tool execution ...
const endTime = Date.now();

logToolCall('ls', { path: '.' }, ['file1.ts', 'file2.ts'], {
  duration: endTime - startTime,
  success: true
});

// Log API interactions
logApiRequest('gemini-1.5-flash', {
  contents: [{ role: 'user', parts: [{ text: 'Hello' }] }]
}, {
  tokens: 150,
  requestId: 'req-123'
});

// Create structured events
const promptEvent = new UserPromptEvent(
  'Analyze this codebase',
  20,
  sessionId
);

console.log('Event data:', promptEvent.toJson());

// High water mark tracking
const memoryTracker = new HighWaterMarkTracker('memory_usage', 30000);
memoryTracker.startReporting();

// Record memory usage periodically
setInterval(() => {
  const memoryUsage = process.memoryUsage().heapUsed;
  memoryTracker.record(memoryUsage);
}, 5000);

// Custom span tracing
import { withSpan } from '@google/gemini-cli-core';

const result = withSpan('file-processing', (span) => {
  span.setAttributes({
    'file.path': '/path/to/file.ts',
    'file.size': 1024
  });
  
  // Process file...
  return processFile('/path/to/file.ts');
});

// Shutdown telemetry on exit
process.on('beforeExit', async () => {
  await shutdownTelemetry();
});