stats.c File Reference

📊 Server performance monitoring: resource utilization tracking, client metrics, and health reporting More...

Go to the source code of this file.

Functions
int	stats_init (void)
	Initialize the stats mutex.
void	stats_cleanup (void)
	Cleanup the stats mutex.
void *	stats_logger_thread (void *arg)
	Main statistics collection and reporting thread function.
void	update_server_stats (void)
	Update global server statistics (placeholder)
void	log_server_stats (void)
	Log comprehensive server statistics summary.

Variables
server_stats_t	g_stats = {0}
	Global server statistics structure.
mutex_t	g_stats_mutex = {0}
	Mutex protecting global server statistics.
atomic_bool	g_server_should_exit
	Global shutdown flag from main.c - coordinate statistics thread termination.

Detailed Description

📊 Server performance monitoring: resource utilization tracking, client metrics, and health reporting

1. Continuous monitoring of server performance metricsmetricsPer-client statistics collection and reportingreportingBuffer pool utilization trackingtrackingPacket queue performance analysisanalysisHash table efficiency monitoringmonitoringPeriodic statistics logging for operational visibility MONITORING ARCHITECTURE:

STATISTICS COLLECTION THREAD:

• Dedicated background thread for non-intrusive monitoring
• 30-second reporting intervals (configurable)
• Interruptible sleep for responsive shutdown
• Thread-safe data collection from all system components

PERFORMANCE IMPACT MINIMIZATION:

• Read-only access to operational data structures
• Minimal locking (reader locks where possible)
• Background processing doesn't affect real-time performance
• Throttled logging to prevent log spam

MONITORED SUBSYSTEMS:

CLIENT MANAGEMENT METRICS:

• Active client count
• Clients with audio capabilities
• Clients with video capabilities
• Connection duration and activity patterns

BUFFER POOL PERFORMANCE:

• Global buffer pool utilization
• Allocation/deallocation rates
• Peak usage patterns
• Memory efficiency metrics

PACKET QUEUE STATISTICS:

• Per-client queue depths
• Enqueue/dequeue rates
• Packet drop rates under load
• Queue overflow incidents

HASH TABLE EFFICIENCY:

• Client lookup performance
• Hash collision rates
• Load factor monitoring
• Access pattern analysis

FRAME PROCESSING METRICS:

• Total frames captured
• Total frames sent to clients
• Frame drop rate under load
• Blank frame count (no video sources)

THREAD SAFETY AND DATA CONSISTENCY:

NON-INTRUSIVE MONITORING:

• Uses reader locks to avoid blocking operational threads
• Takes atomic snapshots of volatile data
• Minimal impact on render thread performance
• Safe concurrent access to client data

STATISTICS ATOMICITY:

• Global statistics protected by dedicated mutex
• Consistent reporting even during concurrent updates
• Thread-safe access to shared counters

OPERATIONAL INTEGRATION:

LIFECYCLE MANAGEMENT:

• Statistics thread started in main.c during server initialization
• Graceful shutdown coordination with other threads
• Clean resource cleanup on server termination

DEBUGGING SUPPORT:

• Extensive debug logging for troubleshooting
• Performance bottleneck identification
• System health monitoring
• Operational visibility for administrators

EXTENSIBILITY FRAMEWORK:

METRIC ADDITION:

• Easy addition of new performance counters
• Modular statistics collection
• Configurable reporting intervals
• Custom metric aggregation

INTEGRATION POINTS:

• client.c: Client lifecycle statistics
• render.c: Frame processing metrics
• buffer_pool.c: Memory utilization data
• packet_queue.c: Queue performance data

WHY THIS MODULAR DESIGN:

The original server.c had no centralized monitoring, making it impossible to:

• Understand system performance characteristics
• Debug performance issues under load
• Monitor resource utilization
• Track client behavior patterns

This separation provides:

• Centralized performance visibility
• Non-intrusive monitoring infrastructure
• Operational debugging capabilities
• System health awareness

PERFORMANCE PHILOSOPHY:

• Monitoring should never impact real-time performance
• Statistics collection uses minimal CPU overhead
• Background processing model
• Graceful degradation under extreme load

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

September 2025

Version

2.0 (Post-Modularization)

See also

main.c For statistics thread lifecycle management

buffer_pool.c For memory utilization monitoring

packet_queue.c For queue performance metrics

Definition in file stats.c.

Function Documentation

log_server_stats()

void log_server_stats

(

void

)

Log comprehensive server statistics summary.

Outputs a formatted summary of server performance statistics including frame processing rates, throughput metrics, and system health indicators. This function provides operational visibility into server performance.

STATISTICS REPORTED:

FRAME PROCESSING METRICS:

• frames_captured: Total frames received from all clients
• frames_sent: Total ASCII frames delivered to all clients
• frames_dropped: Frames lost due to overload or errors

PERFORMANCE INDICATORS:

• avg_capture_fps: Moving average of frame capture rate
• avg_send_fps: Moving average of frame delivery rate

THREAD SAFETY:

• Acquires g_stats_mutex for atomic statistics snapshot
• Prevents inconsistent reporting during concurrent updates
• Minimal lock hold time (only during data copy)

USAGE SCENARIOS:

• Periodic performance reporting
• Debug information during troubleshooting
• System health monitoring
• Performance trend analysis

OUTPUT FORMAT:

• Human-readable format suitable for log analysis
• Structured data for automated monitoring
• Consistent formatting for operational visibility

Note

Function provides thread-safe access to global statistics

Statistics snapshot is atomic to ensure consistency

See also

update_server_stats() For statistics update implementation

Definition at line 559 of file stats.c.

                            {
  // Check if stats mutex is initialized before trying to lock it
  // In debug builds, stats_init() may not be called (it's guarded by #ifdef NDEBUG)
  // Skip logging if mutex is not initialized to avoid crashing
  if (!g_stats_mutex_initialized) {
    return; // Mutex not initialized, skip logging
  }
  mutex_lock(&g_stats_mutex);
  log_info("Server Statistics:\n"
           "  frames_captured=%llu\n"
           "  frames_sent=%llu\n"
           "  frames_dropped=%llu\n"
           "  Average FPS: capture=%.2f, send=%.2f",
           (unsigned long long)g_stats.frames_captured, (unsigned long long)g_stats.frames_sent,
           (unsigned long long)g_stats.frames_dropped, g_stats.avg_capture_fps, g_stats.avg_send_fps);
  mutex_unlock(&g_stats_mutex);
}

References server_stats_t::avg_capture_fps, server_stats_t::avg_send_fps, server_stats_t::frames_captured, server_stats_t::frames_dropped, server_stats_t::frames_sent, g_stats, g_stats_mutex, log_info, mutex_lock, and mutex_unlock.

Referenced by stats_logger_thread().

stats_cleanup()

void stats_cleanup

(

void

)

Cleanup the stats mutex.

Definition at line 195 of file stats.c.

                         {
  if (g_stats_mutex_initialized) {
    mutex_destroy(&g_stats_mutex);
    g_stats_mutex_initialized = false;
  }
}

References g_stats_mutex, and mutex_destroy().

Referenced by server_main().

stats_init()

int stats_init

(

void

)

Initialize the stats mutex.

Returns

0 on success, -1 on failure

Definition at line 184 of file stats.c.

                     {
  int ret = mutex_init(&g_stats_mutex);
  if (ret == 0) {
    g_stats_mutex_initialized = true;
  }
  return ret;
}

References g_stats_mutex, and mutex_init().

Referenced by server_main().

stats_logger_thread()

void * stats_logger_thread

(

void *

arg

)

Main statistics collection and reporting thread function.

This background thread performs continuous monitoring of server performance and logs comprehensive statistics reports at regular intervals. It operates independently of the main server processing threads to avoid performance impact.

THREAD EXECUTION FLOW:

1. INITIALIZATION:
   • Log thread startup (with debug instrumentation)
   • Initialize loop counters for debugging
   • Set up monitoring infrastructure
2. MAIN MONITORING LOOP:
   • Check shutdown flag frequently (every 10ms)
   • Sleep in small intervals to maintain responsiveness
   • Collect statistics from all system components every 30 seconds
   • Generate comprehensive performance reports
3. STATISTICS COLLECTION:
   • Global buffer pool utilization
   • Per-client connection and activity status
   • Packet queue performance metrics
   • Hash table efficiency statistics
   • Frame processing counters
4. CLEANUP AND EXIT:
   • Detect shutdown signal and exit loop gracefully
   • Log thread termination for debugging
   • Return NULL to indicate clean exit

MONITORING METHODOLOGY:

NON-BLOCKING DATA COLLECTION:

• Uses reader locks on shared data structures
• Takes atomic snapshots of volatile counters
• Minimal impact on operational performance
• Safe concurrent access with render threads

RESPONSIVE SHUTDOWN:

• Checks g_server_should_exit every 10ms during sleep periods
• Exits monitoring loop immediately when shutdown detected
• No hanging or delayed shutdown behavior
• Clean resource cleanup

PERFORMANCE METRICS COLLECTED:

CLIENT STATISTICS:

• Total active clients
• Clients with audio queues active
• Clients with video queues active
• Per-client connection duration

BUFFER POOL METRICS:

• Global allocation/deallocation rates
• Peak memory usage patterns
• Buffer pool efficiency
• Memory fragmentation indicators

PACKET QUEUE PERFORMANCE:

• Per-client enqueue/dequeue rates
• Packet drop incidents
• Queue depth histograms
• Overflow frequency analysis

HASH TABLE EFFICIENCY:

• Client lookup performance
• Hash collision statistics
• Load balancing effectiveness
• Access pattern analysis

DEBUGGING AND TROUBLESHOOTING:

EXTENSIVE DEBUG LOGGING: The function contains detailed debug printf statements for troubleshooting threading issues. This instrumentation helps diagnose:

• Thread startup/shutdown problems
• Shutdown detection timing issues
• Sleep/wake cycle behavior
• Statistics collection reliability

DEBUG OUTPUT INCLUDES:

• Function entry/exit points
• Loop iteration counts
• Shutdown flag state changes
• Sleep cycle progression
• Statistics collection timing

ERROR HANDLING:

• Graceful handling of data access failures
• Continued operation if individual metrics fail
• No fatal errors that would crash statistics thread
• Degraded reporting if subsystems unavailable

PERFORMANCE CONSIDERATIONS:

• 30-second reporting interval balances visibility vs overhead
• 10ms sleep granularity provides responsive shutdown
• Read-only access minimizes lock contention
• Background processing doesn't affect real-time performance

Parameters

arg	Thread argument (unused - required by thread interface)

Returns

NULL on clean thread termination

Note

This function runs continuously until server shutdown

Debug printf statements help diagnose threading issues

All statistics collection is non-blocking and read-only

Warning

Thread must be properly joined to prevent resource leaks

Definition at line 332 of file stats.c.

                                     {
  (void)arg;
 
  while (!atomic_load(&g_server_should_exit)) {
    // Log buffer pool statistics every 10 seconds with fast exit checking (10ms intervals)
    for (int i = 0; i < 1000 && !atomic_load(&g_server_should_exit); i++) {
      platform_sleep_usec(10000); // 10ms sleep
    }
 
    // Check exit condition before proceeding with statistics logging
    // CRITICAL: Check multiple times to avoid accessing freed resources during shutdown
    if (atomic_load(&g_server_should_exit)) {
      break;
    }
 
    // Collect all statistics data first
#ifndef NDEBUG
    char lock_debug_info[512] = {0};
    // CRITICAL: Check exit condition again before accessing lock_debug
    // lock_debug might be destroyed during shutdown
    if (!atomic_load(&g_server_should_exit) && lock_debug_is_initialized()) {
      uint64_t total_acquired = 0, total_released = 0;
      uint32_t currently_held = 0;
      lock_debug_get_stats(&total_acquired, &total_released, &currently_held);
 
      safe_snprintf(lock_debug_info, sizeof(lock_debug_info),
                    "Historical Mutex/RWLock Statistics:\n"
                    "  Total locks acquired: %llu\n"
                    "  Total locks released: %llu\n"
                    "  Currently held: %u\n"
                    "  Net locks (acquired - released): %lld",
                    (unsigned long long)total_acquired, (unsigned long long)total_released, currently_held,
                    (long long)total_acquired - (long long)total_released);
    }
#endif
 
    // Collect client statistics
    // CRITICAL: Check exit condition again before accessing rwlock
    // rwlock might be destroyed during shutdown
    if (atomic_load(&g_server_should_exit)) {
      break;
    }
 
    rwlock_rdlock(&g_client_manager_rwlock);
    int active_clients = 0;
    int clients_with_audio = 0;
    int clients_with_video = 0;
    char client_details[2048] = {0};
    int client_details_len = 0;
 
    for (int i = 0; i < MAX_CLIENTS; i++) {
      if (atomic_load(&g_client_manager.clients[i].active)) {
        active_clients++;
        if (g_client_manager.clients[i].audio_queue) {
          clients_with_audio++;
        }
        if (g_client_manager.clients[i].outgoing_video_buffer) {
          clients_with_video++;
        }
      }
    }
 
    // Collect per-client details
    for (int i = 0; i < MAX_CLIENTS; i++) {
      client_info_t *client = &g_client_manager.clients[i];
      bool is_active = atomic_load(&client->active);
      uint32_t client_id_snapshot = atomic_load(&client->client_id);
 
      if (is_active && client_id_snapshot != 0) {
        // Check audio queue stats
        if (client->audio_queue) {
          uint64_t enqueued, dequeued, dropped;
          packet_queue_get_stats(client->audio_queue, &enqueued, &dequeued, &dropped);
          if (enqueued > 0 || dequeued > 0 || dropped > 0) {
            int len =
                snprintf(client_details + client_details_len, sizeof(client_details) - client_details_len,
                         "  Client %u audio queue: %llu enqueued, %llu dequeued, %llu dropped", client_id_snapshot,
                         (unsigned long long)enqueued, (unsigned long long)dequeued, (unsigned long long)dropped);
            if (len > 0 && client_details_len + len < (int)sizeof(client_details)) {
              client_details_len += len;
            }
          }
        }
        // Check video buffer stats
        if (client->outgoing_video_buffer) {
          video_frame_stats_t stats;
          video_frame_get_stats(client->outgoing_video_buffer, &stats);
          if (stats.total_frames > 0) {
            int len = snprintf(client_details + client_details_len, sizeof(client_details) - client_details_len,
                               "  Client %u video buffer: %llu frames, %llu dropped (%.1f%% drop rate)",
                               client_id_snapshot, (unsigned long long)stats.total_frames,
                               (unsigned long long)stats.dropped_frames, stats.drop_rate * 100.0f);
            if (len > 0 && client_details_len + len < (int)sizeof(client_details)) {
              client_details_len += len;
            }
          }
        }
      }
    }
    rwlock_rdunlock(&g_client_manager_rwlock);
 
    // Single comprehensive log statement
    if (client_details_len > 0) {
      log_info("Stats: Clients: %d, Audio: %d, Video: %d\n%s", active_clients, clients_with_audio, clients_with_video,
               client_details);
    }
  }
 
  log_server_stats();
 
  asciichat_error_stats_print();
 
  // Clean up thread-local error context before exit
  asciichat_errno_cleanup();
 
  return NULL;
}

References client_info::active, asciichat_errno_cleanup(), asciichat_error_stats_print(), client_info::audio_queue, client_info::client_id, client_manager_t::clients, video_frame_stats_t::drop_rate, video_frame_stats_t::dropped_frames, g_client_manager, g_client_manager_rwlock, g_server_should_exit, lock_debug_is_initialized(), log_info, log_server_stats(), MAX_CLIENTS, client_info::outgoing_video_buffer, packet_queue_get_stats(), platform_sleep_usec(), rwlock_rdlock, rwlock_rdunlock, safe_snprintf(), video_frame_stats_t::total_frames, and video_frame_get_stats().

Referenced by server_main().

update_server_stats()

void update_server_stats

(

void

)

Update global server statistics (placeholder)

This function is intended to update the global server statistics structure with current performance metrics. Currently unimplemented but provides the framework for centralized statistics updates.

PLANNED FUNCTIONALITY:

• Aggregate per-client frame counts into global totals
• Calculate moving averages for FPS metrics
• Update system health indicators
• Compute performance trend data

IMPLEMENTATION STRATEGY:

• Thread-safe updates using g_stats_mutex
• Atomic operations for frequently updated counters
• Efficient aggregation algorithms
• Minimal performance impact

INTEGRATION POINTS:

• Called by render threads when updating frame counts
• Invoked by client management code for connection metrics

• Used by packet queue systems for throughput tracking

  Todo:

  Implement comprehensive statistics aggregation

  Note

  Function currently serves as placeholder for future development

Definition at line 478 of file stats.c.

                               {
  // Aggregate statistics from all active clients
  uint64_t total_frames_sent = 0;
  uint64_t total_frames_dropped = 0;
 
  // Read-lock to safely iterate over all clients
  rwlock_rdlock(&g_client_manager_rwlock);
 
  for (int i = 0; i < MAX_CLIENTS; i++) {
    client_info_t *client = &g_client_manager.clients[i];
    if (atomic_load(&client->client_id) != 0 && atomic_load(&client->active)) {
      // Aggregate frames sent to all clients
      total_frames_sent += client->frames_sent;
 
      // Get dropped frame statistics from outgoing video buffer
      if (client->outgoing_video_buffer) {
        video_frame_stats_t stats;
        video_frame_get_stats(client->outgoing_video_buffer, &stats);
        total_frames_dropped += stats.dropped_frames;
      }
    }
  }
 
  rwlock_rdunlock(&g_client_manager_rwlock);
 
  // Update global statistics atomically
  mutex_lock(&g_stats_mutex);
  g_stats.frames_sent = total_frames_sent;
  g_stats.frames_dropped = total_frames_dropped;
 
  // Calculate frames_captured from frames_sent and frames_dropped
  // frames_captured = frames_sent + frames_dropped (total output frames)
  if (total_frames_sent > 0 || total_frames_dropped > 0) {
    g_stats.frames_captured = total_frames_sent + total_frames_dropped;
  }
 
  mutex_unlock(&g_stats_mutex);
}

References client_info::active, client_info::client_id, client_manager_t::clients, video_frame_stats_t::dropped_frames, server_stats_t::frames_captured, server_stats_t::frames_dropped, client_info::frames_sent, server_stats_t::frames_sent, g_client_manager, g_client_manager_rwlock, g_stats, g_stats_mutex, MAX_CLIENTS, mutex_lock, mutex_unlock, client_info::outgoing_video_buffer, rwlock_rdlock, rwlock_rdunlock, and video_frame_get_stats().

Variable Documentation

g_server_should_exit

atomic_bool g_server_should_exit

extern

Global shutdown flag from main.c - coordinate statistics thread termination.

The statistics thread monitors this flag to detect server shutdown and exit its monitoring loop gracefully, ensuring clean resource cleanup.

Global shutdown flag from main.c - coordinate statistics thread termination.

Global shutdown flag from main.c - coordinate graceful thread termination.

Global shutdown flag from main.c - used to avoid error spam during shutdown.

Global shutdown flag from main.c.

This flag is the primary coordination mechanism for clean server shutdown. It's atomic to ensure thread-safe access without mutexes, as it's checked frequently in tight loops across all worker threads.

USAGE PATTERN:

• Set to true by signal handlers (SIGINT/SIGTERM) or main loop on error
• Checked by all worker threads to know when to exit gracefully
• Must be atomic to prevent race conditions during shutdown cascade

Definition at line 135 of file server/main.c.

Referenced by stats_logger_thread().

g_stats

server_stats_t g_stats = {0}

Global server statistics structure.

Maintains aggregated performance metrics for the entire server including frame processing rates, client counts, and system health indicators. All access to this structure must be protected by g_stats_mutex.

CONTENTS:

• frames_captured: Total frames received from all clients
• frames_sent: Total ASCII frames delivered to all clients
• frames_dropped: Frames lost due to buffer overflows or processing delays
• avg_capture_fps: Moving average of frame capture rate
• avg_send_fps: Moving average of frame delivery rate

Definition at line 159 of file stats.c.

{0};

Referenced by log_server_stats(), server_main(), and update_server_stats().

g_stats_mutex

mutex_t g_stats_mutex = {0}

Mutex protecting global server statistics.

Ensures thread-safe access to g_stats structure from both the statistics collection thread and any operational threads that update counters. Uses standard mutex (not reader-writer) due to relatively infrequent access.

Definition at line 168 of file stats.c.

{0};

Referenced by log_server_stats(), server_main(), stats_cleanup(), stats_init(), and update_server_stats().