Skip to main content

​
Overview

The SimulationBank API provides comprehensive metrics for analyzing simulation performance, including wait times, throughput, utilization, and queue statistics. Metrics are collected in real-time during simulation and can be retrieved via the /api/metrics endpoints.

​
Simulation Report

The primary metrics structure returned by GET /api/metrics/report.

​
Schema

​
simulation_id
string
Unique identifier for the simulation run.
​
total_simulation_time
float
Total elapsed simulation time in seconds.Example: 14400.0 (4 hours)
​
customers_arrived
integer
Total number of customers who arrived at the bank during the simulation.Note: Includes both served and rejected customers.
​
customers_served
integer
Total number of customers who successfully completed service.Formula: customers_arrived - customers_rejected
​
customers_rejected
integer
Number of customers rejected due to queue being at maximum capacity.Note: This metric indicates lost business and capacity issues.

​
Wait Time Metrics

​
average_wait_time
float
Mean wait time across all customers (in seconds).Calculation: Average of (service_start_time - arrival_time) for all served customers.Example: 45.3 seconds
​
wait_time_by_priority
object
Average wait times broken down by priority level.
​
max_wait_time
float
Maximum wait time experienced by any customer.Example: 450.2 seconds
​
min_wait_time
float
Minimum wait time experienced by any customer.Example: 0.0 seconds (served immediately)

​
Service Time Metrics

​
average_service_time
float
Mean service time across all served customers (in seconds).Example: 3.98 seconds
​
average_total_time
float
Mean total time in system (wait + service) in seconds.Formula: average_wait_time + average_service_timeExample: 49.28 seconds

​
Queue Metrics

​
max_queue_length
integer
Peak queue length observed during the simulation.Example: 23 customersNote: If this equals max_queue_capacity, customers were likely rejected.
​
average_queue_length
float
Time-weighted average queue length throughout the simulation.Calculation: Integral of queue length over time divided by total time.Example: 8.4 customers

​
Utilization Metrics

​
teller_utilization
object
Utilization rate (0.0 to 1.0) for each individual teller.Format: { "teller_id": utilization_rate }Example:
{
  "T-1": 0.89,
  "T-2": 0.87,
  "T-3": 0.91
}
​
overall_utilization
float
Average utilization across all tellers (0.0 to 1.0).Calculation: Mean of all teller utilization rates.Example: 0.89 (89% utilized)
Utilization above 0.90 (90%) often indicates the system is near capacity and may experience long queues.

​
Throughput Metrics

​
throughput
float
System throughput measured as customers served per unit time.Formula: customers_served / total_simulation_timeUnits: customers per secondExample: 0.149 customers/second (≈8.94 customers/minute)

​
System Health Metrics

​
starvation_incidents
integer
Number of times the system became completely idle (all tellers idle with no customers waiting).Example: 3 incidents
Frequent starvation indicates low arrival rate or excess capacity. Rare starvation is normal.

​
Live Metrics

Real-time metrics returned by GET /api/metrics/live during an active simulation.
​
current_time
float
Current simulation clock time in seconds.
​
current_queue_length
integer
Number of customers currently waiting in queue.
​
active_tellers
integer
Number of tellers currently serving customers (status = BUSY).
​
idle_tellers
integer
Number of tellers currently available (status = IDLE).
​
customers_served_so_far
integer
Total customers served up to the current simulation time.
​
customers_in_system
integer
Total customers currently in the system (waiting + being served).
​
recent_throughput
float
Customers served in the last time window.Units: customers per minuteExample: 8.94 customers/minute

​
Wait Time Record

Detailed record for individual customer wait times (used internally for metrics calculation).
​
customer_id
string
Customer identifier.
​
priority
integer
Customer priority level (1, 2, or 3).
​
wait_time
float
Time spent waiting in queue (seconds).
​
service_time
float
Time spent being served (seconds).
​
total_time
float
Total time in system: wait_time + service_time

​
Throughput Record

Throughput measurement over a time interval (used for time-series analysis).
​
timestamp
float
Simulation time when the measurement was taken.
​
customers_served
integer
Number of customers served during this interval.
​
customers_rejected
integer
Number of customers rejected during this interval.

​
Example Complete Report

{
  "status": "success",
  "data": {
    "simulation_id": "a3f2c1b5",
    "total_simulation_time": 14400.0,
    "customers_arrived": 2156,
    "customers_served": 2148,
    "customers_rejected": 8,
    "average_wait_time": 45.3,
    "wait_time_by_priority": {
      "1": 12.5,
      "2": 38.2,
      "3": 67.8
    },
    "max_wait_time": 450.2,
    "min_wait_time": 0.0,
    "average_service_time": 3.98,
    "average_total_time": 49.28,
    "max_queue_length": 23,
    "average_queue_length": 8.4,
    "teller_utilization": {
      "T-1": 0.89,
      "T-2": 0.87,
      "T-3": 0.91
    },
    "overall_utilization": 0.89,
    "throughput": 0.149,
    "starvation_incidents": 3
  }
}

​
Key Performance Indicators

​
System Efficiency

​
service_level
derived
Percentage of customers served (not rejected).Formula: (customers_served / customers_arrived) × 100Target: > 99%
​
average_wait_ratio
derived
Ratio of wait time to service time.Formula: average_wait_time / average_service_timeInterpretation:
  • < 1.0: Wait time less than service time (good)
  • 1.0-2.0: Moderate queue delays
  • 2.0: Significant queueing issues
​
utilization_balance
derived
Variance in utilization across tellers.Interpretation: Low variance indicates balanced workload distribution.

​
Priority Fairness

​
priority_wait_ratio
derived
Ratio between priority level wait times.Example:
Wait time ratio (HIGH:MEDIUM:LOW) = 1:3:5.4
Interpretation: Shows effectiveness of priority queue system.

​
Metrics Best Practices

Always allow simulations to reach steady-state before analyzing metrics. Initial transient periods may skew results.
For reliable statistics, run simulations for at least 1000 customer arrivals or 2+ hours of simulation time.
  1. Capacity Planning: Use overall_utilization and throughput to determine if staffing is adequate
  2. Service Quality: Monitor average_wait_time and wait_time_by_priority to ensure SLA compliance
  3. Resource Optimization: Compare individual teller_utilization to identify imbalances
  4. Bottleneck Detection: Check if max_queue_length approaches max_queue_capacity

Build docs developers (and LLMs) love

Get started for freeTalk to us