GroupId Logging Enhancement
Overview
Version 6.5.0 introduces GroupId tracking to the structured logging system, providing enhanced context for game events by associating them with specific groups. This enhancement enables administrators to analyze game activity within specific groups and understand group-based user behavior patterns.
🎯 New Features
GroupId Field in GameLog
- Optional Field:
GroupIdin GameLog entity for group association - Contextual Information: Links game events to specific groups
- Search Capability: Filter logs by GroupId for group-specific analysis
- Backward Compatible: Existing logs without GroupId continue to work
Enhanced Admin Interface
- Group Column: New column in log viewer showing GroupId
- Group Filtering: Search logs by specific GroupId
- Visual Display: Shows “-“ for events without group association
- Integrated Search: Combined filtering with existing search options
Enhanced Search Capabilities
- Group-based Filtering: Find all events within a specific group
- Combined Filters: Search by GroupId + PlayerId + GameId + LogType
- Group Analytics: Track group activity patterns over time
- Multi-group Analysis: Compare activity across different groups
📊 Database Schema Changes
Updated GameLog Structure
CREATE TABLE GameLogs (
Id INTEGER PRIMARY KEY AUTOINCREMENT,
Timestamp DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
LogType INTEGER NOT NULL,
PlayerId INTEGER NOT NULL,
GameId INTEGER NULL,
GroupId INTEGER NULL, -- NEW: Group association
OpponentPlayerId INTEGER NULL,
Details TEXT NULL
);
Migration Notes
- Automatic Addition: GroupId column added to existing tables
- NULL Values: Existing logs have GroupId = NULL (displayed as “-“)
- No Breaking Changes: All existing functionality preserved
- Default Behavior: New logs include GroupId when available
🔍 Enhanced Search Examples
Group-specific Analysis
// Get all activity for group 123
var groupLogs = await GameLog.SearchLogsAsync(
groupId: 123,
count: 100
);
// Find all games created in group 456
var groupGames = await GameLog.SearchLogsAsync(
groupId: 456,
logType: LogType.GameCreated,
count: 50
);
Combined Filtering
// Find all game endings for player 7 in group 123
var playerGroupGames = await GameLog.SearchLogsAsync(
playerId: 7,
groupId: 123,
logType: LogType.GameEnded,
count: 25
);
// Get all activity in group 456 for the last week
var recentGroupActivity = await GameLog.SearchLogsAsync(
groupId: 456,
startDate: DateTime.UtcNow.AddDays(-7),
count: 200
);
🎨 Enhanced Admin Interface
New Table Structure
| Timestamp | Type | Player | Game | Group | Details |
|---------------------|------------|-------------|------|-------|-----------------------------|
| 2026-03-27 12:00:00 | GameStarted | Alice vs Bob| 1234 | 456 | Game started - Alice joined |
| 2026-03-27 12:05:00 | GameEnded | Alice vs Bob| 1234 | 456 | Winner: Alice, Loser: Bob |
| 2026-03-27 12:10:00 | PlayerLogin | Carol | - | 789 | Player Carol logged in |
Search Interface Enhancements
- Group ID Field: Numeric input for GroupId filtering
- Clear Button: Resets all filters including GroupId
- Real-time Search: Instant filtering as you type
- Combined Results: Shows logs matching all criteria
Visual Group Information
- Group Display: Shows GroupId when available
- Empty Groups: Shows “-“ for events without group association
- Consistent Styling: Matches existing table formatting
- Responsive Design: Works on all screen sizes
📝 Code Implementation
Enhanced Logging Methods
// Game events with GroupId
await GameLog.LogGameEventAsync(
LogType.GameCreated,
userId,
gameId,
"Game created",
null,
groupId // NEW: Group association
);
// Wins with GroupId
await GameLog.LogWinAsync(
winnerId,
loserId,
gameId,
"Winner: Alice, Loser: Bob",
groupId // NEW: Group association
);
// Player actions with GroupId
await GameLog.LogPlayerActionAsync(
LogType.PlayerLogin,
userId,
"Player logged in",
null,
groupId // NEW: Group association
);
Search Method Enhancement
public async Task<List<GameLog>> SearchLogsAsync(
int? playerId = null,
int? gameId = null,
int? groupId = null, // NEW: Group filtering
LogType? logType = null,
DateTime? startDate = null,
DateTime? endDate = null,
int count = 100
)
Integration Points
// DraftsService.cs - Game creation
_ = _gameLog.LogGameEventAsync(
LogType.GameCreated,
userId,
gameId,
$"Game created by {displayName}",
null,
groupId // From game object
);
// Game joining with GroupId
_ = _gameLog.LogGameEventAsync(
LogType.GameJoined,
userId,
gameId,
"Player joined",
null,
game.GroupId // From game object
);
📈 Use Cases and Benefits
Group Management
- Activity Tracking: Monitor which groups are most active
- User Behavior: Understand how different groups use the system
- Resource Planning: Allocate server resources based on group usage
- Security Monitoring: Track unusual activity patterns per group
Administrative Analysis
- Group Comparison: Compare activity levels between groups
- Problem Isolation: Identify issues specific to certain groups
- Usage Statistics: Generate group-specific metrics
- Performance Monitoring: Track group-specific performance issues
User Experience
- Context Awareness: Understand the group context of events
- Debugging: Isolate issues to specific group environments
- Reporting: Generate group-based activity reports
- Analytics: Analyze group engagement patterns
🔍 Search Scenarios
Common Administrative Queries
// Most active groups (by log volume)
var activeGroups = await GameLog.SearchLogsAsync(
count: 1000
).GroupBy(x => x.GroupId)
.OrderByDescending(g => g.Count())
.Take(10);
// Recent activity in specific group
var groupActivity = await GameLog.SearchLogsAsync(
groupId: targetGroupId,
startDate: DateTime.UtcNow.AddDays(-1),
count: 50
);
// Games created by group
var groupGames = await GameLog.SearchLogsAsync(
groupId: targetGroupId,
logType: LogType.GameCreated,
count: 100
);
Troubleshooting Examples
// Find all timeouts in a specific group
var groupTimeouts = await GameLog.SearchLogsAsync(
groupId: problemGroupId,
logType: LogType.GameTimeout,
count: 25
);
// Check player activity across groups
var playerGroupActivity = await GameLog.SearchLogsAsync(
playerId: problemPlayerId,
count: 50
).Where(x => x.GroupId.HasValue);
// Group-specific error patterns
var groupErrors = await GameLog.SearchLogsAsync(
groupId: targetGroupId,
logType: LogType.Error,
count: 10
);
🚀 Performance Considerations
Database Optimization
- Index Strategy: Consider adding index on GroupId for frequent queries
- Query Efficiency: GroupId filtering done at database level
- Memory Usage: Minimal impact - one additional nullable field
- Search Performance: Combined filters maintain efficiency
UI Performance
- Rendering: Additional column has minimal impact on table rendering
- Search Speed: GroupId filtering is instant with existing search
- Data Loading: No additional data loading required
- Responsive Design: Table adapts to new column gracefully
🔧 Migration Guide
For Existing Applications
- Deploy New Version: Automatic GroupId column addition
- No Code Changes Required: Existing logging calls work unchanged
- Optional Enhancement: Gradually add GroupId to new logging calls
- Admin Training: Introduce new GroupId filtering capabilities
For New Development
- Use Enhanced Methods: Include GroupId parameter where available
- Group-Aware Design: Consider GroupId in logging strategy
- Search Optimization: Leverage GroupId filtering for analysis
- Documentation: Maintain GroupId logging standards
🎯 Best Practices
GroupId Logging Guidelines
- Include When Available: Add GroupId to all game-related events
- Null for Non-Group Events: Don’t force GroupId for system events
- Consistent Usage: Use GroupId uniformly across similar event types
- Context Relevance: Only include GroupId when it adds meaningful context
Search Optimization
- Group-Specific Queries: Use GroupId filtering for focused analysis
- Combined Filtering: Leverage multiple filters for precise results
- Result Limiting: Limit search results to maintain performance
- Date Ranges: Combine GroupId with date filtering for temporal analysis
Administrative Usage
- Regular Monitoring: Check group activity patterns periodically
- Issue Isolation: Use GroupId to isolate problems to specific groups
- Resource Planning: Allocate resources based on group usage patterns
- Security Auditing: Monitor group-specific security events
📊 Example Reports
Group Activity Summary
Group Activity Report - Last 7 Days
===================================
Group 123: 156 events (45 games, 89 logins, 18 timeouts)
Group 456: 89 events (23 games, 54 logins, 12 timeouts)
Group 789: 234 events (67 games, 134 logins, 33 timeouts)
Group-Specific Issues
Group 456 - High Timeout Rate
================================
- 12 timeout events detected
- Average game duration: 8.5 minutes
- Most common: Turn timeout (75%)
- Recommendation: Review player skill levels
Performance by Group
Group Performance Metrics
========================
Group 123: Avg game time 12.3 min, 95% completion rate
Group 456: Avg game time 8.7 min, 78% completion rate
Group 789: Avg game time 15.2 min, 89% completion rate
🔮 Future Enhancements
Potential Improvements
- Group Names: Display group names instead of IDs
- Group Analytics Dashboard: Dedicated group analysis interface
- Group-based Alerts: Automatic notifications for group issues
- Group Comparison Tools: Side-by-side group activity comparison
- Export Capabilities: Export group-specific log data
Advanced Features
- Group Hierarchies: Support for nested group structures
- Group Permissions: Role-based access to group logs
- Group Metrics: Automated group performance indicators
- Group Trends: Historical group activity trending
📚 Integration with Group System
Future Group Features
This GroupId enhancement lays the foundation for future group management features:
- Group Creation: Admin creates groups and assigns owners
- Group Membership: Players join groups by invitation or request
- Group-Specific Games: Games visible only to group members
- Group Analytics: Comprehensive group-based reporting
Current Benefits
- Activity Tracking: Foundation for group activity monitoring
- Context Preservation: Group context preserved in historical logs
- Search Foundation: Group-based filtering ready for future features
- Scalable Design: Architecture supports advanced group features
Version: 6.5.1
Implemented: 2026-03-27
Type: Enhancement
Backward Compatible: ✅ Yes
GroupId Support: ✅ Yes
Search Enhanced: ✅ Yes
Admin Interface: ✅ Updated
