Debug and logging

Quick Commands

info

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

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

Most Useful for Troubleshooting

Connection Issues

Audio Problems

Function Calling Issues

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:

Common Troubleshooting Scenarios

"AI isn't responding"

"Voice input not working"

"Function calls not working"

"Performance issues"

Pro Tips

1. Start with level 1 for basic info without spam
2. Use level 2 for detailed debugging (most useful)
3. Use level 3 only when you need everything (very verbose)
4. Enable SaveAudioFiles to analyze audio issues offline
5. Check saved files in YourProject/Saved/Logs/LLMAI/
6. 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/ )