Unreal Log Viewer 3

A Visual Studio Code extension designed to receive, display, and filter Unreal Engine logs streamed over a TCP network connection. This tool helps developers monitor and debug their Unreal Engine projects in real-time directly within VS Code.

For a quick start and usage examples, see the User Guide.

Project Structure

• src/ — Extension source code (TypeScript)
• out/ — Compiled JavaScript output (after build)
• resources/ — Extension assets (icons, etc.)
• docs/TechnicalDocumentation.md — Full technical documentation (features, architecture, manifest details, troubleshooting)
• docs/UserGuide.md — Full user guide (usage, examples)
• test/generate_unreal_logs.ps1 — Log generator script for testing
• README.md — This file
• package.json, tsconfig.json, etc. — Project configuration

Features

• Real-time Log Streaming: Connects to a TCP server (configurable port) to receive and display logs as they are generated by your Unreal Engine application.
• Advanced Log Filtering:
  • Level Filter: Filter logs by severity (e.g., LOG, WARNING, ERROR, FATAL, VERBOSE, VERYVERBOSE).
    • Supports comma-separated values for multiple levels (e.g., WARNING,ERROR,FATAL).
    • Use ! to exclude levels (e.g., !VERBOSE,!VERYVERBOSE).
    • Use > to include a level and all higher levels (e.g., >WARNING shows WARNING, ERROR, and FATAL).
  • Category Filter: Filter logs by their Unreal Engine category (e.g., LogTemp, LogBlueprint).
    • Supports comma-separated values for multiple categories.
    • Use ! to exclude categories (e.g., !LogNet).
    • Partial matching is supported (e.g., Blueprint will match LogBlueprintUserMessages).
  • Message Filter: Filter logs by their content/message.
    • Supports comma-separated values for multiple keywords.
    • Use ! to exclude messages containing certain keywords.
    • Partial matching is supported.
  • Filters are applied automatically as you type.
  • Filter settings are persisted across VS Code sessions.
• Log Counts: Displays a "shown/total" count of log messages, updating dynamically as filters change or new logs arrive.
• Customizable Appearance:
  • Toggle relative or absolute timestamps.
  • Adjust log table font size.
  • Enable/disable log level color-coding.
  • Show/hide grid lines in the log table.
  • Specify a custom font family for the log table.
• Log Management:
  • Max Log Messages: Set a limit on the number of messages stored. Oldest messages are pruned when the limit is exceeded.
  • Clear Logs:
    • "Clear" button in the webview: Clears only the displayed logs.
    • "Unreal Log Viewer: Clear" command: Clears all stored logs and resets filters.
• GitHub Copilot Integration:
  • Expose a configurable number of recent logs as a plain text virtual document.
  • Use the command "Unreal Log Viewer: Show Logs as Text for Copilot" to open this view, allowing Copilot to access log context. The number of logs is controlled by unrealLogViewer.copilotLogExportLimit.
• Configurable Server Port: Easily change the TCP port the extension listens on. Requires a manual command execution to apply changes (Unreal Log Viewer: Apply Server Port Change).

How to Use

1. Install the Extension: (Details for installation if published - for now, assume local build)
2. Configure Your Unreal Project:
   • You'll need to modify your Unreal Engine project to send logs over TCP to the port the extension is listening on.
   • A common way to do this is by adding a custom log output device in C++.
   • Example (Conceptual - adapt to your project's needs):

     // In a suitable place in your project's C++ code
     #include "HAL/OutputDevices.h"
     #include "Networking.h"
     
     class FSocketLogOutputDevice : public FOutputDevice
     {
         FSocket* Socket;
         // ... socket connection logic ...
     
     public:
         FSocketLogOutputDevice(const TCHAR* Host, int32 Port)
         {
             // ... Initialize and connect socket ...
         }
     
         virtual ~FSocketLogOutputDevice()
         {
             // ... Close socket ...
             if (Socket)
             {
                 Socket->Close();
                 ISocketSubsystem::Get(PLATFORM_SOCKETSUBSYSTEM)->DestroySocket(Socket);
                 Socket = nullptr;
             }
         }
     
         virtual void Serialize(const TCHAR* V, ELogVerbosity::Type Verbosity, const FName& Category) override
         {
             if (Socket && Socket->GetConnectionState() == SCS_Connected)
             {
                 // Construct JSON log entry
                 // Note: Ensure your JSON structure matches what the extension expects:
                 // { "date": "ISO_STRING", "level": "LEVEL_STRING", "category": "CATEGORY_STRING", "message": "MESSAGE_STRING" }
                 // Example:
                 FString Timestamp = FDateTime::UtcNow().ToIso8601();
                 FString LevelStr = LexToString(Verbosity);
                 FString CategoryStr = Category.ToString();
                 FString MessageStr = V;
                 MessageStr.ReplaceCharInline(L'"', L'\"'); // Basic escaping for quotes in message
                 FString JsonPayload = FString::Printf(TEXT("{\"date\":\"%s\",\"level\":\"%s\",\"category\":\"%s\",\"message\":\"%s\"}\n"),
                     *Timestamp, *LevelStr, *CategoryStr, *MessageStr);
     
                 int32 BytesSent = 0;
                 Socket->Send((uint8*)TCHAR_TO_UTF8(*JsonPayload), JsonPayload.Len(), BytesSent);
             }
         }
     };
     
     // To register (e.g., in your game module's StartupModule):
     // GLog->AddOutputDevice(new FSocketLogOutputDevice(TEXT("127.0.0.1"), 9876)); // Use configured port

   • The generate_unreal_logs.ps1 and generate_unreal_logs.sh scripts in this repository provide a way to simulate log messages for testing the extension without a full Unreal Engine setup.
3. Open the Log Viewer:
   • Click the Unreal Log Viewer icon in the Activity Bar.
   • Alternatively, run the "Unreal Log Viewer: Create" command from the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
4. Configure Settings (Optional):
   • Go to File > Preferences > Settings (or Code > Settings > Settings on macOS).
   • Search for "Unreal Log Viewer" to find and adjust available settings like server port, timestamp format, font sizes, colors, etc.
   • If you change the unrealLogViewer.serverPort setting, you must run the command "Unreal Log Viewer: Apply Server Port Change" from the Command Palette for the new port to take effect.
5. Using Filters:
   • Level Filter: Enter desired log levels (e.g., WARNING,ERROR).
   • Category Filter: Enter desired categories (e.g., LogTemp, MyGame).
   • Message Filter: Enter keywords to find in log messages.
   • Use ! for exclusion (e.g., !LogNet, !SpamMessage).
   • Use > for level hierarchy (e.g., >LOG shows LOG, DISPLAY, WARNING, ERROR, FATAL).
   • Filters are applied as you type.
6. Clearing Logs:
   • The "Clear" button in the log viewer panel clears the displayed logs but keeps your filters.
   • The "Unreal Log Viewer: Clear" command (from Command Palette) clears all stored logs and resets all filter inputs.
7. Using with GitHub Copilot:
   • Run the command "Unreal Log Viewer: Show Logs as Text for Copilot" from the Command Palette.
   • This opens a new tab with the recent logs formatted as plain text. Copilot can use this content as context for its suggestions.
   • The number of logs exposed is controlled by the unrealLogViewer.copilotLogExportLimit setting.

Available Commands

• Unreal Log Viewer: Create: Opens the Unreal Log Viewer panel.
• Unreal Log Viewer: Clear: Clears all stored logs and resets filters.
• Unreal Log Viewer: Apply Server Port Change: Applies a new server port if changed in settings.
• Unreal Log Viewer: Show Logs as Text for Copilot: Opens a virtual document with current logs for Copilot context.

Configuration Settings

The following settings can be configured in VS Code's settings UI:

• unrealLogViewer.serverPort (default: 9876): The TCP port for the server.
• unrealLogViewer.useRelativeTimestamps (default: false): Display relative timestamps.
• unrealLogViewer.logTableFontSize (default: var(--vscode-font-size)): Font size for the log table.
• unrealLogViewer.useLogLevelColors (default: true): Enable log level color coding.
• unrealLogViewer.maxLogMessages (default: 10000): Maximum number of log messages to store.
• unrealLogViewer.showGridLines (default: false): Show grid lines in the log table.
• unrealLogViewer.logTableFontFamily (default: var(--vscode-font-family)): Font family for the log table.
• unrealLogViewer.copilotLogExportLimit (default: 1000): Max logs for Copilot text view.

Build and Packaging Notes

• Name: unreal-log-viewer
• Display Name: Unreal Log-Viewer 3
• Version: 1.0.0
• Publisher: coregames
• Repository: https://github.com/hwacookie/unreal-log-extension
• License: GPL-3.0-only
• VS Code Engine: ^1.73.0
• Activation Events: onView:unrealLogViewerView3, onCommand:unrealLogViewer.create, onCommand:unrealLogViewer.clear, onCommand:unrealLogViewer.applyServerPortChange, onCommand:unrealLogViewer.showLogsAsText

Known Issue:

• The dependencies entry in package.json currently contains a self-referential "unreal-log-viewer": "file:" entry. This is known to cause packaging errors (e.g., with vsce package). Remove this entry for production packaging.

Building from Source (for Development)

1. Clone the repository.
2. Open the folder in VS Code.
3. Install dependencies: npm install
4. Start the TypeScript watcher: npm run watch (or press F5 to launch an Extension Development Host window).
5. Make your changes. The watcher will recompile on save.

Documentation

For full technical details, advanced usage, troubleshooting, and manifest information, see docs/TechnicalDocumentation.md.

For a concise how-to and filtering examples, see the User Guide.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

License

GPL-3.0-only — See the LICENSE file for details.