Skip to content

AI_LOGGING_MODE.md

Latest commit

 

History

History
324 lines (227 loc) · 10 KB

AI_LOGGING_MODE.md

File metadata and controls

324 lines (227 loc) · 10 KB

AI Coding Logging Mode

Overview

RootStream includes an AI Coding Logging Mode designed specifically for AI-assisted development workflows. This mode provides structured, machine-readable logging output that helps AI coding assistants (like GitHub Copilot, Claude, ChatGPT) understand the internal operation of RootStream in real-time.

Key Features

  • Zero overhead when disabled - Macros compile out completely
  • Structured output format - [AICODING][timestamp][module] message
  • Multiple activation methods - CLI flag, environment variable, or API
  • Optional file output - Can log to file or stderr
  • Startup banner - Clear warning when verbose mode is active
  • Session summary - Reports total log entries on shutdown

Activation Methods

Method 1: Environment Variable (Recommended)

Set the AI_COPILOT_MODE environment variable to enable logging:

AI_COPILOT_MODE=1 ./rootstream --service

This is the recommended method for AI-assisted debugging as it persists across all invocations.

Method 2: CLI Flag

Use the --ai-coding-logs flag when starting RootStream:

# Log to stderr (default)
./rootstream --ai-coding-logs

# Log to file
./rootstream --ai-coding-logs=/var/log/rootstream-ai.log

Method 3: Programmatic API

For integration testing or custom workflows:

#include "ai_logging.h"

rootstream_ctx_t ctx;
ai_logging_init(&ctx);
ai_logging_set_enabled(&ctx, true);
ai_logging_set_output(&ctx, "/tmp/debug.log");

// ... your code ...

ai_logging_shutdown(&ctx);

Output Format

All AI coding logs follow this structured format:

[AICODING][timestamp][module] message

Example Output

[AICODING][2026-02-13 03:48:15][core] init: AI logging module initialized (mode=stderr)
[AICODING][2026-02-13 03:48:15][core] startup: RootStream version=1.0.0
[AICODING][2026-02-13 03:48:15][core] startup: port=9876 bitrate=10000 service_mode=1
[AICODING][2026-02-13 03:48:15][capture] init: attempting DRM/KMS backend
[AICODING][2026-02-13 03:48:15][capture] init: DRM device=/dev/dri/card0 fd=5
[AICODING][2026-02-13 03:48:16][encode] init: available backends=[NVENC:0, VAAPI:1, x264:1]
[AICODING][2026-02-13 03:48:16][encode] init: selected backend=VAAPI
[AICODING][2026-02-13 03:48:16][network] init: bound to port 9876
[AICODING][2026-02-13 03:48:16][discovery] init: mDNS service started name=gaming-pc

Module Names

Logging is organized by subsystem:

  • core - Main initialization, configuration, shutdown
  • capture - Video capture backends (DRM, X11, dummy)
  • encode - Video encoder backends (VAAPI, NVENC, x264)
  • network - Network stack, socket operations
  • input - Input injection (uinput, xdotool)
  • audio - Audio capture/playback
  • crypto - Encryption, key exchange
  • discovery - mDNS peer discovery
  • gui - Tray/GUI backends

Use Cases

1. Debugging Backend Selection

When troubleshooting why a specific backend was chosen:

AI_COPILOT_MODE=1 ./rootstream --service 2>&1 | grep -E '\[encode\]|\[capture\]'

You'll see:

[AICODING][...][capture] init: attempting DRM/KMS backend
[AICODING][...][capture] fallback: DRM failed, trying X11
[AICODING][...][encode] init: available backends=[NVENC:0, VAAPI:1, x264:1]
[AICODING][...][encode] init: selected backend=x264 (reason=VAAPI init failed)

2. Tracking Initialization Flow

Understanding the startup sequence:

AI_COPILOT_MODE=1 ./rootstream --service 2>&1 | head -30

Shows complete initialization order with timing.

3. Network Connection Issues

Debugging peer connection failures:

AI_COPILOT_MODE=1 ./rootstream connect kXx7Y...@peer 2>&1 | grep '\[network\]'

4. AI-Assisted Code Navigation

When working with an AI coding assistant:

  1. Enable logging: export AI_COPILOT_MODE=1
  2. Run RootStream: ./rootstream --service
  3. Share logs with AI: Copy relevant log sections to your AI chat
  4. AI can now understand: Code paths taken, backends selected, error conditions

Startup Banner

When AI logging is enabled, you'll see:

╔═══════════════════════════════════════════════════════════════════╗
║          AI CODING LOGGING MODE ENABLED                           ║
╠═══════════════════════════════════════════════════════════════════╣
║  Verbose structured logging active for AI-assisted development    ║
║  Output format: [AICODING][module][tag] message                   ║
║                                                                   ║
║  To disable: AI_COPILOT_MODE=0 or remove --ai-coding-logs flag   ║
╚═══════════════════════════════════════════════════════════════════╝

This ensures you're aware that verbose logging is active.

Shutdown Summary

When the program exits, you'll see:

╔═══════════════════════════════════════════════════════════════════╗
║          AI CODING LOGGING SESSION SUMMARY                        ║
╠═══════════════════════════════════════════════════════════════════╣
║  Total log entries: 147                                           ║
║  Output destination: stderr                                       ║
╚═══════════════════════════════════════════════════════════════════╝

Performance Impact

When Disabled (Default)

Zero overhead - The ai_log() macro is compiled out entirely:

#define AI_LOG_CAPTURE(fmt, ...) ai_log("capture", fmt, ##__VA_ARGS__)

When disabled, this becomes a no-op at compile time.

When Enabled

Minimal overhead - Each log call is a single fprintf():

  • CPU: < 0.01% overhead per log call
  • Latency: < 1μs per message
  • Memory: ~1KB static state

Even with hundreds of log calls during startup, the performance impact is negligible.

Sample Troubleshooting Workflows

Problem: "Why is my encoder using x264 instead of VAAPI?"

Workflow:

AI_COPILOT_MODE=1 ./rootstream host 2>&1 | grep -A5 '\[encode\].*init'

Expected output:

[AICODING][...][encode] init: available backends=[NVENC:0, VAAPI:1, x264:1]
[AICODING][...][encode] init: attempting VAAPI
[AICODING][...][encode] init: VAAPI device=/dev/dri/renderD128
[AICODING][...][encode] fallback: VAAPI init failed (error=-1)
[AICODING][...][encode] init: attempting x264
[AICODING][...][encode] init: selected backend=x264

Now you know VAAPI initialization failed, and can investigate why.

Problem: "Connection refused when connecting to peer"

Workflow:

AI_COPILOT_MODE=1 ./rootstream connect kXx7Y...@peer 2>&1 | grep '\[network\]'

Expected output:

[AICODING][...][network] init: attempting connection to 192.168.1.100:9876
[AICODING][...][network] error: connect() failed (errno=111 Connection refused)
[AICODING][...][network] retry: attempt 2/5 in 2 seconds

Problem: "Input not working on remote machine"

Workflow:

AI_COPILOT_MODE=1 ./rootstream host 2>&1 | grep '\[input\]'

Expected output:

[AICODING][...][input] init: attempting uinput backend
[AICODING][...][input] error: failed to open /dev/uinput (errno=13 Permission denied)
[AICODING][...][input] fallback: using xdotool backend
[AICODING][...][input] init: selected backend=xdotool

Now you know to add your user to the input group or use sudo.

Integration with AI Coding Assistants

GitHub Copilot Workflow

  1. Start RootStream with logging:

    AI_COPILOT_MODE=1 ./rootstream --service 2> /tmp/rootstream.log

  2. When debugging an issue, open /tmp/rootstream.log in your editor

  3. Copilot can now see the execution flow and suggest fixes based on:

    • Which backends were selected
    • Where initialization failed
    • Error codes and errno values

Claude/ChatGPT Workflow

  1. Enable logging and reproduce your issue:

    AI_COPILOT_MODE=1 ./rootstream host 2>&1 | tee /tmp/debug.log

  2. Copy relevant sections to your AI chat:

    I'm debugging RootStream encoder selection. Here are the logs:

[paste logs here]

Why did it choose x264 instead of VAAPI?

  3. The AI can now analyze the actual execution path and provide targeted advice

Disabling Logging

Temporary (Single Session)

AI_COPILOT_MODE=0 ./rootstream --service

Permanent (Unset Environment Variable)

unset AI_COPILOT_MODE
./rootstream --service

Build-Time Disable (Optional)

For production builds, you can compile out all AI logging support:

make CFLAGS="-DDISABLE_AI_LOGGING" all

This removes all AI logging code at compile time.

Best Practices

DO

✅ Use AI logging when working with AI coding assistants ✅ Enable logging to debug backend selection issues ✅ Redirect to file when logging large sessions ✅ Use grep/awk to filter specific modules ✅ Share log snippets with AI for targeted help

DON'T

❌ Enable AI logging in production (performance overhead) ❌ Commit AI log files to version control ❌ Use AI logging to replace proper error handling ❌ Expect AI logging to capture all internal state ❌ Leave AI logging enabled for benchmarking

See Also