Metrics server

EmptyEpsilon exposes a Prometheus metrics endpoint when running as a server (not as a client). This allows monitoring game state, server performance, and player ship status with Prometheus and visualizing the data with Grafana using the included sample dashboard.

Note: The metrics server is independent of the HTTP Server; enable it separately.

Enabling the metrics endpoint

With options.ini

Edit the Preferences file (options.ini) and add this line, choosing any unused TCP port:

metricsserver=9100

On the command line

./EmptyEpsilon metricsserver=9100

Setting the value to 0 or omitting it disables the endpoint. Port numbers under 10 are rounded up to 80.

Verify the endpoint

curl http://localhost:9100/metrics

Expected output begins with:

# EmptyEpsilon Prometheus Metrics
# Version <number>

# HELP ee_game_speed Current game speed multiplier (0 = paused)
# TYPE ee_game_speed gauge
ee_game_speed 1

Available metrics

All metric names are prefixed with ee_.

Metric	Type	Description
ee_game_speed	Gauge	Current game speed multiplier (0 = paused)
ee_elapsed_time_seconds	Gauge	Total in-game seconds elapsed
ee_entity_count	Gauge	Number of active ECS entities
ee_update_duration_seconds{phase}	Gauge	Per-subsystem update wall time in seconds
ee_server_send_bytes_per_second	Gauge	Total network send rate in bytes/s
ee_server_send_bytes_per_second_per_client	Gauge	Per-client network send rate in bytes/s
ee_server_update_duration_seconds	Gauge	Time spent in the server update cycle
ee_server_client_count	Gauge	Number of connected game clients
ee_server_client_ping_milliseconds{client_id}	Gauge	Round-trip time per client in milliseconds
ee_server_master_server_state	Gauge	Master server registration state (0–4)
ee_scenario_info{scenario,server_name,version}	Gauge	Scenario metadata; value is always 1
ee_mission_time_info{mission_time}	Gauge	Mission clock as HH:MM:SS; value is always 1
ee_player_connection{client_id,name,ship,positions}	Gauge	One row per connected player; value is always 1
ee_player_ship_count	Gauge	Number of entities with a PlayerControl component
ee_player_ship_info{ship,password}	Gauge	One row per player ship; value is always 1
ee_player_ship_hull_ratio{ship}	Gauge	Hull integrity as a fraction (0.0–1.0)
ee_player_ship_energy{ship}	Gauge	Reactor energy level
ee_player_ship_shield_ratio{ship,index}	Gauge	Per-face shield level as a fraction (0.0–1.0)
ee_server_network_bytes{component}	Gauge	Per-component network bytes (1-second window)
ee_kills_total{instigator}	Counter	Entities destroyed per instigator (session total)
ee_debug_pobject_count	Gauge	Active PObject count (debug builds only)

Master server state values: 0 = Disabled, 1 = Registering, 2 = Success, 3 = FailedToReach, 4 = FailedPortForwarding.

Per-subsystem update duration and per-component network bytes are collected only when metricsserver is set. They incur a small performance overhead.

Prometheus configuration

Add a scrape target to prometheus.yml:

scrape_configs:
  - job_name: 'emptyepsilon'
    static_configs:
      - targets: ['localhost:9100']

Replace localhost with the server's hostname or IP if EmptyEpsilon runs on a different system.

Grafana dashboard

The repository includes a pre-built dashboard at www/metrics-dashboard/grafana-dashboard.json. To import it:

1. Add Prometheus as a Grafana data source pointing to your Prometheus server.
2. In Grafana, click Dashboards > Import and upload grafana-dashboard.json.
3. Select the Prometheus data source when prompted.

The dashboard includes panels for:

• Game Overview: game speed, elapsed time, mission time, entity count, player ships, scenario name.
• Server Performance: update phase duration, server update duration, network send rate, per-component network bytes.
• Client Connections: connected clients, master server state, client ping, connected players table.
• Player Ships: hull integrity, shield status, reactor energy, hull/shield history, ship access table.
• Game Stats: kills by instigator bar chart.
• Debug (debug builds only): PObject count, network bytes by component.