Marc Rejohn Castillano 5cb6561924 added ruflo

2026-04-09 19:01:53 +08:00

9.9 KiB

Raw Blame History

Debug Streaming Guide

Version: 1.0.0 Date: 2025-11-01 Status: ✅ Production Ready

🔍 Overview

The Debug Streaming system provides detailed, real-time visibility into all agent operations with multiple verbosity levels, customizable output formats, and performance metrics.

Perfect for: Development, debugging, performance tuning, production monitoring

🚀 Quick Start

Basic Usage

import { createDebugStream, DebugLevel } from 'agentic-flow/federation/debug/debug-stream';

// Create debug stream
const debug = createDebugStream({
  level: DebugLevel.DETAILED,
  format: 'human',
  colorize: true,
});

// Log operations
debug.logDatabase('query', { table: 'sessions' }, 15);
debug.logMemory('store', 'agent-001', 'team-1', { id: 'mem-1' }, 12);

// Print metrics
debug.printMetrics();

Environment Variables

# Set debug level
export DEBUG_LEVEL=VERBOSE

# Set output format
export DEBUG_FORMAT=human  # human | json | compact

# Set output destination
export DEBUG_OUTPUT=console  # console | file | both

# Optional: file path
export DEBUG_OUTPUT_FILE=debug.log

📊 Debug Levels

SILENT (0)

No debug output. Production default.

DEBUG_LEVEL=SILENT

BASIC (1)

Major events only: initialization, shutdown, errors.

DEBUG_LEVEL=BASIC

Output:

[2025-11-01T14:00:00.000Z] BASIC  CONNECTION server_start
[2025-11-01T14:00:01.000Z] BASIC  CONNECTION client_connected

Best for: Production monitoring, error tracking

DETAILED (2)

Includes all database operations with timing.

DEBUG_LEVEL=DETAILED

Output:

[2025-11-01T14:00:00.100Z] DETAIL DATABASE query_memories 8.00ms
  Data: {
    "table": "agent_memories",
    "rows": 5
  }
[2025-11-01T14:00:00.120Z] DETAIL MEMORY store agent=agent-001 tenant=team-1 12.00ms
  Data: {
    "id": "mem-456",
    "content": "Task complete"
  }

Best for: Development, performance tuning, SQL debugging

VERBOSE (3)

All events including real-time operations and tasks.

DEBUG_LEVEL=VERBOSE

Output:

[2025-11-01T14:00:00.000Z] VERBOS REALTIME agent=agent-001 agent_join
  Data: {
    "tenant": "team-alpha",
    "status": "online"
  }
[2025-11-01T14:00:00.050Z] VERBOS TASK agent=agent-001 task_assigned
  Data: {
    "taskId": "task-123",
    "description": "Process user request"
  }

Best for: Multi-agent debugging, coordination troubleshooting

TRACE (4)

Everything including internal state changes.

DEBUG_LEVEL=TRACE

Output:

[2025-11-01T14:00:00.000Z] TRACE  TRACE state_change
  Data: {
    "component": "ConnectionPool",
    "old_state": "idle",
    "new_state": "connecting"
  }

Best for: Deep debugging, troubleshooting edge cases

🎨 Output Formats

Human-Readable (Default)

DEBUG_FORMAT=human

Features:

Color-coded output
Formatted JSON
Timestamps
Duration highlighting
Stack traces (optional)

Example:

[2025-11-01T14:00:00.100Z] DETAIL DATABASE query_memories 8.00ms
  Data: {
    "table": "agent_memories",
    "rows": 5
  }

JSON

DEBUG_FORMAT=json

Features:

Machine-parseable
Structured data
Easy to process
Log aggregation friendly

Example:

{"timestamp":"2025-11-01T14:00:00.100Z","level":2,"category":"database","operation":"query_memories","duration":8,"data":{"table":"agent_memories","rows":5}}

Compact

DEBUG_FORMAT=compact

Features:

Single line per event
Minimal overhead
Production friendly
Easy to grep

Example:

2025-11-01T14:00:00.100Z | DETAIL | database | query_memories | 8ms

🎯 Usage Examples

Example 1: Development Debugging

import { createDebugStream, DebugLevel } from './debug-stream';

const debug = createDebugStream({
  level: DebugLevel.VERBOSE,
  format: 'human',
  colorize: true,
});

// Your code here
await performDatabaseOperations();

// Print metrics at end
debug.printMetrics();

Example 2: Production Monitoring

const debug = createDebugStream({
  level: DebugLevel.BASIC,
  format: 'json',
  output: 'file',
  outputFile: '/var/log/agent-debug.log',
  colorize: false,
});

// Monitor critical operations only
debug.logConnection('service_start', { version: '1.0.0' });

Example 3: Performance Profiling

const debug = createDebugStream({
  level: DebugLevel.DETAILED,
  format: 'human',
  includeTimestamps: true,
});

// Log operations with timing
const start = Date.now();
await database.query('SELECT * FROM ...');
const duration = Date.now() - start;

debug.logDatabase('query', { sql: '...' }, duration);

// Analyze performance
debug.printMetrics();

Example 4: Event Filtering

const debug = createDebugStream({
  level: DebugLevel.VERBOSE,
  filterCategories: ['database', 'memory'], // Only these
  filterAgents: ['agent-001'], // Only this agent
});

// Only matching events will be logged

Example 5: Real-Time Monitoring

const debug = createDebugStream({
  level: DebugLevel.DETAILED,
});

// Subscribe to events
debug.on('event', (event) => {
  if (event.duration && event.duration > 100) {
    console.log(`⚠️  SLOW: ${event.operation} took ${event.duration}ms`);
  }
});

📚 API Reference

DebugStream Class

Methods

log(event) Log a debug event manually.

logConnection(operation, data?, error?) Log connection events.

logDatabase(operation, data?, duration?, error?) Log database operations with timing.

logRealtime(operation, agentId?, data?, duration?) Log realtime events.

logMemory(operation, agentId?, tenantId?, data?, duration?) Log memory operations.

logTask(operation, agentId?, tenantId?, data?, duration?) Log task operations.

logTrace(operation, data?) Log internal state changes.

getMetrics() Get performance metrics summary.

printMetrics() Print formatted metrics to console.

getEvents(filter?) Get buffered events with optional filter.

clearEvents() Clear event buffer.

clearMetrics() Clear performance metrics.

close() Close file stream (if using file output).

Events

'event' Emitted for every debug event.

debug.on('event', (event) => {
  console.log('Event:', event);
});

🔧 Integration

With Supabase Adapter

import { SupabaseFederationAdapterDebug } from './supabase-adapter-debug';

const adapter = new SupabaseFederationAdapterDebug({
  url: process.env.SUPABASE_URL!,
  anonKey: process.env.SUPABASE_ANON_KEY!,
  debug: {
    enabled: true,
    level: DebugLevel.DETAILED,
    format: 'human',
  },
});

await adapter.initialize();
await adapter.storeMemory({...});

// Print performance metrics
adapter.printMetrics();

With Real-Time Federation

import { createRealtimeHub } from './realtime-federation';
import { createDebugStream, DebugLevel } from './debug-stream';

const debug = createDebugStream({
  level: DebugLevel.VERBOSE,
});

const hub = createRealtimeHub('agent-001', 'team-1');

// Integrate debug logging
hub.on('message:received', (msg) => {
  debug.logRealtime('message_received', 'agent-001', msg);
});

📊 Performance Metrics

Automatic Tracking

All operations with duration are automatically tracked:

debug.logDatabase('query', {}, 15);
debug.logDatabase('query', {}, 8);
debug.logDatabase('insert', {}, 12);

// Metrics are aggregated automatically
debug.printMetrics();

Output:

Performance Metrics Summary
============================================================
Operation                               Count     Avg Duration
------------------------------------------------------------
database:query                          2         11.50ms
database:insert                         1         12.00ms

Custom Metrics

const startTime = Date.now();
await yourOperation();
const duration = Date.now() - startTime;

debug.logDatabase('custom_operation', { details }, duration);

🎓 Best Practices

Development

# Maximum visibility
DEBUG_LEVEL=TRACE
DEBUG_FORMAT=human
DEBUG_OUTPUT=console

Staging

# Balanced monitoring
DEBUG_LEVEL=DETAILED
DEBUG_FORMAT=json
DEBUG_OUTPUT=both
DEBUG_OUTPUT_FILE=/var/log/staging-debug.log

Production

# Minimal overhead
DEBUG_LEVEL=BASIC
DEBUG_FORMAT=compact
DEBUG_OUTPUT=file
DEBUG_OUTPUT_FILE=/var/log/production.log

🐛 Troubleshooting

Issue: Too Much Output

Solution: Lower the debug level

# From VERBOSE to DETAILED
DEBUG_LEVEL=DETAILED

Issue: Can't Find Slow Queries

Solution: Use event filtering with custom handler

debug.on('event', (event) => {
  if (event.category === 'database' && event.duration! > 50) {
    console.log('SLOW:', event);
  }
});

Issue: File Output Not Working

Solution: Check file permissions

# Ensure directory exists
mkdir -p /var/log/agent

# Set permissions
chmod 755 /var/log/agent

# Test with tmp
DEBUG_OUTPUT_FILE=/tmp/debug.log

✅ Summary

Debug Streaming provides:

✅ 5 verbosity levels (SILENT to TRACE)
✅ 3 output formats (human, json, compact)
✅ Multiple destinations (console, file, both)
✅ Automatic performance tracking
✅ Event filtering
✅ Real-time streaming
✅ Color-coded output
✅ Stack traces (optional)

Perfect for:

Development debugging
Performance profiling
Production monitoring
Troubleshooting
Learning and education

Version: 1.0.0 Last Updated: 2025-11-01 Status: ✅ Production Ready

🔍 Start debugging with visibility!

9.9 KiB Raw Blame History

Debug Streaming Guide

🔍 Overview

🚀 Quick Start

Basic Usage

Environment Variables

📊 Debug Levels

SILENT (0)

BASIC (1)

DETAILED (2)

VERBOSE (3)

TRACE (4)

🎨 Output Formats

Human-Readable (Default)

JSON

Compact

🎯 Usage Examples

Example 1: Development Debugging

Example 2: Production Monitoring

Example 3: Performance Profiling

Example 4: Event Filtering

Example 5: Real-Time Monitoring

📚 API Reference

DebugStream Class

Methods

Events

🔧 Integration

With Supabase Adapter

With Real-Time Federation

📊 Performance Metrics

Automatic Tracking

Custom Metrics

🎓 Best Practices

Development

Staging

Production

🐛 Troubleshooting

Issue: Too Much Output

Issue: Can't Find Slow Queries

Issue: File Output Not Working

🔗 Related Documentation

✅ Summary

9.9 KiB

Raw Blame History