debug-logging

name	debug-logging
description	Volatio debug logging convention with

debug-logging

When to Use

• Debugging any issue
• Need temporary logs that are easy to find and remove
• Distinguishing debug logs from permanent observability

Golden Path: Debug Log Format

console.log(`[ClassName.methodName] description ${data} ${Date.now()} ######`);

Format Rules

• [ClassName.methodName] - Exact location in code
• Include relevant data/variables
• Add timestamp ${Date.now()}
• End with ###### marker for easy search/removal
• Add logs at: function entry, before/after key operations, error paths

Example

export class EconomicEventsPersister {
  async persist(events: Event[]): Promise<void> {
    console.log(`[EconomicEventsPersister.persist] Starting with ${events.length} events ${Date.now()} ######`);
    
    for (const event of events) {
      console.log(`[EconomicEventsPersister.persist] Processing ${event.eventKey} ${Date.now()} ######`);
      
      try {
        await db.insert(economicEvents).values(event);
        console.log(`[EconomicEventsPersister.persist] Inserted ${event.eventKey} ${Date.now()} ######`);
      } catch (error) {
        console.log(`[EconomicEventsPersister.persist] Failed ${event.eventKey}: ${error} ${Date.now()} ######`);
      }
    }
    
    console.log(`[EconomicEventsPersister.persist] Complete ${Date.now()} ######`);
  }
}

Running with Full Output

ALWAYS show ALL logs - never hide output:

# ✅ GOOD: Show everything
bun script.ts 2>&1

# ✅ GOOD: Show output AND save to file
bun script.ts 2>&1 | tee debug.log

# ❌ BAD: Hiding output
bun script.ts > /dev/null 2>&1
bun script.ts --silent

Searching Debug Logs

# Find all debug logs
grep '######' output.log

# Find specific class/method
grep '\[ClassName.methodName\]' output.log

# Find in real-time
bun script.ts 2>&1 | grep --line-buffered '######'

Cleanup After Fix

Remove ALL debug logs when done:

# Find all files with debug markers
grep -r '######' packages/

# Remove all lines with ######
grep -r '######' packages/ --files-with-matches | xargs sed -i '' '/######/d'

CRITICAL: Clean Removal

// ❌ BAD: Leaves empty blocks
try {
  console.log(`[Class.method] debug ${Date.now()} ######`);
  await someOperation();
} catch (error) {
  console.log(`[Class.method] error ${Date.now()} ######`);
}

// ✅ GOOD: Remove empty blocks entirely
await someOperation();

Rules for cleanup:

1. Remove the debug log line
2. Check if containing block (try/catch, if/else) now has no other statements
3. If block is empty, remove the entire block structure
4. Maintain proper indentation

Debug Logs vs Production Logs

Type	Purpose	Format	Persistence
Debug Logs	Temporary debugging	console.log(...) ######	Remove after fix
Production Logs	Permanent observability	logger.info(...)	Keep forever

Production Logging (Pino)

For permanent observability, use @volatio/shared/logger:

import { logger, createJobLogger, metrics } from '@volatio/shared/logger';

// Base logger
logger.info({ port: 3001 }, 'Server started');

// Job-specific logger
const log = createJobLogger(job.id, 'yahoo-discovery');
log.info({ articles: 50 }, 'Discovery complete');

// Metrics
metrics.discoveryComplete({
  source: 'yahoo',
  totalFound: 100,
  durationMs: 3200,
});

Don'ts

• Don't commit ###### logs - they're temporary only
• Don't hide command output during debugging
• Don't use production logger for temporary debugging
• Don't leave empty blocks after removing logs