Debug Skill

Fiber debugging and troubleshooting: log configuration, stack corruption, event loop blocking, memory leaks, and diagnostic patterns.

Invoke with: /debug

Log Configuration

{
    log: {
        path: 'stdout',
        format: '%D %H %A[%P] (%T, %S): %M',
        types: 'error,info,trace',
        sources: 'all,!mbedtls',
    },
}

Filtering by Source

log: { sources: 'mqtt,web' }           // Only MQTT and web server logs
log: { sources: 'all,!mbedtls,!tls' }  // Exclude noisy modules

Logging APIs

rError("tag", "Critical failure: %s", reason);    // Always shown
rInfo("tag", "Service started on port %d", port);  // Shown when 'info' in types
rTrace("tag", "Debug detail: %s", data);           // Shown when 'trace' in types

Common Problems and Solutions

1. Fiber Stack Corruption / Crash

Symptoms: Random crashes, corrupted variables, segfaults in unrelated code.

Fix: Increase fiber stack size or move large allocations to heap:

limits: { fiberStack: '128k' }

/* Bad: large stack allocation */
char buf[16384];

/* Good: heap allocation */
char *buf = rAlloc(16384);
rFree(buf);

2. Event Loop Blocking / Hangs

Symptoms: Application stops responding, no log output, web server timeouts.

Fix: Replace blocking calls with fiber-aware equivalents:

Blocking Call	Fiber-Aware Replacement
sleep(n)	rSleep(n * 1000)
usleep(n)	rSleep(n / 1000)

3. Thread Safety Violations

Symptoms: Crashes when using threads, corrupted data.

Rule: Thread callbacks must NOT call any Ioto or R runtime functions.

static void threadMain(void *arg)
{
    /* SAFE: standard C only, no R or Ioto calls */
    int result = computeExpensiveResult();
    rSignal("threadDone", &result);
}

4. Memory Leaks

Track allocations that lack corresponding frees:

Allocation	Required Free
rAlloc() / sclone() / sfmt()	rFree()
jsonAlloc() / jsonParse()	jsonFree()
jsonToString()	rFree()
urlGet() / urlPost()	rFree()
urlGetJson() / urlPostJson()	jsonFree()

5. MQTT Connection Failures

Diagnosis checklist:

• Is services.mqtt enabled in ioto.json5?
• Is the broker reachable?
• Is mqtt.authority pointing to the correct CA certificate?
• Enable MQTT trace: sources: 'mqtt'

6. Web Server Not Responding

Diagnosis checklist:

• Is services.web enabled?
• Check web.json5 endpoint addresses and ports
• Are TLS certificates valid?
• Check for port conflicts: lsof -i :PORT
• Enable web trace: sources: 'web'

Debug Build

make OPTIMIZE=debug            # Debug symbols, no optimization
make OPTIMIZE=debug SHOW=1     # Also show build commands