SimTX API/Packets/ServerHealthReport

ServerHealthReport

Frame	ServerFrame, field 34
Member	health
Direction	Server → client
Session	Control
Roles	ROLE_CONTROL.
Permission	None
Answered by
Answers	ServerHealthRequest
Defined in	control.proto

ServerHealthReport describes the load and internal state of a game server: CPU and memory, simulation timing, worker queues, and per-session statistics for every transmitter and receiver. It is meant for status pages, dashboards and operators. Most fields are diagnostic and follow the server implementation; treat them as informational.

Definition

message ServerHealthReport {
  int64 request_id = 1;
  int64 captured_at_ms = 2;
  string status = 3;
  int64 uptime_ms = 4;
  int32 available_processors = 5;
  float process_cpu_load = 6;
  float system_cpu_load = 7;
  double system_load_average = 8;
  int64 process_cpu_time_nanos = 9;
  int64 heap_used_bytes = 10;
  int64 heap_committed_bytes = 11;
  int64 heap_max_bytes = 12;
  int64 non_heap_used_bytes = 13;
  int64 physical_memory_used_bytes = 14;
  int64 physical_memory_total_bytes = 15;
  int64 open_file_descriptors = 16;
  int64 max_file_descriptors = 17;
  int32 live_threads = 18;
  int32 peak_threads = 19;
  int32 connected_clients = 20;
  int32 connected_stations = 21;
  int32 active_transmitters = 22;
  int32 receiver_groups = 23;
  bool acceptor_alive = 24;
  int64 world_tick = 25;
  int64 world_tick_duration_nanos = 26;
  int64 world_tick_interval_nanos = 27;
  int64 simulation_time_ms = 28;
  int32 session_tasks_active = 29;
  int32 session_tasks_queued = 30;
  int32 receiver_dsp_active = 31;
  int32 receiver_dsp_queued = 32;
  int32 propagation_jobs_active = 33;
  int32 propagation_jobs_queued = 34;
  int64 streamed_receiver_chunks = 35;
  int64 receiver_overrun_chunks = 36;
  int32 stalled_transmitter_writes = 37;
  int32 stalled_receiver_groups = 38;
  repeated TransmitterHealth transmitters = 39;
  repeated ReceiverHealth receivers = 40;
}

Fields

#	Field	Type	Description
1	request_id	int64	The request this answers.
2	captured_at_ms	int64	When the report was captured, Unix ms.
3	status	string	OK, DEGRADED or STOPPED; UNKNOWN if not set.
4	uptime_ms	int64	Process uptime, ms.
5	available_processors	int32	CPU cores available.
6	process_cpu_load	float	Process CPU load, 0 to 1.
7	system_cpu_load	float	Whole-machine CPU load, 0 to 1.
8	system_load_average	double	One-minute load average.
9	process_cpu_time_nanos	int64	Cumulative process CPU time.
10	heap_used_bytes	int64	JVM heap in use.
11	heap_committed_bytes	int64	JVM heap committed.
12	heap_max_bytes	int64	JVM heap maximum.
13	non_heap_used_bytes	int64	JVM non-heap memory in use.
14	physical_memory_used_bytes	int64	Machine memory in use.
15	physical_memory_total_bytes	int64	Machine memory total.
16	open_file_descriptors	int64	Open file descriptors.
17	max_file_descriptors	int64	File descriptor limit.
18	live_threads	int32	Live threads.
19	peak_threads	int32	Peak threads.
20	connected_clients	int32	Open client connections.
21	connected_stations	int32	Sessions (receivers and transmitters).
22	active_transmitters	int32	Transmitters on air.
23	receiver_groups	int32	Groups of receivers sharing DSP work.
24	acceptor_alive	bool	Whether the connection acceptor is running.
25	world_tick	int64	Simulation tick counter.
26	world_tick_duration_nanos	int64	Duration of the last simulation tick.
27	world_tick_interval_nanos	int64	Interval between simulation ticks.
28	simulation_time_ms	int64	Current simulated time, Unix ms.
29	session_tasks_active	int32	Session worker tasks running.
30	session_tasks_queued	int32	Session worker tasks waiting.
31	receiver_dsp_active	int32	Receiver DSP jobs running.
32	receiver_dsp_queued	int32	Receiver DSP jobs waiting.
33	propagation_jobs_active	int32	Propagation jobs running.
34	propagation_jobs_queued	int32	Propagation jobs waiting.
35	streamed_receiver_chunks	int64	IQ blocks delivered since start.
36	receiver_overrun_chunks	int64	IQ blocks dropped because a client queue was full.
37	stalled_transmitter_writes	int32	Transmitter sessions currently stalled writing.
38	stalled_receiver_groups	int32	Receiver groups currently stalled.
39	transmitters	repeated TransmitterHealth	One TransmitterHealth per live transmitter, at most 4,096.
40	receivers	repeated ReceiverHealth	One ReceiverHealth per live receiver, at most 4,096.

TransmitterHealth

message TransmitterHealth {
  bytes session_id = 1;
  string callsign = 2;
  string address = 3;
  string source_type = 4;      // string enum (common.proto)
  double frequency_hz = 5;
  string modulation = 6;       // string enum (common.proto)
  int32 sample_rate = 7;
  int32 buffer_capacity_samples = 8;
  int32 buffer_retained_samples = 9;
  int64 buffer_sequence = 10;
  int64 wire_components_received = 11;
  int64 processed_blocks = 12;
  int64 total_processing_nanos = 13;
  int64 connected_duration_nanos = 14;
  int64 last_progress_age_nanos = 15;
  int64 recent_processing_nanos = 16;
  int64 max_processing_nanos = 17;
  int64 current_write_stall_nanos = 18;
  int64 recent_write_nanos = 19;
  int64 max_write_nanos = 20;
  int64 total_write_nanos = 21;
}

#	Field	Type	Description
1	session_id	bytes	16-byte transmission id.
2	callsign	string	Callsign.
3	address	string	Client address. Empty unless the session holds monitor.any or moderation.manage.
4	source_type	string	Source type name.
5	frequency_hz	double	Carrier frequency, Hz.
6	modulation	string	Modulation name.
7	sample_rate	int32	Declared input sample rate.
8	buffer_capacity_samples	int32	Playout buffer capacity, samples.
9	buffer_retained_samples	int32	Samples held in the playout buffer.
10	buffer_sequence	int64	Write position of the playout buffer.
11	wire_components_received	int64	Sample values received from the client.
12	processed_blocks	int64	Blocks processed.
13	total_processing_nanos	int64	Total processing time.
14	connected_duration_nanos	int64	Time since the session started.
15	last_progress_age_nanos	int64	Time since the session last made progress.
16	recent_processing_nanos	int64	Processing time in the recent window.
17	max_processing_nanos	int64	Longest processing step.
18	current_write_stall_nanos	int64	Duration of the current stalled write, 0 if none.
19	recent_write_nanos	int64	Write time in the recent window.
20	max_write_nanos	int64	Longest write.
21	total_write_nanos	int64	Total write time.

ReceiverHealth

message ReceiverHealth {
  bytes session_id = 1;
  string callsign = 2;
  string address = 3;
  double center_frequency_hz = 4;
  int32 sample_rate = 5;
  int32 chunk_samples = 6;
  bool wideband = 7;
  int32 shared_group_members = 8;
  int32 queued_frames = 9;
  int32 max_queued_frames = 10;
  int32 queue_capacity = 11;
  int64 frames_written = 12;
  int64 frames_dropped = 13;
  int64 group_processed_chunks = 14;
  int64 total_group_processing_nanos = 15;
  int64 total_group_dsp_nanos = 16;
  int64 connected_duration_nanos = 17;
  int64 group_progress_age_nanos = 18;
  int64 recent_group_processing_nanos = 19;
  int64 max_group_processing_nanos = 20;
  int64 recent_group_dsp_nanos = 21;
  int64 max_group_dsp_nanos = 22;
  int64 current_write_stall_nanos = 23;
  int64 recent_write_nanos = 24;
  int64 max_write_nanos = 25;
  int64 total_write_nanos = 26;
}

#	Field	Type	Description
1	session_id	bytes	16-byte session id.
2	callsign	string	Callsign.
3	address	string	Client address. Empty unless the session holds monitor.any or moderation.manage.
4	center_frequency_hz	double	Centre frequency, Hz.
5	sample_rate	int32	Negotiated sample rate.
6	chunk_samples	int32	Negotiated block size.
7	wideband	bool	True for a wideband receiver.
8	shared_group_members	int32	Receivers sharing this receiver's DSP group.
9	queued_frames	int32	Frames waiting in the output queue.
10	max_queued_frames	int32	Highest queue level seen.
11	queue_capacity	int32	Output queue capacity.
12	frames_written	int64	Frames written to the client.
13	frames_dropped	int64	Frames dropped because the queue was full.
14	group_processed_chunks	int64	Blocks processed by the DSP group.
15	total_group_processing_nanos	int64	Total group processing time.
16	total_group_dsp_nanos	int64	Total group DSP time.
17	connected_duration_nanos	int64	Time since the session started.
18	group_progress_age_nanos	int64	Time since the group last made progress.
19	recent_group_processing_nanos	int64	Group processing time in the recent window.
20	max_group_processing_nanos	int64	Longest group processing step.
21	recent_group_dsp_nanos	int64	Group DSP time in the recent window.
22	max_group_dsp_nanos	int64	Longest group DSP step.
23	current_write_stall_nanos	int64	Duration of the current stalled write, 0 if none.
24	recent_write_nanos	int64	Write time in the recent window.
25	max_write_nanos	int64	Longest write.
26	total_write_nanos	int64	Total write time.

Usage

• Useful summary values for a status page: status, connected_stations, active_transmitters, process_cpu_load, and the ratio world_tick_duration_nanos / world_tick_interval_nanos (below 1 means the simulation keeps up with real time).
• receiver_overrun_chunks rising quickly means that clients are not reading fast enough, or that the server cannot keep up.
• Durations are in nanoseconds. Recent values cover a short sliding window.
• session_id in the per-session entries is the same 16-byte id as in SessionStatus and StationList.

See also

• ServerHealthRequest