chrani-bot-tng/bot/resources/GUIDELINES_LOGGING.md

Logging System Analysis & Plan

System Architecture Overview

Browser (JavaScript)
    ↕ Socket.io
Python Backend (Flask + Socket.io)
    ↕ Telnet
7D2D Game Server

Current Logging State

Python Backend

• Format: Inconsistent mix of:
  • print(f"[PREFIX] message")
  • print("{}: message".format(module))
  • Plain print("message")
• No:
  • Timestamps
  • Log levels (ERROR, WARN, INFO, DEBUG)
  • User context
  • Correlation IDs
  • Structured data

JavaScript Frontend

• Issues:
  • Ding/Dong logs every 10 seconds (spam)
  • Many debug messages that don't help troubleshooting
  • No structured logging
  • Success messages mixed with errors

Event Flow Analysis

1. User Action Flow

User clicks checkbox (Browser)
  → Widget event sent via Socket.io
    → Python: webserver receives event
      → Python: Action handler (e.g., dom_management/select)
        → Python: DOM upsert
          → Python: Callback triggers
            → Python: Widget handler updates
              → Socket.io sends update back
                → Browser: DOM updated

Critical Logging Points:

• Action received (user, action, data)
• Action validation failed
• DOM operation (path, method, user)
• Callback trigger (which handler, why)
• Socket send (to whom, what type)

2. Tile Request Flow

Browser requests tile (HTTP GET)
  → Python: webserver /map_tiles route
    → Python: Auth check
      → Python: Proxy to game server
        → 7D2D: Returns tile OR error
          → Python: Forward response OR error
            → Browser: Displays tile OR 404

Critical Logging Points:

• Tile request (only on ERROR)
• Auth failure
• Game server error (status code, url)
• Network timeout

3. Telnet Command Flow

Python: Action needs game data
  → Python: Telnet send command
    → 7D2D: Processes command
      → 7D2D: Returns response
        → Python: Parse response
          → Python: Update DOM
            → Python: Trigger callbacks

Log Format

Python Backend Format

[LEVEL] [TIMESTAMP] event_name | context_key=value context_key=value

Example:

[ERROR] [2025-01-19 12:34:56.123] tile_fetch_failed | user=steamid123 z=4 x=-2 y=1 status=404 url=http://...
[WARN ]  [2025-01-19 12:34:57.456] auth_missing_sid | user=steamid456 action=tile_request
[INFO ]  [2025-01-19 12:00:00.000] module_loaded | module=webserver version=1.0

JavaScript Frontend Format

[PREFIX] event_name | context

Example:

[SOCKET ERROR] event_processing_failed | data_type=widget_content error=Cannot read property 'id' of undefined
[MAP ERROR   ] shape_creation_failed | location_id=map_owner_loc1 shape=circle error=Invalid radius