Editing SimTX API/Packets/ServerHealthReport

{{SimTX API navigation}}
{{SimTX packet
| name = ServerHealthReport
| frame = ServerFrame
| field = 34
| member = health
| direction = s2c
| session = [[SimTX API/Control session|Control]]
| roles = <code>ROLE_CONTROL</code>.
| permission = None
| answers = [[SimTX API/Packets/ServerHealthRequest|ServerHealthRequest]]
| group = control
| file = 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 ==
<syntaxhighlight lang="protobuf">
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;
}
</syntaxhighlight>

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

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

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

== Usage ==
* Useful summary values for a status page: <code>status</code>, <code>connected_stations</code>, <code>active_transmitters</code>, <code>process_cpu_load</code>, and the ratio <code>world_tick_duration_nanos / world_tick_interval_nanos</code> (below 1 means the simulation keeps up with real time).
* <code>receiver_overrun_chunks</code> 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.
* <code>session_id</code> in the per-session entries is the same 16-byte id as in [[SimTX API/Packets/SessionStatus|SessionStatus]] and [[SimTX API/Packets/StationList|StationList]].

== See also ==
* [[SimTX API/Packets/ServerHealthRequest|ServerHealthRequest]]

{{SimTX API navbox}}
[[Category:SimTX API]]