@omen.foundation/node-microservice-runtime 0.1.65 → 0.1.67

package/src/collector-manager.ts

@@ -1,1267 +0,0 @@
-import { spawn, ChildProcess } from 'child_process';
-import { createWriteStream, existsSync, chmodSync, mkdirSync } from 'fs';
-import { join, dirname } from 'path';
-import { pipeline } from 'stream/promises';
-import { createGunzip } from 'zlib';
-import { createHash } from 'node:crypto';
-import { createServer } from 'net';
-import type { Logger } from 'pino';
-import pino from 'pino';
-import dgram from 'dgram';
-import deasync from 'deasync';
-import type { EnvironmentConfig } from './types.js';
-import { hostToHttpUrl } from './utils/urls.js';
-
-// Protocol is httpprotobuf 
-
-interface CollectorDiscoveryEntry {
-  version: string;
-  status: string;
-  pid: number;
-  otlpEndpoint: string;
-}
-
-export interface CollectorStatus {
-  isRunning: boolean;
-  isReady: boolean;
-  pid: number;
-  otlpEndpoint?: string;
-  version?: string;
-}
-
-const COLLECTOR_VERSION = '1.0.1'; // Match C# collector version (from collector-version.json)
-const COLLECTOR_DOWNLOAD_BASE = `https://collectors.beamable.com/version/${COLLECTOR_VERSION}`;
-const DISCOVERY_PORT = parseInt(process.env.BEAM_COLLECTOR_DISCOVERY_PORT || '8688', 10);
-
-/**
- * Finds a free TCP port (matching C# PortUtil.FreeTcpPort())
- */
-function findFreePort(): Promise<number> {
-  return new Promise((resolve, reject) => {
-    const server = createServer();
-    server.listen(0, () => {
-      const address = server.address();
-      const port = typeof address === 'object' && address !== null ? address.port : 0;
-      server.close(() => {
-        if (port > 0) {
-          resolve(port);
-        } else {
-          // Fallback to a default port if something went wrong
-          resolve(9090);
-        }
-      });
-    });
-    server.on('error', (err) => {
-      reject(err);
-    });
-  });
-}
-
-// Global storage for collector process and errors (to prevent GC and track status)
-let globalCollectorProcess: ChildProcess | null = null;
-let globalCollectorStartError: string | null = null;
-let globalCollectorExitCode: number | null = null;
-let globalCollectorStderr: string[] = [];
-// Track if collector startup is in progress to prevent duplicate starts
-let globalCollectorStartupPromise: Promise<string | null> | null = null;
-let globalCollectorInitError: string | null = null; // Tracks errors from discoverOrStartCollector
-
-/**
- * ClickHouse credentials response from Beamable API
- */
-interface ClickHouseCredentials {
-  endpoint: string;
-  expiresAt?: string;
-  password: string;
-  username: string;
-}
-
-/**
- * Calculates Beamable signature for signed requests
- * Signature format: MD5(secret + pid + version + uriPathAndQuery + body) as Base64
- * Matches C# SignedRequesterHelper.CalculateSignature
- */
-function calculateSignature(
-  pid: string,
-  secret: string,
-  uriPathAndQuery: string,
-  body: string | null = null,
-  version: string = '1'
-): string {
-  let dataToSign = `${secret}${pid}${version}${uriPathAndQuery}`;
-  if (body) {
-    dataToSign += body;
-  }
-  
-  // MD5 hash to Base64 (matching C# implementation)
-  const hash = createHash('md5').update(dataToSign, 'utf8').digest('base64');
-  return hash;
-}
-
-/**
- * Extracts path and query from a URL
- */
-function getPathAndQuery(url: string): string {
-  try {
-    const urlObj = new URL(url);
-    return urlObj.pathname + urlObj.search;
-  } catch {
-    // If URL parsing fails, return as-is
-    return url;
-  }
-}
-
-/**
- * Fetches ClickHouse credentials from Beamable API
- * GET /api/beamo/otel/auth/writer/config
- * Requires signed request authentication (X-BEAM-SIGNATURE header)
- */
-export async function fetchClickHouseCredentials(
-  env: EnvironmentConfig
-): Promise<ClickHouseCredentials> {
-  const apiUrl = hostToHttpUrl(env.host);
-  const uriPath = '/api/beamo/otel/auth/writer/config';
-  const configUrl = new URL(uriPath, apiUrl).toString();
-  
-  // Create a minimal logger for verbose output
-  const verboseLogger = pino({ name: 'fetch-credentials', level: 'info' }, process.stdout);
-  verboseLogger.info(`[Credentials] Starting credential fetch from ${configUrl}...`);
-  
-  // Get secret from environment (required for signed requests)
-  const secret = process.env.SECRET;
-  if (!secret) {
-    verboseLogger.error('[Credentials] SECRET environment variable is missing');
-    throw new Error('SECRET environment variable is required to fetch ClickHouse credentials');
-  }
-  verboseLogger.info('[Credentials] SECRET found, calculating signature...');
-  
-  // Calculate signature for signed request (matching C# HttpSignedRequester)
-  const pathAndQuery = getPathAndQuery(uriPath);
-  const signature = calculateSignature(env.pid, secret, pathAndQuery, null, '1');
-  verboseLogger.info('[Credentials] Signature calculated, making API request...');
-  
-  // Build headers with signed authentication (matching C# HttpSignedRequester)
-  const headers: Record<string, string> = {
-    'Content-Type': 'application/json',
-    Accept: 'application/json',
-    'X-BEAM-SCOPE': `${env.cid}.${env.pid}`,
-    'X-BEAM-SIGNATURE': signature,
-  };
-  
-  const fetchStartTime = Date.now();
-  const response = await fetch(configUrl, {
-    method: 'GET',
-    headers,
-  });
-  const fetchElapsed = Date.now() - fetchStartTime;
-  verboseLogger.info(`[Credentials] API request completed in ${fetchElapsed}ms, status: ${response.status}`);
-  
-  if (!response.ok) {
-    const errorText = await response.text().catch(() => 'Unknown error');
-    verboseLogger.error(`[Credentials] API request failed: ${response.status} ${response.statusText}`);
-    throw new Error(`Failed to fetch ClickHouse credentials from ${configUrl}: ${response.status} ${response.statusText} - ${errorText.substring(0, 200)}`);
-  }
-  
-  verboseLogger.info('[Credentials] Parsing response JSON...');
-  const credentials = await response.json() as ClickHouseCredentials;
-  
-  if (!credentials.endpoint || !credentials.username || !credentials.password) {
-    verboseLogger.error('[Credentials] Invalid response: missing required fields');
-    throw new Error('Invalid ClickHouse credentials response: missing required fields');
-  }
-  
-  verboseLogger.info(`[Credentials] Successfully fetched credentials (endpoint: ${credentials.endpoint}, username: ${credentials.username})`);
-  return credentials;
-}
-
-/**
- * Gets the collector storage directory (similar to C# LocalApplicationData/beam/collectors/version)
- * Checks production location first (pre-installed in Docker), then falls back to temp directory
- */
-function getCollectorStoragePath(): string {
-  // Check production location first (pre-installed in Docker image at /opt/beam/collectors)
-  // This avoids runtime download delays (~12 seconds)
-  const productionPath = '/opt/beam/collectors';
-  const productionVersionPath = join(productionPath, COLLECTOR_VERSION);
-  
-  // Use production path if it exists (Docker image pre-installed collector)
-  if (existsSync(productionPath)) {
-    return productionVersionPath;
-  }
-  
-  // Fallback to temp directory (local development without Docker)
-  const tempDir = process.env.TMPDIR || process.env.TMP || '/tmp';
-  return join(tempDir, 'beam', 'collectors', COLLECTOR_VERSION);
-}
-
-/**
- * Gets the collector binary name for the current platform
- */
-function getCollectorBinaryName(): string {
-  const platform = process.platform;
-  const arch = process.arch;
-  
-  // Match C# naming: collector-{osArchSuffix}
-  // C# returns "collector-linux-amd64", not "beamable-collector-linux-amd64"
-  if (platform === 'linux' && arch === 'x64') {
-    return 'collector-linux-amd64';
-  } else if (platform === 'linux' && arch === 'arm64') {
-    return 'collector-linux-arm64';
-  } else if (platform === 'darwin' && arch === 'x64') {
-    return 'collector-darwin-amd64';
-  } else if (platform === 'darwin' && arch === 'arm64') {
-    return 'collector-darwin-arm64';
-  } else if (platform === 'win32' && arch === 'x64') {
-    return 'collector-windows-amd64.exe';
-  }
-  
-  throw new Error(`Unsupported platform: ${platform} ${arch}`);
-}
-
-/**
- * Downloads and decompresses a gzipped file
- */
-async function downloadAndDecompressGzip(url: string, outputPath: string, makeExecutable: boolean = false): Promise<void> {
-  let response: Response;
-  try {
-    // Add timeout and better error handling
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), 30000); // 30 second timeout
-    
-    try {
-      response = await fetch(url, {
-        signal: controller.signal,
-        headers: {
-          'User-Agent': 'Beamable-Node-Microservice-Runtime/1.0',
-        },
-      });
-      clearTimeout(timeoutId);
-    } catch (fetchError) {
-      clearTimeout(timeoutId);
-      if (fetchError instanceof Error) {
-        // Extract underlying error details from cause
-        let underlyingError = '';
-        if ((fetchError as any).cause) {
-          const cause = (fetchError as any).cause;
-          if (cause instanceof Error) {
-            const causeCode = (cause as any).code;
-            underlyingError = ` (cause: ${cause.name} - ${cause.message}${causeCode ? ` [code: ${causeCode}]` : ''})`;
-          } else if (typeof cause === 'object' && cause.code) {
-            underlyingError = ` (cause code: ${cause.code})`;
-          }
-        }
-        
-        // Provide more context about the error
-        if (fetchError.name === 'AbortError') {
-          throw new Error(`Timeout downloading ${url} (30s limit exceeded)${underlyingError}`);
-        }
-        
-        // Check error code if available (Node.js system errors)
-        const errorCode = (fetchError as any).code || ((fetchError as any).cause?.code);
-        if (errorCode) {
-          if (errorCode === 'ENOTFOUND' || errorCode === 'EAI_AGAIN') {
-            throw new Error(`DNS resolution failed for ${url} (code: ${errorCode}). Check network connectivity and DNS settings.`);
-          }
-          if (errorCode === 'ECONNREFUSED') {
-            throw new Error(`Connection refused to ${url} (code: ${errorCode}). Server may be down or firewall blocking.`);
-          }
-          if (errorCode === 'ETIMEDOUT' || errorCode === 'ECONNRESET') {
-            throw new Error(`Connection timeout/reset to ${url} (code: ${errorCode}). Network may be slow or unreachable.`);
-          }
-          if (errorCode === 'CERT_HAS_EXPIRED' || errorCode === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE') {
-            throw new Error(`SSL/TLS certificate error connecting to ${url} (code: ${errorCode}): ${fetchError.message}`);
-          }
-        }
-        
-        // Check for common network errors in message
-        const errorMsg = fetchError.message.toLowerCase();
-        if (errorMsg.includes('enotfound') || errorMsg.includes('dns')) {
-          throw new Error(`DNS resolution failed for ${url}. Check network connectivity and DNS settings.${underlyingError}`);
-        }
-        if (errorMsg.includes('econnrefused') || errorMsg.includes('connection refused')) {
-          throw new Error(`Connection refused to ${url}. Server may be down or firewall blocking.${underlyingError}`);
-        }
-        if (errorMsg.includes('etimedout') || errorMsg.includes('timeout')) {
-          throw new Error(`Connection timeout to ${url}. Network may be slow or unreachable.${underlyingError}`);
-        }
-        if (errorMsg.includes('certificate') || errorMsg.includes('ssl') || errorMsg.includes('tls')) {
-          throw new Error(`SSL/TLS error connecting to ${url}: ${fetchError.message}${underlyingError}`);
-        }
-        throw new Error(`Network error downloading ${url}: ${fetchError.name} - ${fetchError.message}${underlyingError}`);
-      }
-      throw new Error(`Network error downloading ${url}: ${String(fetchError)}`);
-    }
-  } catch (error) {
-    // Re-throw with more context
-    if (error instanceof Error) {
-      if (error.message.includes('Timeout') || error.message.includes('DNS') || error.message.includes('Connection')) {
-        throw error; // Already has good context
-      }
-      throw new Error(`Network error downloading ${url}: ${error.message}`);
-    }
-    throw new Error(`Network error downloading ${url}: ${String(error)}`);
-  }
-  
-  if (!response.ok) {
-    const errorText = await response.text().catch(() => '');
-    throw new Error(`HTTP ${response.status} downloading ${url}: ${response.statusText}${errorText ? ` - ${errorText.substring(0, 200)}` : ''}`);
-  }
-  
-  const dir = dirname(outputPath);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  
-  const gunzip = createGunzip();
-  const writeStream = createWriteStream(outputPath);
-  
-  await pipeline(response.body as any, gunzip, writeStream);
-  
-  if (makeExecutable && process.platform !== 'win32') {
-    try {
-      chmodSync(outputPath, 0o755);
-    } catch (error) {
-      console.error(`Failed to make ${outputPath} executable:`, error);
-    }
-  }
-}
-
-/**
- * Resolves the collector binary and config, downloading if needed
- */
-async function resolveCollector(allowDownload: boolean = true, logger?: Logger): Promise<{ binaryPath: string | null; configPath: string | null }> {
-  const basePath = getCollectorStoragePath();
-  const binaryName = getCollectorBinaryName();
-  const configName = 'clickhouse-config.yaml';
-  
-  const binaryPath = join(basePath, binaryName);
-  const configPath = join(basePath, configName);
-  
-  const itemsToDownload: Array<{ url: string; path: string; executable: boolean }> = [];
-  
-  if (!existsSync(binaryPath) && allowDownload) {
-    const binaryUrl = `${COLLECTOR_DOWNLOAD_BASE}/${binaryName}.gz`;
-    itemsToDownload.push({ url: binaryUrl, path: binaryPath, executable: true });
-    logger?.info(`[Collector] Will download binary from: ${binaryUrl}`);
-  } else if (existsSync(binaryPath)) {
-    logger?.info(`[Collector] Binary found at: ${binaryPath}`);
-  }
-  
-  if (!existsSync(configPath) && allowDownload) {
-    const configUrl = `${COLLECTOR_DOWNLOAD_BASE}/${configName}.gz`;
-    itemsToDownload.push({ url: configUrl, path: configPath, executable: false });
-    logger?.info(`[Collector] Will download config from: ${configUrl}`);
-  } else if (existsSync(configPath)) {
-    logger?.info(`[Collector] Config found at: ${configPath}`);
-  }
-  
-  // Download items in parallel for faster startup (binary and config simultaneously)
-  if (itemsToDownload.length > 0) {
-    logger?.info(`[Collector] Downloading ${itemsToDownload.length} item(s) in parallel...`);
-    const downloadPromises = itemsToDownload.map(async (item) => {
-      try {
-        logger?.info(`[Collector] Downloading ${item.url}...`);
-        await downloadAndDecompressGzip(item.url, item.path, item.executable);
-        logger?.info(`[Collector] Downloaded to ${item.path}`);
-      } catch (error) {
-        // Don't wrap the error again if it already contains the URL and details
-        const errorMsg = error instanceof Error ? error.message : String(error);
-        logger?.error(`[Collector] Failed to download ${item.url}: ${errorMsg}`);
-        // Only wrap if the error doesn't already contain the URL
-        if (error instanceof Error && errorMsg.includes(item.url)) {
-          throw error; // Error already has URL and context
-        }
-        throw new Error(`Failed to download collector ${item.executable ? 'binary' : 'config'} from ${item.url}: ${errorMsg}`);
-      }
-    });
-    
-    // Wait for all downloads to complete (or fail)
-    await Promise.all(downloadPromises);
-  }
-  
-  return {
-    binaryPath: existsSync(binaryPath) ? binaryPath : null,
-    configPath: existsSync(configPath) ? configPath : null,
-  };
-}
-
-/**
- * Discovers collector via UDP broadcast
- */
-function discoverCollectorViaUDP(timeoutMs: number = 1000): Promise<CollectorDiscoveryEntry | null> {
-  return new Promise((resolve) => {
-    const socket = dgram.createSocket('udp4');
-    const discovered: CollectorDiscoveryEntry[] = [];
-    let timeout: NodeJS.Timeout;
-    let resolved = false; // Guard to prevent double resolution
-    const startTime = Date.now();
-    
-    // Safety timeout - force resolve after timeout + 100ms buffer
-    const safetyTimeout = setTimeout(() => {
-      if (!resolved) {
-        console.log(`[UDP Discovery] Safety timeout triggered - forcing resolution`);
-        resolved = true;
-        try {
-          socket.removeAllListeners();
-          socket.close();
-        } catch (e) {
-          // Ignore
-        }
-        clearTimeout(timeout);
-        resolve(discovered.length > 0 ? discovered[0] : null);
-      }
-    }, timeoutMs + 100);
-    
-    const doResolve = (result: CollectorDiscoveryEntry | null) => {
-      if (!resolved) {
-        resolved = true;
-        clearTimeout(timeout);
-        clearTimeout(safetyTimeout);
-        try {
-          socket.removeAllListeners();
-          socket.close();
-        } catch (e) {
-          // Ignore
-        }
-        console.log(`[UDP Discovery] Resolving promise with result: ${result ? 'found' : 'null'}`);
-        resolve(result);
-      }
-    };
-    
-    socket.on('message', (msg) => {
-      try {
-        const message = JSON.parse(msg.toString()) as CollectorDiscoveryEntry;
-        // Check if version matches
-        if (message.version === COLLECTOR_VERSION && message.status === 'READY') {
-          discovered.push(message);
-          const elapsed = Date.now() - startTime;
-          console.log(`[UDP Discovery] Found collector after ${elapsed}ms: ${message.otlpEndpoint}`);
-          // Resolve immediately when collector found
-          doResolve(discovered[0]);
-        }
-      } catch (error) {
-        // Ignore parse errors
-      }
-    });
-    
-    socket.on('error', (err) => {
-      const elapsed = Date.now() - startTime;
-      console.log(`[UDP Discovery] Socket error after ${elapsed}ms: ${err.message}`);
-      doResolve(null);
-    });
-    
-    socket.bind(() => {
-      socket.setBroadcast(true);
-      console.log(`[UDP Discovery] Listening for collector broadcasts (timeout: ${timeoutMs}ms)...`);
-      
-      timeout = setTimeout(() => {
-        const elapsed = Date.now() - startTime;
-        if (discovered.length > 0) {
-          console.log(`[UDP Discovery] Timeout after ${elapsed}ms, found ${discovered.length} collector(s)`);
-        } else {
-          console.log(`[UDP Discovery] Timeout after ${elapsed}ms, no collector found`);
-        }
-        doResolve(discovered.length > 0 ? discovered[0] : null);
-      }, timeoutMs);
-    });
-  });
-}
-
-/**
- * Gets the current status of ClickHouse credentials (from env or API)
- */
-export function getClickHouseCredentialsStatus(): {
-  hasEndpoint: boolean;
-  hasUsername: boolean;
-  hasPassword: boolean;
-  source: 'environment' | 'api' | 'missing';
-} {
-  const hasEndpoint = !!process.env.BEAM_CLICKHOUSE_ENDPOINT;
-  const hasUsername = !!process.env.BEAM_CLICKHOUSE_USERNAME;
-  const hasPassword = !!process.env.BEAM_CLICKHOUSE_PASSWORD;
-  
-  if (hasEndpoint && hasUsername && hasPassword) {
-    return {
-      hasEndpoint: true,
-      hasUsername: true,
-      hasPassword: true,
-      source: 'environment',
-    };
-  }
-  
-  return {
-    hasEndpoint,
-    hasUsername,
-    hasPassword,
-    source: 'missing',
-  };
-}
-
-/**
- * Checks if collector is already running via UDP discovery
- */
-export async function isCollectorRunning(): Promise<CollectorStatus> {
-  // First, check if we have a global collector process reference
-  // If the process is running and we've seen "Everything is ready" in stderr, it's ready
-  if (globalCollectorProcess) {
-    // Check if process is still alive
-    try {
-      // Process is alive if we can access it and it hasn't exited
-      const processAlive = globalCollectorProcess.exitCode === null && 
-                           globalCollectorProcess.killed === false;
-      
-      if (processAlive) {
-        // Check if we've seen the "Everything is ready" message in stderr
-        // This is a reliable indicator that the collector is ready
-        const stderrText = globalCollectorStderr.join('\n');
-        const isReady = stderrText.includes('Everything is ready') || 
-                       stderrText.includes('Begin running and processing data');
-        
-        if (isReady) {
-          // Try UDP discovery to get the endpoint, but if it fails, use the configured endpoint
-          try {
-            const discovered = await discoverCollectorViaUDP(1000); // Shorter timeout since we know it's running
-            if (discovered && discovered.status === 'READY') {
-              return {
-                isRunning: true,
-                isReady: true,
-                pid: discovered.pid || globalCollectorProcess.pid || 0,
-                otlpEndpoint: discovered.otlpEndpoint,
-                version: discovered.version,
-              };
-            }
-          } catch {
-            // UDP discovery failed, but process is alive and has "Everything is ready" message
-            // Use the configured endpoint as fallback
-          }
-          
-          // Process is alive and we've seen "Everything is ready" - treat as ready
-          // Extract endpoint from environment or use default
-          const configuredEndpoint = process.env.BEAM_OTLP_HTTP_ENDPOINT || '0.0.0.0:4318';
-          return {
-            isRunning: true,
-            isReady: true,
-            pid: globalCollectorProcess.pid || 0,
-            otlpEndpoint: configuredEndpoint,
-            version: COLLECTOR_VERSION,
-          };
-        }
-      }
-    } catch {
-      // Process might have exited or is invalid
-    }
-  }
-  
-  // Try UDP discovery as fallback
-  try {
-    const udpStartTime = Date.now();
-    console.log('[UDP Discovery] Starting UDP discovery in isCollectorRunning()...');
-    console.log('[UDP Discovery] Calling discoverCollectorViaUDP(1000)...');
-    const discovered = await discoverCollectorViaUDP(1000); // Match C#: 1 second max (10 attempts × 100ms)
-    const udpElapsed = Date.now() - udpStartTime;
-    console.log(`[UDP Discovery] UDP discovery promise resolved after ${udpElapsed}ms, result: ${discovered ? 'found' : 'null'}`);
-    if (discovered) {
-      console.log(`[UDP Discovery] Found collector in ${udpElapsed}ms: ${discovered.otlpEndpoint}`);
-      return {
-        isRunning: true,
-        isReady: discovered.status === 'READY',
-        pid: discovered.pid,
-        otlpEndpoint: discovered.otlpEndpoint,
-        version: discovered.version,
-      };
-    } else {
-      console.log(`[UDP Discovery] No collector found after ${udpElapsed}ms, returning not running status`);
-    }
-  } catch (error) {
-    // Discovery failed, collector probably not running
-    const errorMsg = error instanceof Error ? error.message : String(error);
-    console.log(`[UDP Discovery] Error in isCollectorRunning(): ${errorMsg}`);
-    if (error instanceof Error && error.stack) {
-      console.log(`[UDP Discovery] Error stack: ${error.stack}`);
-    }
-  }
-  
-  console.log('[UDP Discovery] Returning default not-running status from isCollectorRunning()');
-  return {
-    isRunning: false,
-    isReady: false,
-    pid: 0,
-  };
-}
-
-/**
- * Sets default collector configuration environment variables in process.env
- * Matches C# CollectorManager.AddCollectorConfigurationToEnvironment()
- */
-function addCollectorConfigurationToEnvironment(): void {
-  const defaults: Record<string, string> = {
-    BEAM_CLICKHOUSE_PROCESSOR_TIMEOUT: '5s',
-    BEAM_CLICKHOUSE_PROCESSOR_BATCH_SIZE: '5000',
-    BEAM_CLICKHOUSE_EXPORTER_TIMEOUT: '5s',
-    BEAM_CLICKHOUSE_EXPORTER_QUEUE_SIZE: '1000',
-    BEAM_CLICKHOUSE_EXPORTER_RETRY_ENABLED: 'true',
-    BEAM_CLICKHOUSE_EXPORTER_RETRY_INITIAL_INTERVAL: '5s',
-    BEAM_CLICKHOUSE_EXPORTER_RETRY_MAX_INTERVAL: '30s',
-    BEAM_CLICKHOUSE_EXPORTER_RETRY_MAX_ELAPSED_TIME: '300s',
-  };
-  
-  // Only set if not already set (matching C# behavior)
-  for (const [key, defaultValue] of Object.entries(defaults)) {
-    if (!process.env[key]) {
-      process.env[key] = defaultValue;
-    }
-  }
-}
-
-/**
- * Sets ClickHouse credentials in process.env (matching C# CollectorManager.AddAuthEnvironmentVars)
- */
-export function addAuthEnvironmentVars(endpoint: string, username: string, password: string): void {
-  // Always set the values when explicitly provided (matching C# behavior)
-  // This ensures credentials fetched from API override any existing (potentially empty) values
-  // In Node.js, process.env is a writable object - setting properties here persists for the lifetime of the process
-  process.env.BEAM_CLICKHOUSE_ENDPOINT = endpoint;
-  process.env.BEAM_CLICKHOUSE_USERNAME = username;
-  process.env.BEAM_CLICKHOUSE_PASSWORD = password;
-  
-  // Verify they were actually set (for debugging)
-  if (!process.env.BEAM_CLICKHOUSE_ENDPOINT || !process.env.BEAM_CLICKHOUSE_USERNAME || !process.env.BEAM_CLICKHOUSE_PASSWORD) {
-    throw new Error(`Failed to set ClickHouse credentials in process.env - this should never happen in Node.js`);
-  }
-}
-
-/**
- * Starts the collector and waits for it to be ready before returning.
- * This ensures Portal logs (structured logs via OTLP) only start appearing AFTER collector is ready.
- * Returns the OTLP endpoint when ready, or null if it times out or fails.
- */
-export async function startCollectorAndWaitForReady(
-  env: EnvironmentConfig,
-  _timeoutMs?: number // Not used - kept for API compatibility
-): Promise<string | null> {
-  // Match C# logic: (this.InDocker() || UseLocalOtel) && !BEAM_DISABLE_STANDARD_OTEL
-  const isInDocker = process.env.IS_LOCAL !== '1' && process.env.IS_LOCAL !== 'true';
-  const useLocalOtel = !!process.env.BEAM_LOCAL_OTEL;
-  const standardOtelEnabled = (isInDocker || useLocalOtel) && !process.env.BEAM_DISABLE_STANDARD_OTEL;
-  const hasExplicitEndpoint = !!process.env.BEAM_OTEL_EXPORTER_OTLP_ENDPOINT;
-
-  // If OTLP is not needed, return immediately
-  if (!standardOtelEnabled && !hasExplicitEndpoint) {
-    return null;
-  }
-
-  // Create a minimal console logger for initialization messages (no OTLP yet)
-  const initLogger = pino({
-    name: 'beamable-otlp-init',
-    level: 'info',
-  }, process.stdout);
-
-  initLogger.info('[OTLP] Setting up collector (waiting for readiness before enabling Portal logs)...');
-  const setupStartTime = Date.now();
-
-  // Simple linear async/await - no timeouts, no Promise.race complexity
-  try {
-    initLogger.info('[OTLP] Step 1: Discovering or starting collector...');
-    const endpoint = await discoverOrStartCollector(initLogger, standardOtelEnabled, env);
-    const elapsed = Date.now() - setupStartTime;
-    
-    if (endpoint) {
-      initLogger.info(`[OTLP] Collector ready at ${endpoint}. Portal logs now enabled. (took ${elapsed}ms)`);
-      return endpoint;
-    } else {
-      initLogger.warn(`[OTLP] Collector setup failed, continuing without Portal logs. (took ${elapsed}ms)`);
-      return null;
-    }
-  } catch (error) {
-    const elapsed = Date.now() - setupStartTime;
-    const errorMsg = error instanceof Error ? error.message : String(error);
-    initLogger.error(`[OTLP] Collector setup failed after ${elapsed}ms: ${errorMsg}`);
-    return null;
-  }
-}
-
-/**
- * Starts the collector asynchronously in the background (non-blocking).
- * This allows the service to start immediately while collector downloads/starts.
- * Returns immediately - collector setup happens in background.
- * @deprecated Use startCollectorAndWaitForReady() to ensure Portal logs only appear after collector is ready
- */
-export function startCollectorAsync(env: EnvironmentConfig): void {
-  // Match C# logic: (this.InDocker() || UseLocalOtel) && !BEAM_DISABLE_STANDARD_OTEL
-  const isInDocker = process.env.IS_LOCAL !== '1' && process.env.IS_LOCAL !== 'true';
-  const useLocalOtel = !!process.env.BEAM_LOCAL_OTEL;
-  const standardOtelEnabled = (isInDocker || useLocalOtel) && !process.env.BEAM_DISABLE_STANDARD_OTEL;
-  const hasExplicitEndpoint = !!process.env.BEAM_OTEL_EXPORTER_OTLP_ENDPOINT;
-
-  // If OTLP is not needed, return immediately
-  if (!standardOtelEnabled && !hasExplicitEndpoint) {
-    return;
-  }
-
-  // Create a minimal console logger for initialization messages (no OTLP yet)
-  const initLogger = pino({
-    name: 'beamable-otlp-init',
-    level: 'info',
-  }, process.stdout);
-
-  initLogger.info('[OTLP] Starting collector setup in background (non-blocking)...');
-
-  // Start collector setup asynchronously - don't wait for it
-  // The service can start immediately, collector will connect when ready
-  discoverOrStartCollector(initLogger, standardOtelEnabled, env)
-    .then((result) => {
-      if (result) {
-        initLogger.info(`[OTLP] Collector setup complete in background, endpoint: ${result}`);
-        // Update the global logger provider if it exists to enable OTLP
-        // The logger will automatically start using OTLP once the provider is set
-      } else {
-        initLogger.warn('[OTLP] Collector setup returned null, OTLP logging will be disabled');
-      }
-    })
-    .catch((error) => {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      initLogger.error(`[OTLP] Failed to setup collector in background: ${errorMsg}`);
-    });
-  
-  // Return immediately - service can start serving requests
-}
-
-/**
- * Sets up the collector BEFORE logging is initialized (DEPRECATED - blocking approach).
- * This function is kept for backwards compatibility but is no longer recommended.
- * Use startCollectorAsync() for non-blocking startup instead.
- * @deprecated Use startCollectorAsync() for non-blocking startup
- */
-export function setupCollectorBeforeLogging(
-  env: EnvironmentConfig,
-  timeoutMs: number = 60000
-): string | null {
-  // Match C# logic: (this.InDocker() || UseLocalOtel) && !BEAM_DISABLE_STANDARD_OTEL
-  const isInDocker = process.env.IS_LOCAL !== '1' && process.env.IS_LOCAL !== 'true';
-  const useLocalOtel = !!process.env.BEAM_LOCAL_OTEL;
-  const standardOtelEnabled = (isInDocker || useLocalOtel) && !process.env.BEAM_DISABLE_STANDARD_OTEL;
-  const hasExplicitEndpoint = !!process.env.BEAM_OTEL_EXPORTER_OTLP_ENDPOINT;
-
-  // If OTLP is not needed, return immediately
-  if (!standardOtelEnabled && !hasExplicitEndpoint) {
-    return null;
-  }
-
-  // Create a minimal console logger for initialization messages (no OTLP yet)
-  const initLogger = pino({
-    name: 'beamable-otlp-init',
-    level: 'info',
-  }, process.stdout);
-
-  initLogger.info('[OTLP] Setting up collector before logging initialization...');
-
-  // Use deasync to wait synchronously for collector setup
-  let endpoint: string | null = null;
-  let completed = false;
-  let setupError: string | null = null;
-
-  // Start collector setup promise
-  discoverOrStartCollector(initLogger, standardOtelEnabled, env)
-    .then((result) => {
-      endpoint = result;
-      completed = true;
-      if (result) {
-        initLogger.info(`[OTLP] Collector setup complete, endpoint: ${result}`);
-      } else {
-        initLogger.warn('[OTLP] Collector setup returned null, OTLP logging will be disabled');
-      }
-      return result;
-    })
-    .catch((error) => {
-      setupError = error instanceof Error ? error.message : String(error);
-      completed = true;
-      initLogger.error(`[OTLP] Failed to setup collector: ${setupError}`);
-      endpoint = null;
-    });
-
-  // Wait synchronously for collector setup to complete
-  const startTime = Date.now();
-  const timeoutId = setTimeout(() => {
-    if (!completed) {
-      initLogger.warn(`[OTLP] Collector setup timeout after ${timeoutMs}ms, continuing without OTLP`);
-      completed = true;
-    }
-  }, timeoutMs);
-
-  try {
-    // Use deasync to wait for completion (allows event loop to process async operations)
-    deasync.loopWhile(() => {
-      const elapsed = Date.now() - startTime;
-      if (elapsed >= timeoutMs) {
-        return false; // Stop waiting
-      }
-      return !completed; // Continue waiting if not completed
-    });
-  } catch (error) {
-    initLogger.error(`[OTLP] Error during collector setup wait: ${error instanceof Error ? error.message : String(error)}`);
-  }
-
-  clearTimeout(timeoutId);
-
-  if (completed && endpoint) {
-    initLogger.info('[OTLP] Collector is ready, proceeding with logger creation');
-    return endpoint;
-  } else if (setupError) {
-    initLogger.error(`[OTLP] Collector setup failed: ${setupError}, continuing without OTLP`);
-    return null;
-  } else {
-    initLogger.warn('[OTLP] Collector setup did not complete in time, continuing without OTLP');
-    return null;
-  }
-}
-
-/**
- * Starts the OpenTelemetry collector process
- */
-export async function startCollector(
-  logger: Logger,
-  otlpEndpoint?: string,
-  env?: EnvironmentConfig
-): Promise<{ process: ChildProcess; endpoint: string }> {
-  logger.info('[Collector] === startCollector() ENTERED ===');
-  // Clear any previous errors
-  globalCollectorStartError = null;
-  globalCollectorInitError = null;
-  
-  // CRITICAL: Fetch credentials FIRST, before resolving collector binary/config
-  // This ensures credentials are in process.env even if collector download fails
-  // The credentials will persist in process.env for the lifetime of the process.
-  // Per Gabriel: "these OTEL related ones you need to do it yourself at the beginning of the microservice startup"
-  let clickhouseEndpoint = process.env.BEAM_CLICKHOUSE_ENDPOINT;
-  let clickhouseUsername = process.env.BEAM_CLICKHOUSE_USERNAME;
-  let clickhousePassword = process.env.BEAM_CLICKHOUSE_PASSWORD;
-  
-  if ((!clickhouseEndpoint || !clickhouseUsername || !clickhousePassword) && env) {
-    try {
-      logger.info('[Collector] Fetching ClickHouse credentials from Beamable API...');
-      const credStartTime = Date.now();
-      const credentials = await fetchClickHouseCredentials(env);
-      const credElapsed = Date.now() - credStartTime;
-      logger.info(`[Collector] ClickHouse credentials fetch completed in ${credElapsed}ms`);
-      clickhouseEndpoint = credentials.endpoint;
-      clickhouseUsername = credentials.username;
-      clickhousePassword = credentials.password;
-      
-      // CRITICAL: Set them in process.env IMMEDIATELY after fetching (matching C# CollectorManager.AddAuthEnvironmentVars)
-      // In Node.js, process.env is a writable object - setting properties here persists for the lifetime of the process
-      // This ensures they're available to both the Node.js process and inherited by the collector child process
-      addAuthEnvironmentVars(clickhouseEndpoint, clickhouseUsername, clickhousePassword);
-      
-      // Verify they were set (defensive check - should never fail in Node.js)
-      const verifyEndpoint = process.env.BEAM_CLICKHOUSE_ENDPOINT;
-      const verifyUsername = process.env.BEAM_CLICKHOUSE_USERNAME;
-      const verifyPassword = process.env.BEAM_CLICKHOUSE_PASSWORD;
-      
-      if (!verifyEndpoint || !verifyUsername || !verifyPassword) {
-        logger.error(`[Collector] CRITICAL: Credentials were set but are missing from process.env! This should never happen.`);
-        throw new Error('Failed to persist ClickHouse credentials in process.env');
-      }
-      
-      logger.info('[Collector] ClickHouse credentials fetched from API and verified in process.env');
-    } catch (error) {
-      const errorMsg = `[Collector] Failed to fetch ClickHouse credentials from API: ${error instanceof Error ? error.message : String(error)}`;
-      logger.error(errorMsg);
-      throw new Error(errorMsg);
-    }
-  }
-  
-  // Validate required environment variables (matching C# behavior)
-  // These must be set before starting the collector, otherwise it will fail
-  if (!clickhouseEndpoint || !clickhouseUsername || !clickhousePassword) {
-    const errorMsg = `[Collector] Required ClickHouse credentials are missing. Set BEAM_CLICKHOUSE_ENDPOINT, BEAM_CLICKHOUSE_USERNAME, and BEAM_CLICKHOUSE_PASSWORD, or ensure the API endpoint is accessible.`;
-    logger.error(errorMsg);
-    throw new Error(errorMsg);
-  }
-  
-  // Now resolve collector binary and config (after credentials are fetched and set)
-  logger.info('[Collector] Step 2: Resolving collector binary and config...');
-  const resolveStartTime = Date.now();
-  const collectorInfo = await resolveCollector(true, logger);
-  const resolveElapsed = Date.now() - resolveStartTime;
-  logger.info(`[Collector] Collector binary/config resolution completed in ${resolveElapsed}ms`);
-  
-  if (!collectorInfo.binaryPath) {
-    logger.error('[Collector] Binary not found and download failed');
-    throw new Error('Collector binary not found and download failed');
-  }
-  
-  if (!collectorInfo.configPath) {
-    logger.error('[Collector] Config not found and download failed');
-    throw new Error('Collector config not found and download failed');
-  }
-  
-  logger.info(`[Collector] Using binary: ${collectorInfo.binaryPath}`);
-  logger.info(`[Collector] Using config: ${collectorInfo.configPath}`);
-  
-  // Verify binary exists
-  if (!collectorInfo.binaryPath || !existsSync(collectorInfo.binaryPath)) {
-    throw new Error(`Collector binary not found at ${collectorInfo.binaryPath}`);
-  }
-  
-  // Check if binary is executable (Unix only - Windows doesn't have execute permission)
-  if (process.platform !== 'win32') {
-    try {
-      const fsPromises = await import('fs/promises');
-      const stats = await fsPromises.stat(collectorInfo.binaryPath);
-      const mode = Number(stats.mode);
-      const isExecutable = !!(mode & parseInt('111', 8)); // Check execute bit
-      if (!isExecutable) {
-        logger.warn(`[Collector] Binary may not be executable. Mode: ${mode.toString(8)}`);
-        // Try to make it executable again
-        try {
-          chmodSync(collectorInfo.binaryPath, 0o755);
-          logger.info(`[Collector] Made binary executable`);
-        } catch (chmodError) {
-          logger.error(`[Collector] Failed to make binary executable: ${chmodError instanceof Error ? chmodError.message : String(chmodError)}`);
-        }
-      }
-    } catch (statError) {
-      logger.warn(`[Collector] Could not check binary permissions: ${statError instanceof Error ? statError.message : String(statError)}`);
-    }
-  }
-
-  // Set default collector configuration environment variables in process.env
-  // This ensures they're available to both the Node.js process and the collector child process
-  // Matches C# CollectorManager.AddCollectorConfigurationToEnvironment()
-  addCollectorConfigurationToEnvironment();
-  
-  // CRITICAL: Set BEAM_COLLECTOR_DISCOVERY_PORT if not already set (matching C# AddDefaultCollectorHostAndPortFallback)
-  // This MUST be set before starting the collector
-  if (!process.env.BEAM_COLLECTOR_DISCOVERY_PORT) {
-    process.env.BEAM_COLLECTOR_DISCOVERY_PORT = String(DISCOVERY_PORT);
-    logger.info(`[Collector] Set BEAM_COLLECTOR_DISCOVERY_PORT=${DISCOVERY_PORT} (default)`);
-  }
-  
-  // Determine OTLP endpoint
-  // Use a free port if not specified (like C# does with PortUtil.FreeEndpoint())
-  let localEndpoint = otlpEndpoint;
-  if (!localEndpoint) {
-    // For now, use default OTLP HTTP port
-    // In production, this would be discovered or set by Beamable
-    localEndpoint = '0.0.0.0:4318';
-  }
-  localEndpoint = localEndpoint.replace(/^http:\/\//, '').replace(/^https:\/\//, '');
-  
-  // Find a free port for Prometheus (matching C# PortUtil.FreeTcpPort())
-  // We'll use a simple approach: bind to port 0 and let the OS assign a port
-  // For now, use a default port (9090 is common for Prometheus) or find a free one
-  // C# uses PortUtil.FreeTcpPort() which finds an available TCP port
-  // We'll use a simple helper to find a free port
-  const prometheusPort = await findFreePort();
-  
-  // Set environment variables for collector
-  // Note: BEAM_CLICKHOUSE_ENDPOINT is for collector → ClickHouse communication
-  // This is different from the OTLP endpoint (microservice → collector)
-  // The collector process will inherit all environment variables from process.env automatically
-  // We only need to set the OTLP endpoint, discovery port, and Prometheus port explicitly here
-  const collectorEnv: NodeJS.ProcessEnv = {
-    ...process.env, // Inherit all process.env (including credentials and config we just set)
-    BEAM_OTLP_HTTP_ENDPOINT: localEndpoint,
-    BEAM_COLLECTOR_DISCOVERY_PORT: String(DISCOVERY_PORT),
-    BEAM_COLLECTOR_PROMETHEUS_PORT: String(prometheusPort),
-  };
-  
-  // Start collector process
-  const collectorProcess = spawn(collectorInfo.binaryPath, ['--config', collectorInfo.configPath], {
-    env: collectorEnv,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    detached: false,
-  });
-  
-  // Store globally to prevent GC and track status
-  globalCollectorProcess = collectorProcess;
-  globalCollectorStartError = null;
-  globalCollectorExitCode = null;
-  globalCollectorStderr = [];
-  
-  // Set up handlers BEFORE we check if process started, so we capture all output
-  collectorProcess.stdout?.on('data', (data) => {
-    const outputLine = data.toString().trim();
-    // Log stdout at info level to see collector output
-    logger.info(`[Collector OUT] ${outputLine}`);
-  });
-  
-  collectorProcess.stderr?.on('data', (data) => {
-    const errorLine = data.toString().trim();
-    globalCollectorStderr.push(errorLine);
-    // Keep only last 50 lines to prevent memory issues
-    if (globalCollectorStderr.length > 50) {
-      globalCollectorStderr.shift();
-    }
-    // Log stderr at info level so we can see why collector crashes
-    logger.info(`[Collector ERR] ${errorLine}`);
-  });
-  
-  collectorProcess.on('error', (err) => {
-    globalCollectorStartError = err.message;
-    logger.error(`[Collector] Failed to start: ${err.message}`);
-  });
-  
-  collectorProcess.on('exit', (code, signal) => {
-    globalCollectorExitCode = code;
-    logger.warn(`[Collector] Process exited with code ${code}${signal ? `, signal ${signal}` : ''}`);
-    
-    // If process exited with an error code, log accumulated stderr
-    if (code !== 0 && globalCollectorStderr.length > 0) {
-      logger.error(`[Collector] Exit error - Last ${Math.min(10, globalCollectorStderr.length)} stderr lines:`);
-      globalCollectorStderr.slice(-10).forEach((line) => {
-        logger.error(`[Collector ERR] ${line}`);
-      });
-    }
-    
-    // Don't clear reference immediately - keep it for status checks
-    // globalCollectorProcess = null; // Keep reference for getCollectorProcessStatus()
-  });
-  
-  logger.info(`[Collector] Started with PID ${collectorProcess.pid}, endpoint: ${localEndpoint}`);
-  
-  // Give the process a moment to start and potentially write to stderr
-  // This helps capture immediate startup errors
-  // Wait a bit longer to ensure we catch immediate crashes
-  await new Promise(resolve => setTimeout(resolve, 500));
-  
-  // Check if process already exited (immediate crash)
-  if (globalCollectorExitCode !== null && globalCollectorExitCode !== 0) {
-    const stderrMsg = globalCollectorStderr.length > 0 
-      ? ` Stderr: ${globalCollectorStderr.join('; ')}` 
-      : ' No stderr output captured.';
-    throw new Error(`Collector process exited immediately after startup with code ${globalCollectorExitCode}.${stderrMsg}`);
-  }
-  
-  return {
-    process: collectorProcess,
-    endpoint: `http://${localEndpoint}`,
-  };
-}
-
-/**
- * Gets detailed collector status including process info and errors
- */
-export function getCollectorProcessStatus(): {
-  hasProcess: boolean;
-  pid: number | null;
-  exitCode: number | null;
-  startError: string | null;
-  initError: string | null;
-  stderr: string[];
-  isPreInstalled?: boolean;
-  binaryPath?: string | null;
-  configPath?: string | null;
-} {
-  // Check if collector is actually running successfully - if so, clear stale initError
-  const processAlive = globalCollectorProcess !== null && 
-                       globalCollectorProcess.exitCode === null && 
-                       globalCollectorProcess.killed === false;
-  
-  const stderrText = globalCollectorStderr.join('\n');
-  const isReady = stderrText.includes('Everything is ready') || 
-                 stderrText.includes('Begin running and processing data');
-  
-  // If collector is running and ready, clear stale initError (might be from failed download attempt)
-  // The error could be from an initial download attempt that failed, but collector started successfully using pre-installed binary
-  const actualInitError = (processAlive && isReady) ? null : globalCollectorInitError;
-  
-  // Check if collector binary is pre-installed
-  const basePath = getCollectorStoragePath();
-  const binaryName = getCollectorBinaryName();
-  const configName = 'clickhouse-config.yaml';
-  const binaryPath = join(basePath, binaryName);
-  const configPath = join(basePath, configName);
-  const isPreInstalled = existsSync(binaryPath) && existsSync(configPath);
-  
-  return {
-    hasProcess: globalCollectorProcess !== null,
-    pid: globalCollectorProcess?.pid ?? null,
-    exitCode: globalCollectorExitCode,
-    startError: globalCollectorStartError,
-    initError: actualInitError, // Clear if collector is running and ready
-    stderr: [...globalCollectorStderr], // Return a copy
-    isPreInstalled,
-    binaryPath: isPreInstalled ? binaryPath : null,
-    configPath: isPreInstalled ? configPath : null,
-  };
-}
-
-/**
- * Discovers or starts the collector and returns the OTLP endpoint
- */
-export async function discoverOrStartCollector(
-  logger: Logger,
-  standardOtelEnabled: boolean,
-  env?: EnvironmentConfig
-): Promise<string | null> {
-  if (!standardOtelEnabled) {
-    return null;
-  }
-  
-  // CRITICAL: Check if collector startup is already in progress
-  // This prevents duplicate collector starts if this function is called multiple times
-  // (e.g., if setupCollectorBeforeLogging times out but the promise is still running)
-  if (globalCollectorStartupPromise) {
-    logger.info('[Collector] Collector startup already in progress, waiting for existing startup to complete...');
-    try {
-      const result = await globalCollectorStartupPromise;
-      // Clear the promise after it completes (success or failure)
-      globalCollectorStartupPromise = null;
-      return result;
-    } catch (error) {
-      logger.error(`[Collector] Existing startup promise failed: ${error instanceof Error ? error.message : String(error)}`);
-      // Clear the promise so we can retry
-      globalCollectorStartupPromise = null;
-      // Fall through to start a new one
-    }
-  }
-  
-  // CRITICAL: Check if we already have a collector process starting/running
-  // This prevents duplicate collector starts if this function is called multiple times
-  let existingEndpoint: string | undefined;
-  if (globalCollectorProcess) {
-    // Check if process is still alive
-    const processAlive = globalCollectorProcess.exitCode === null && 
-                         globalCollectorProcess.killed === false;
-    
-    if (processAlive) {
-      logger.info(`[Collector] Collector process already exists (PID ${globalCollectorProcess.pid}), waiting for it to be ready...`);
-      // Use the configured endpoint from environment (we started it earlier)
-      existingEndpoint = process.env.BEAM_OTLP_HTTP_ENDPOINT ? 
-        `http://${process.env.BEAM_OTLP_HTTP_ENDPOINT}` : 
-        'http://0.0.0.0:4318';
-      // Fall through to the wait logic below (don't start a new collector)
-    } else {
-      // Process is dead, clear it and start fresh
-      logger.warn(`[Collector] Previous collector process (PID ${globalCollectorProcess.pid}) is dead, starting new one...`);
-      globalCollectorProcess = null;
-      globalCollectorExitCode = null;
-      globalCollectorStderr = [];
-    }
-  }
-  
-  // First, quick check if collector is already running (via UDP discovery)
-  // Match C#: 10 attempts × 100ms = 1 second max (much faster than before)
-  // Skip UDP discovery if we already have a process reference (faster)
-  if (!globalCollectorProcess) {
-    logger.info('[Collector] Quick check for existing collector via UDP discovery (timeout: 1s, matching C#)...');
-    const udpStartTime = Date.now();
-    logger.info('[Collector] Calling isCollectorRunning()...');
-    const status = await isCollectorRunning();
-    const udpElapsed = Date.now() - udpStartTime;
-    logger.info(`[Collector] isCollectorRunning() returned after ${udpElapsed}ms: isRunning=${status.isRunning}, isReady=${status.isReady}, endpoint=${status.otlpEndpoint || 'none'}`);
-    if (status.isRunning && status.isReady && status.otlpEndpoint) {
-      logger.info(`[Collector] Found running collector at ${status.otlpEndpoint}, will reuse it`);
-      return `http://${status.otlpEndpoint}`;
-    }
-    logger.info('[Collector] No existing collector found, will start new one...');
-  } else {
-    logger.info('[Collector] Collector process already exists, skipping UDP discovery...');
-  }
-  
-  // Collector not running - start it (or wait for existing one to be ready)
-  // Wrap the entire startup logic in a promise that we track globally
-  // This prevents duplicate starts if this function is called multiple times
-  logger.info('[Collector] Creating startup promise...');
-  const startupPromise = (async (): Promise<string | null> => {
-    logger.info('[Collector] Startup promise executing...');
-    try {
-      // Clear any previous init error
-      globalCollectorInitError = null;
-      logger.info(`[Collector] Checking existingEndpoint: ${existingEndpoint || 'none'}`);
-      
-      let endpoint: string;
-      if (existingEndpoint) {
-        // Collector already starting, just wait for it to be ready
-        endpoint = existingEndpoint;
-        logger.info(`[Collector] Waiting for existing collector to become ready at ${endpoint}...`);
-    } else {
-      // Start a new collector
-      logger.info('[Collector] Starting new OpenTelemetry collector...');
-      const startCollectorTime = Date.now();
-      const startResult = await startCollector(logger, undefined, env);
-      const startCollectorElapsed = Date.now() - startCollectorTime;
-      logger.info(`[Collector] Collector process started in ${startCollectorElapsed}ms, endpoint: ${startResult.endpoint}`);
-      endpoint = startResult.endpoint;
-      
-      // Check if collector process exited immediately (crashed)
-      logger.info('[Collector] Checking if collector process is still running...');
-      await new Promise(resolve => setTimeout(resolve, 200));
-      
-      if (globalCollectorExitCode !== null && globalCollectorExitCode !== 0) {
-        const errorMsg = `Collector process exited immediately with code ${globalCollectorExitCode}. ${globalCollectorStderr.length > 0 ? `Stderr: ${globalCollectorStderr.join('; ')}` : 'No stderr output.'}`;
-        globalCollectorInitError = errorMsg;
-        logger.error(`[Collector] ${errorMsg}`);
-        return null;
-      }
-      logger.info('[Collector] Collector process is still running, proceeding to readiness check...');
-    }
-    
-    // CRITICAL: Wait for collector to be fully ready before returning
-    // We'll wait up to 60 seconds, checking every 500ms
-    // This ensures the collector is actually ready to receive logs before we continue
-    const maxWaitTime = 60000; // 60 seconds
-    const checkInterval = 500; // Check every 500ms
-    const maxChecks = Math.floor(maxWaitTime / checkInterval);
-    
-    logger.info(`[Collector] Waiting for collector to become ready (checking every ${checkInterval}ms, max ${maxWaitTime / 1000}s)...`);
-    const readinessStartTime = Date.now();
-    
-    for (let i = 0; i < maxChecks; i++) {
-      await new Promise(resolve => setTimeout(resolve, checkInterval));
-      const elapsed = Date.now() - readinessStartTime;
-      
-      // Check if process exited during wait
-      if (globalCollectorExitCode !== null && globalCollectorExitCode !== 0) {
-        const errorMsg = `Collector process exited during startup with code ${globalCollectorExitCode}. ${globalCollectorStderr.length > 0 ? `Stderr: ${globalCollectorStderr.join('; ')}` : 'No stderr output.'}`;
-        globalCollectorInitError = errorMsg;
-        logger.error(`[Collector] ${errorMsg} (after ${elapsed}ms)`);
-        return null;
-      }
-      
-      logger.info(`[Collector] Checking collector readiness... (${(elapsed / 1000).toFixed(1)}s elapsed, attempt ${i + 1}/${maxChecks})`);
-      const newStatus = await isCollectorRunning();
-      logger.info(`[Collector] Collector status: isRunning=${newStatus.isRunning}, isReady=${newStatus.isReady}, pid=${newStatus.pid}, endpoint=${newStatus.otlpEndpoint || 'none'}`);
-      
-      if (newStatus.isRunning && newStatus.isReady) {
-        logger.info(`[Collector] Collector is ready at ${newStatus.otlpEndpoint || endpoint} (ready after ${elapsed}ms)`);
-        return newStatus.otlpEndpoint ? `http://${newStatus.otlpEndpoint}` : endpoint;
-      }
-      
-      // Log progress every second (every 2 checks)
-      if (i > 0 && i % 2 === 0) {
-        logger.info(`[Collector] Still waiting for collector to become ready... (${(elapsed / 1000).toFixed(1)}s elapsed)`);
-      }
-    }
-    
-    // Check one more time if process exited
-    if (globalCollectorExitCode !== null && globalCollectorExitCode !== 0) {
-      const errorMsg = `Collector process exited with code ${globalCollectorExitCode}. ${globalCollectorStderr.length > 0 ? `Stderr: ${globalCollectorStderr.join('; ')}` : 'No stderr output.'}`;
-      globalCollectorInitError = errorMsg;
-      logger.error(`[Collector] ${errorMsg}`);
-      return null;
-    }
-    
-      // Collector did not become ready within timeout
-      logger.error(`[Collector] Collector did not become ready within ${maxWaitTime / 1000} seconds`);
-      return null;
-    } catch (err) {
-      const errorMsg = err instanceof Error ? err.message : String(err);
-      globalCollectorInitError = errorMsg;
-      logger.error(`[Collector] Failed to start collector: ${errorMsg}`);
-      return null;
-    }
-  })();
-  
-  // Store the promise globally so other calls to this function can wait for it
-  globalCollectorStartupPromise = startupPromise;
-  
-  // Clear the promise when it completes (so we don't keep waiting on old promises)
-  startupPromise.finally(() => {
-    globalCollectorStartupPromise = null;
-  });
-  
-  return await startupPromise;
-}
-