Beyhan Oğur
18 KiB
18 KiB
Debug Console
**Referenced Files in This Document** - [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs) - [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs) - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs) - [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs) - [PacketFilterInfo.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterInfo.cs) - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs) - [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs) - [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This document explains the Debug Console in ClassicAssist.Avalonia, focusing on how it receives, displays, and manages diagnostic information from various subsystems. It covers:
- Console output system and log viewing capabilities
- Diagnostic information display for packets, chat, and macros
- Configuring logging levels, filtering messages, and exporting debug data
- Real-time streaming and search functionality
- Message formatting options and interpreting outputs
- Performance implications across logging levels
- Best practices for development vs production
- Extending the console with custom sources and formats
Project Structure
The Debug Console is implemented as an Avalonia view with a corresponding ViewModel that binds to shared services and network filters. The key files are:
- View layer (Avalonia): DebugWindow.axaml and DebugWindow.axaml.cs
- View model: DebugViewModel.cs
- Shared services and filters: ChatManager, Packet Filters, Packet Handlers
- Application bootstrap: App.axaml.cs and Engine.cs
graph TB
subgraph "UI Layer"
DW["DebugWindow.axaml"]
DWC["DebugWindow.axaml.cs"]
DVM["DebugViewModel.cs"]
end
subgraph "Shared Services"
CM["ChatManager.cs"]
SMTW["SystemMessageTextWriter.cs"]
end
subgraph "Networking"
IPF["IncomingPacketFilters.cs"]
OPF["OutgoingPacketFilters.cs"]
PF["PacketFilter.cs"]
PFI["PacketFilterInfo.cs"]
IPH["IncomingPacketHandlers.cs"]
OPH["OutgoingPacketHandlers.cs"]
end
subgraph "Bootstrap"
APP["App.axaml.cs"]
ENG["Engine.cs"]
end
DW --> DWC
DWC --> DVM
DVM --> CM
DVM --> IPF
DVM --> OPF
DVM --> PF
DVM --> PFI
DVM --> IPH
DVM --> OPH
APP --> ENG
ENG --> DVM
Diagram sources
- DebugWindow.axaml
- DebugWindow.axaml.cs
- DebugViewModel.cs
- ChatManager.cs
- SystemMessageTextWriter.cs
- IncomingPacketFilters.cs
- OutgoingPacketFilters.cs
- PacketFilter.cs
- PacketFilterInfo.cs
- IncomingPacketHandlers.cs
- OutgoingPacketHandlers.cs
- App.axaml.cs
- Engine.cs
Section sources
Core Components
- Debug Window (View): Provides UI elements for displaying logs, searching, filtering, and exporting.
- Debug View Model: Binds UI to shared services and network filters; exposes commands for filtering, clearing, and exporting.
- Chat Manager: Centralizes chat message handling and can be integrated into the console for unified diagnostics.
- System Message Text Writer: Bridges macro/system messages into the console pipeline.
- Packet Filters and Handlers: Provide real-time packet inspection and routing, enabling detailed network diagnostics.
Key responsibilities:
- Receive and aggregate logs from multiple sources
- Render logs in real time with optional auto-scrolling
- Support filtering by level, source, or keyword
- Allow export of filtered logs to external files
- Maintain performance by throttling high-volume streams
Section sources
Architecture Overview
The Debug Console integrates with shared services and networking layers to provide centralized diagnostics. The flow typically involves:
- Subsystems emitting logs/messages via shared services
- Debug View Model subscribing to events and updating bound collections
- UI rendering entries in real time with filtering and search
- Export functionality writing selected entries to disk
sequenceDiagram
participant Subsystem as "Subsystem"
participant Service as "Shared Service"
participant VM as "DebugViewModel"
participant UI as "DebugWindow"
participant Exporter as "Exporter"
Subsystem->>Service : Emit log/message
Service-->>VM : Event/Notification
VM->>VM : Apply filter/format
VM-->>UI : Update collection
UI->>UI : Render entry (real-time)
UI->>Exporter : Export filtered logs
Exporter-->>UI : Save file path/status
Diagram sources
- DebugViewModel.cs
- DebugWindow.axaml.cs
- ChatManager.cs
- IncomingPacketFilters.cs
- OutgoingPacketFilters.cs
Detailed Component Analysis
Debug Window (View)
- Purpose: Hosts the console UI, including log list, search box, filter controls, and export actions.
- Behavior: Binds to properties exposed by DebugViewModel; supports keyboard shortcuts and context menu operations.
- Integration: Uses Avalonia data binding to reflect changes from the ViewModel efficiently.
classDiagram
class DebugWindow {
+InitializeComponent()
+OnLoaded()
+BindDataContext()
+ExportLogs()
+ClearConsole()
+SearchText
+SelectedLogLevel
+AutoScrollEnabled
}
Diagram sources
Section sources
Debug View Model
- Purpose: Aggregates logs, applies filters, formats messages, and exposes commands for UI interaction.
- Responsibilities:
- Subscribe to shared services (e.g., ChatManager) and packet filters
- Maintain a bounded collection of log entries to prevent memory growth
- Implement filtering by level, source, and text search
- Provide export functionality to write logs to files
- Manage auto-scroll behavior and thread-safe updates
classDiagram
class DebugViewModel {
+ObservableCollection~LogEntry~ Logs
+string SearchText
+LogLevel SelectedLogLevel
+bool AutoScroll
+void AddLog(source, level, message)
+void ClearLogs()
+IEnumerable~LogEntry~ GetFilteredLogs()
+void ExportLogs(path)
+void ToggleAutoScroll()
}
class LogEntry {
+DateTime Timestamp
+string Source
+LogLevel Level
+string Message
}
DebugViewModel --> LogEntry : "creates/manages"
Diagram sources
Section sources
Chat Integration
- Purpose: Route chat messages into the console for unified diagnostics.
- Mechanism: Subscribe to ChatManager events and append formatted entries to the log collection.
sequenceDiagram
participant Client as "Game Client"
participant CM as "ChatManager"
participant VM as "DebugViewModel"
participant UI as "DebugWindow"
Client->>CM : Chat event
CM-->>VM : OnChatMessage(args)
VM->>VM : Format message
VM-->>UI : Append to Logs
UI->>UI : Render new entry
Diagram sources
Section sources
Macro System Messages
- Purpose: Capture macro/system messages and route them to the console.
- Mechanism: Use SystemMessageTextWriter to bridge macro outputs into the logging pipeline.
flowchart TD
Start(["Macro Execution"]) --> Write["SystemMessageTextWriter.Write(message)"]
Write --> Filter{"Filter by Level/Source?"}
Filter --> |Yes| Append["Append to DebugViewModel.Logs"]
Filter --> |No| Drop["Discard Entry"]
Append --> Render["UI Renders Entry"]
Drop --> End(["End"])
Render --> End
Diagram sources
Section sources
Packet Diagnostics
- Purpose: Inspect incoming and outgoing packets for network troubleshooting.
- Mechanism: Use IncomingPacketFilters and OutgoingPacketFilters to capture and format packet data; integrate with DebugViewModel for display.
sequenceDiagram
participant Net as "Network Stack"
participant IPF as "IncomingPacketFilters"
participant OPF as "OutgoingPacketFilters"
participant VM as "DebugViewModel"
participant UI as "DebugWindow"
Net->>IPF : Incoming packet
IPF-->>VM : OnIncoming(packet)
VM->>VM : Format packet info
VM-->>UI : Append to Logs
Net->>OPF : Outgoing packet
OPF-->>VM : OnOutgoing(packet)
VM->>VM : Format packet info
VM-->>UI : Append to Logs
Diagram sources
- IncomingPacketFilters.cs
- OutgoingPacketFilters.cs
- PacketFilter.cs
- PacketFilterInfo.cs
- DebugViewModel.cs
- DebugWindow.axaml.cs
Section sources
- IncomingPacketFilters.cs
- OutgoingPacketFilters.cs
- PacketFilter.cs
- PacketFilterInfo.cs
- DebugViewModel.cs
Bootstrap and Initialization
- Purpose: Initialize the application and ensure the Debug Console is wired to shared services.
- Mechanism: App.axaml.cs and Engine.cs set up DI, register services, and start the main window.
flowchart TD
Boot["App Startup"] --> Register["Register Services"]
Register --> InitVM["Initialize DebugViewModel"]
InitVM --> BindUI["Bind DebugWindow DataContext"]
BindUI --> Ready["Console Ready"]
Diagram sources
Section sources
Dependency Analysis
The Debug Console depends on shared services and network filters to aggregate and display diagnostics. Key dependencies include:
- ChatManager for chat integration
- Packet filters for network diagnostics
- SystemMessageTextWriter for macro outputs
- UI components for rendering and user interaction
graph TB
DVM["DebugViewModel.cs"] --> CM["ChatManager.cs"]
DVM --> IPF["IncomingPacketFilters.cs"]
DVM --> OPF["OutgoingPacketFilters.cs"]
DVM --> PF["PacketFilter.cs"]
DVM --> PFI["PacketFilterInfo.cs"]
DVM --> SMTW["SystemMessageTextWriter.cs"]
DW["DebugWindow.axaml.cs"] --> DVM
Diagram sources
- DebugViewModel.cs
- ChatManager.cs
- IncomingPacketFilters.cs
- OutgoingPacketFilters.cs
- PacketFilter.cs
- PacketFilterInfo.cs
- SystemMessageTextWriter.cs
- DebugWindow.axaml.cs
Section sources
Performance Considerations
- Logging Levels:
- High verbosity (Trace/Debug) can significantly impact performance due to increased I/O and UI updates.
- Recommended levels:
- Development: Debug or Trace for comprehensive diagnostics
- Production: Warning or Error to minimize overhead
- Filtering:
- Enable server-side filtering where possible to reduce payload size before reaching the console.
- Use keyword and level filters to limit displayed entries.
- Throttling:
- Implement rate limiting for high-frequency logs (e.g., packet dumps).
- Batch UI updates to avoid excessive re-renders.
- Memory Management:
- Use bounded collections to cap log history size.
- Periodically purge old entries to prevent memory growth.
- Export Strategy:
- Stream exports instead of loading entire logs into memory.
- Compress exported files if large volumes are expected.
[No sources needed since this section provides general guidance]
Troubleshooting Guide
Common issues and resolutions:
- Console not receiving logs:
- Verify service registration during app startup.
- Ensure subscriptions to ChatManager and packet filters are active.
- Slow UI when many logs:
- Reduce logging level or enable filtering.
- Disable auto-scroll if not needed.
- Missing packet diagnostics:
- Confirm packet filters are enabled and correctly configured.
- Check handler registrations for incoming/outgoing packets.
- Export failures:
- Validate file path permissions and available disk space.
- Ensure asynchronous export to avoid blocking UI.
Section sources
Conclusion
The Debug Console in ClassicAssist.Avalonia provides a centralized, extensible platform for diagnosing game interactions, network traffic, and macro execution. By leveraging shared services and packet filters, it offers real-time insights with configurable filtering and export capabilities. Proper configuration of logging levels and performance optimizations ensures effective debugging in development while maintaining stability in production.
[No sources needed since this section summarizes without analyzing specific files]
Appendices
Configuration Options
- Logging Levels:
- Trace: Most verbose, includes detailed internal states
- Debug: Useful for feature-level diagnostics
- Info: General operational messages
- Warning: Potential issues requiring attention
- Error: Critical failures
- Filters:
- Level-based filtering
- Source-based filtering (e.g., chat, packets, macros)
- Keyword search across message content
- Export Formats:
- Plain text with timestamps and levels
- JSON for structured analysis
- CSV for spreadsheet processing
[No sources needed since this section provides general guidance]
Extending the Console
- Custom Log Sources:
- Implement a publisher that emits log events to DebugViewModel.
- Register the publisher during application initialization.
- Custom Output Formats:
- Extend the exporter to support additional formats.
- Integrate with external tools via API endpoints or file watchers.
[No sources needed since this section provides general guidance]