Raxol.Terminal.Graphics.PerformanceMonitor (Raxol v2.0.1)

View Source

Comprehensive performance monitoring system for terminal graphics operations.

This module provides real-time monitoring and analysis of:

  • Graphics operation latency and throughput
  • GPU utilization and memory usage
  • Rendering pipeline performance
  • Cache hit rates and efficiency
  • Resource allocation patterns
  • Performance regression detection

Features

Real-time Monitoring

  • Sub-millisecond operation timing
  • GPU memory usage tracking
  • Rendering pipeline bottleneck detection
  • Cache performance analysis
  • Throughput measurement (operations/second)

Performance Analysis

  • Statistical analysis (percentiles, averages, variance)
  • Performance trend analysis
  • Anomaly detection for performance regressions
  • Comparative analysis across different graphics operations
  • Resource utilization optimization suggestions

Reporting and Alerting

  • Real-time performance dashboards
  • Performance alert thresholds
  • Historical performance data
  • Export capabilities for analysis tools
  • Integration with external monitoring systems

Usage

# Start performance monitoring
{:ok, monitor} = PerformanceMonitor.start_link(%{
  sampling_rate: 100,  # samples per second
  retention_period: 3600,  # 1 hour
  alert_thresholds: %{
    latency_p99: 100,  # 100ms
    gpu_memory_usage: 0.8  # 80%
  }
})

# Monitor a graphics operation
PerformanceMonitor.start_operation(:image_scaling, metadata)
# ... perform operation ...
PerformanceMonitor.end_operation(:image_scaling, result)

# Get performance metrics
metrics = PerformanceMonitor.get_metrics()

Summary

Types

alert_config()
operation_id()
operation_metrics()
operation_type()
performance_stats()
timestamp()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

configure_alert(alert_name, alert_config)

Configures performance alerts.

end_operation(operation_id, result \\ %{})

Ends monitoring of a graphics operation.

generate_report(options \\ %{})

Generates a performance report for the specified time period.

get_metrics()

Gets current performance metrics and statistics.

get_performance_history(options \\ %{})

Gets detailed performance history for analysis.

record_metric(metric_name, value, metadata \\ %{})

Records a custom metric for analysis.

reset_statistics()

Resets all performance statistics and history.

start_link(init_opts \\ [])
start_operation(operation_type, metadata \\ %{})

Starts monitoring a graphics operation.

Types

alert_config()

@type alert_config() :: %{
  threshold: float(),
  comparison: :greater_than | :less_than | :equals,
  consecutive_violations: non_neg_integer(),
  callback: function() | nil
}

operation_id()

@type operation_id() :: String.t()

operation_metrics()

@type operation_metrics() :: %{
  type: operation_type(),
  start_time: timestamp(),
  end_time: timestamp(),
  duration: non_neg_integer(),
  cpu_usage: float(),
  gpu_usage: float(),
  memory_used: non_neg_integer(),
  cache_hits: non_neg_integer(),
  cache_misses: non_neg_integer(),
  metadata: map()
}

operation_type()

@type operation_type() :: atom()

performance_stats()

@type performance_stats() :: %{
  operation_counts: map(),
  latency_percentiles: map(),
  throughput: map(),
  resource_utilization: map(),
  cache_performance: map(),
  error_rates: map()
}

timestamp()

@type timestamp() :: non_neg_integer()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

configure_alert(alert_name, alert_config)

@spec configure_alert(atom(), alert_config()) :: :ok | {:error, term()}

Configures performance alerts.

Examples

PerformanceMonitor.configure_alert(:high_latency, %{
  threshold: 100.0,  # 100ms
  comparison: :greater_than,
  consecutive_violations: 3,
  callback: fn metrics -> Log.warning("High latency detected") end
})

end_operation(operation_id, result \\ %{})

@spec end_operation(operation_id(), map()) :: :ok | {:error, term()}

Ends monitoring of a graphics operation.

Parameters

  • operation_id - ID returned from start_operation/2
  • result - Operation result (success/failure and additional data)

generate_report(options \\ %{})

@spec generate_report(map()) :: {:ok, map()} | {:error, term()}

Generates a performance report for the specified time period.

get_metrics()

@spec get_metrics() :: performance_stats()

Gets current performance metrics and statistics.

get_performance_history(options \\ %{})

@spec get_performance_history(map()) :: [operation_metrics()]

Gets detailed performance history for analysis.

Parameters

  • options - Filtering and formatting options
    • :operation_types - List of operation types to include
    • :time_range - {start_time, end_time} in microseconds
    • :limit - Maximum number of operations to return

record_metric(metric_name, value, metadata \\ %{})

@spec record_metric(atom(), float(), map()) :: :ok

Records a custom metric for analysis.

Examples

PerformanceMonitor.record_metric(:gpu_memory_usage, 75.5, %{
  timestamp: System.system_time(:microsecond),
  unit: :percentage
})

reset_statistics()

@spec reset_statistics() :: :ok

Resets all performance statistics and history.

start_link(init_opts \\ [])

start_operation(operation_type, metadata \\ %{})

@spec start_operation(operation_type(), map()) ::
  {:ok, operation_id()} | {:error, term()}

Starts monitoring a graphics operation.

Parameters

  • operation_type - Type of operation (e.g., :image_scaling, :rendering)
  • metadata - Additional operation metadata

Returns

  • {:ok, operation_id} - Successfully started monitoring
  • {:error, reason} - Failed to start monitoring

Examples

{:ok, op_id} = PerformanceMonitor.start_operation(:image_processing, %{
  image_size: 1024 * 1024,
  format: :png,
  operation: :scale
})