Async Troubleshooting

Common Issues

• TimeoutException
  • Cause: Operation exceeded configured timeout (HTTP, stream, task)
  • Fix: Increase timeout, reduce work, or add fallback (race)
• ResourceLimitException
  • Cause: Max concurrent tasks, memory, or FD limit exceeded
  • Fix: Tune async.scheduler.max_concurrent_tasks, async.limits.*; reduce fan-out
• Starvation / No Progress
  • Cause: Blocking code inside async task
  • Fix: Avoid blocking I/O/sleep; use scheduler sleep()/async HTTP/streams
• Stream Read/Write Hangs
  • Cause: Missing timeouts or unreachable peer
  • Fix: Pass Timeout to stream ops; validate endpoints

Debugging Tips

• Enable LoggerMetrics

$logger = app(Psr\Log\LoggerInterface::class);
$metrics = new Glueful\Async\Instrumentation\LoggerMetrics($logger);
$scheduler = new Glueful\Async\FiberScheduler($metrics);

You’ll see logs like async.http.started, async.http.completed, queue depths, and suspends/resumes.

• Measure Queue Depth
  • Watch async.scheduler.queue_depth to spot bottlenecks
• Narrow Scope
  • Reproduce with minimal tasks and deterministic endpoints

Configuration Checklist

• async.scheduler.max_concurrent_tasks — appropriate for workload size
• async.scheduler.max_task_execution_seconds — prevent runaway tasks
• async.http.max_retries, retry_delay_seconds, retry_on_status — resilient calls
• async.streams.buffer_size — reduce small I/O syscalls
• async.limits.max_memory_mb, max_open_file_descriptors — protect resources

Patterns to Recover

• First responder (race): Prefer fastest source, fall back on others
• Bulkhead: Cap concurrency per downstream (e.g., limit tasks per service)
• Backoff: Increase retry_delay_seconds on repeated failures