🐛 LLMAI Debug & Logging System

The LLMAI plugin includes a comprehensive debugging and logging system to help you troubleshoot AI communication, audio processing, and function calling issues.

📋 Contents

🚀 Quick Start
🎮 Console Commands
⚙️ Debug Levels & Options
Logging Macros
Performance Tracking
Utility Functions
Log Categories
Common Troubleshooting
Pro Tips

🚀 Quick Start

For Users (Blueprint/Editor)

The debug system is automatically available - no setup required! Just use the console commands to enable debugging.

For Developers (C++)

Include the logging header in any file where you want to use logging:

#include "LLMAILogging.h"

🎮 Console Commands (Easy Mode)

Open the console in Unreal Editor (` key) and use these commands:

Quick Enable/Disable

llmai.debug.EnableAll      # Turn on all debug logging
llmai.debug.DisableAll     # Turn off all debug logging  
llmai.debug.LogMemory      # Show current memory usage
llmai.debug.LogPerformance # Show performance statistics

Most Useful for Troubleshooting

🔌 Connection Issues

llmai.debug.WebSocketLevel 2 See WebSocket communication details
llmai.debug.OpenAILevel 2 See OpenAI API request/response details

🎤 Audio Problems

llmai.debug.AudioLevel 2 See audio processing details
llmai.debug.VoiceLevel 2 See voice activity detection
llmai.debug.SaveAudioFiles 1 Save audio data for analysis

🔧 Function Calling Issues

llmai.debug.FunctionLevel 2 See AI function call details

⚙️ Debug Levels & Options

Debug Levels (0=Off, 1=Basic, 2=Detailed, 3=Verbose)

Command	Purpose	When to Use
`llmai.debug.WebSocketLevel 2`	WebSocket communication	Connection problems, message issues
`llmai.debug.OpenAILevel 2`	OpenAI API calls	API errors, response problems
`llmai.debug.AudioLevel 2`	Audio processing	Voice input/output issues
`llmai.debug.VoiceLevel 2`	Voice activity detection	Speech detection problems
`llmai.debug.SessionLevel 2`	AI session management	Session state issues
`llmai.debug.FunctionLevel 2`	Function calling	AI function call problems
`llmai.debug.PerformanceLevel 2`	Performance monitoring	Lag, memory issues

Special Debug Options

Command	Purpose	Output Location
`llmai.debug.SaveAudioFiles 1`	Save audio data to files	`ProjectLogDir/LLMAI/`
`llmai.debug.LogAudioMetrics 1`	Show detailed audio stats	Output log
`llmai.debug.LogInterruptions 1`	Track voice interruptions	Output log
`llmai.debug.LogRawWebSocketData 1`	Show raw WebSocket traffic	Output log
`llmai.debug.LogOpenAIResponses 1`	Show full AI responses	Output log
`llmai.debug.LogConnections 1`	Show connection events	Output log

Logging Macros

Level-based Logging

// WebSocket logging (Level 1=Basic, 2=Detailed, 3=Verbose)
LLMAI_LOG_WEBSOCKET(1, TEXT("Basic WebSocket info: %s"), *SomeString);
LLMAI_LOG_WEBSOCKET(2, TEXT("Detailed WebSocket info"));
LLMAI_LOG_WEBSOCKET(3, TEXT("Verbose WebSocket debugging"));

// OpenAI API logging
LLMAI_LOG_OPENAI(1, TEXT("OpenAI request sent: %s"), *RequestType);

// Audio processing logging
LLMAI_LOG_AUDIO(1, TEXT("Audio buffer size: %d"), BufferSize);

// Voice activity logging
LLMAI_LOG_VOICE(1, TEXT("Voice threshold: %.4f"), Threshold);

// Session management logging
LLMAI_LOG_SESSION(1, TEXT("Session state changed: %s"), *NewState);

// Function calling logging
LLMAI_LOG_FUNCTION(1, TEXT("Function called: %s"), *FunctionName);

// Performance logging
LLMAI_LOG_PERFORMANCE(1, TEXT("Operation took %f ms"), TimeTaken);

Simple Category Logging

LLMAI_LOG_CLIENT(TEXT("Client component message"));
LLMAI_LOG_STREAM(TEXT("Audio stream message"));
LLMAI_LOG_SETTINGS(TEXT("Settings updated"));
LLMAI_LOG_TRANSCRIPTION(TEXT("Transcription result: %s"), *Text);

Error and Warning Logging

LLMAI_LOG_ERROR(LogLLMAIWebSocket, TEXT("WebSocket connection failed"));
LLMAI_LOG_WARNING(LogLLMAIAudio, TEXT("Audio buffer overflow"));

Specialized Logging

// Connection events
LLMAI_LOG_CONNECTION(TEXT("Connected to %s"), *URL);

// Raw data (very verbose)
LLMAI_LOG_RAW_DATA(TEXT("SEND"), SomeDataString);

// Audio metrics
LLMAI_LOG_AUDIO_METRICS(TEXT("Level: %.4f, Samples: %d"), Level, Count);

// Voice interruptions
LLMAI_LOG_INTERRUPTION(TEXT("User interrupted AI at %.2f seconds"), Time);

// Memory usage
LLMAI_LOG_MEMORY(TEXT("AudioBuffer"), BufferSizeInBytes);

Performance Tracking

// Simple performance logging
void MyFunction()
{
    LLMAI_PERF_SCOPE(MyFunction);  // Logs function entry
    // ... your code here
}

// Advanced performance timing
void MyAdvancedFunction()
{
    LLMAI_PERF_SCOPE_START(MyAdvancedFunction);  // Start timing
    
    // ... your code here ...
    
    LLMAI_PERF_SCOPE_END(MyAdvancedFunction);    // End timing and log duration
}

// Manual performance logging
LLMAI_PERF_LOG(TEXT("Custom performance metric: %f ms"), Time);

Utility Functions

// Log memory usage
LLMAIDebugUtils::LogMemoryUsage(TEXT("MyComponent"));

// Log audio buffer statistics
LLMAIDebugUtils::LogAudioBufferStats(BufferSize, MaxSize, TEXT("InputBuffer"));

// Log session state changes
LLMAIDebugUtils::LogSessionState(SessionId, TEXT("Connected"), TEXT("Additional info"));

// Log WebSocket messages (with optional truncation)
LLMAIDebugUtils::LogWebSocketMessage(TEXT("SEND"), Message, true);

// Log OpenAI responses
LLMAIDebugUtils::LogOpenAIResponse(TEXT("completion"), ResponseContent);

// Log audio format information
LLMAIDebugUtils::LogAudioFormat(44100, 2, 16);

// Log audio levels with threshold comparison
LLMAIDebugUtils::LogAudioLevel(AudioLevel, Threshold, TEXT("Microphone"));

// Save audio data for debugging
LLMAIDebugUtils::SaveAudioDataForDebug(AudioData, TEXT("debug_audio"), TEXT("Voice"));

// Log function calls and results
LLMAIDebugUtils::LogFunctionCall(TEXT("GetWeather"), TEXT("{\"location\":\"NYC\"}"), TEXT("call_123"));
LLMAIDebugUtils::LogFunctionResult(TEXT("call_123"), TEXT("Sunny, 72°F"), true);

Log Categories

The system provides these main log categories:

LogLLMAI
Core plugin messages

LogLLMAIWebSocket
WebSocket communication details

LogLLMAIAudioStream
Audio streaming component

LogLLMAIFunctions
AI function management

LogLLMAISettings
Plugin settings

LogLLMAIOpenAI
OpenAI API interactions

LogLLMAIAudio
Audio processing

LogLLMAIVoice
Voice activity detection

LogLLMAISession
Session management

LogLLMAITranscription
Speech transcription

LogLLMAIPerformance
Performance monitoring

Common Troubleshooting Scenarios

"AI isn't responding"

llmai.debug.OpenAILevel 2 Check API communication
llmai.debug.SessionLevel 2 Check session state
llmai.debug.LogConnections 1 Check connection status

"Voice input not working"

llmai.debug.AudioLevel 2 Check audio capture
llmai.debug.VoiceLevel 2 Check voice detection
llmai.debug.SaveAudioFiles 1 Save audio for analysis

"Function calls not working"

llmai.debug.FunctionLevel 2 See function call details
llmai.debug.OpenAILevel 2 See AI's function call requests

"Performance issues"

llmai.debug.PerformanceLevel 2 Monitor performance
llmai.debug.LogMemory Check memory usage
stat LLMAI Show performance stats

💡 Pro Tips

Start with level 1 for basic info without spam
Use level 2 for detailed debugging (most useful)
Use level 3 only when you need everything (very verbose)
Enable SaveAudioFiles to analyze audio issues offline
Check saved files in YourProject/Saved/Logs/LLMAI/
Use multiple debug levels together for complex issues

Where to Find Debug Output

Output Log (Window > Developer Tools > Output Log)
Console (` key in editor)
Log Files (YourProject/Saved/Logs/)
Debug Files (YourProject/Saved/Logs/LLMAI/)

📖 Plugin Documentation 📚 API Reference

🚀 Quick Commands