Editing SimTX API v24/Packets/ServerHealthReport

{{SimTX API v24 navigation}}
{{SimTX packet v24
| name = ServerHealthReport
| id = 16
| hex = 0x10
| direction = s2c
| session = [[SimTX API v24/Control session|Control]]
| size = Variable
| permission = None
| answers = [[SimTX API v24/Packets/ServerHealthRequest|ServerHealthRequest]]
| group = control
}}
'''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 intended for status pages, dashboards and operators. Most fields are diagnostic and their exact meaning follows the server implementation; client software should treat them as informational.

== Layout ==
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>packetId</code> || <code>u8</code> || Always <code>16</code>.
|-
| <code>capturedAtEpochMillis</code> || <code>i64</code> || When the report was captured, Unix milliseconds.
|-
| <code>status</code> || <code>UTF</code> || <code>OK</code>, <code>DEGRADED</code> or <code>STOPPED</code>; <code>UNKNOWN</code> if not set.
|-
| <code>uptimeMillis</code> || <code>i64</code> || Process uptime.
|-
| <code>availableProcessors</code> || <code>i32</code> || CPU cores available.
|-
| <code>processCpuLoad</code> || <code>f32</code> || Process CPU load, 0–1.
|-
| <code>systemCpuLoad</code> || <code>f32</code> || Whole-machine CPU load, 0–1.
|-
| <code>systemLoadAverage</code> || <code>f64</code> || One-minute load average.
|-
| <code>processCpuTimeNanos</code> || <code>i64</code> || Cumulative process CPU time.
|-
| <code>heapUsedBytes</code> || <code>i64</code> || JVM heap in use.
|-
| <code>heapCommittedBytes</code> || <code>i64</code> || JVM heap committed.
|-
| <code>heapMaxBytes</code> || <code>i64</code> || JVM heap maximum.
|-
| <code>nonHeapUsedBytes</code> || <code>i64</code> || JVM non-heap memory in use.
|-
| <code>physicalMemoryUsedBytes</code> || <code>i64</code> || Machine memory in use.
|-
| <code>physicalMemoryTotalBytes</code> || <code>i64</code> || Machine memory total.
|-
| <code>openFileDescriptors</code> || <code>i64</code> || Open file descriptors.
|-
| <code>maxFileDescriptors</code> || <code>i64</code> || File descriptor limit.
|-
| <code>liveThreads</code> || <code>i32</code> || Live threads.
|-
| <code>peakThreads</code> || <code>i32</code> || Peak threads.
|-
| <code>connectedClients</code> || <code>i32</code> || Open client connections.
|-
| <code>connectedStations</code> || <code>i32</code> || Stations (receivers and transmitters).
|-
| <code>activeTransmitters</code> || <code>i32</code> || Transmitters on air.
|-
| <code>receiverGroups</code> || <code>i32</code> || Groups of receivers sharing DSP work.
|-
| <code>acceptorAlive</code> || <code>bool</code> || Whether the connection acceptor is running.
|-
| <code>worldTick</code> || <code>i64</code> || Simulation tick counter.
|-
| <code>worldTickDurationNanos</code> || <code>i64</code> || Duration of the last simulation tick.
|-
| <code>worldTickIntervalNanos</code> || <code>i64</code> || Interval between simulation ticks.
|-
| <code>simulationTimeEpochMillis</code> || <code>i64</code> || Current simulated time, Unix milliseconds.
|-
| <code>sessionTasksActive</code> || <code>i32</code> || Session worker tasks running.
|-
| <code>sessionTasksQueued</code> || <code>i32</code> || Session worker tasks waiting.
|-
| <code>receiverDspActive</code> || <code>i32</code> || Receiver DSP jobs running.
|-
| <code>receiverDspQueued</code> || <code>i32</code> || Receiver DSP jobs waiting.
|-
| <code>propagationJobsActive</code> || <code>i32</code> || Propagation jobs running.
|-
| <code>propagationJobsQueued</code> || <code>i32</code> || Propagation jobs waiting.
|-
| <code>streamedReceiverChunks</code> || <code>i64</code> || IQ blocks delivered since start.
|-
| <code>receiverOverrunChunks</code> || <code>i64</code> || IQ blocks dropped because a client queue was full.
|-
| <code>stalledTransmitterWrites</code> || <code>i32</code> || Transmitter sessions currently stalled writing.
|-
| <code>stalledReceiverGroups</code> || <code>i32</code> || Receiver groups currently stalled.
|-
| <code>transmitterCount</code> || <code>i32</code> || Number of transmitter snapshots, at most 4,096.
|-
| <code>transmitters</code> || <code>transmitterCount × TransmitterHealth</code> || See below.
|-
| <code>receiverCount</code> || <code>i32</code> || Number of receiver snapshots, at most 4,096.
|-
| <code>receivers</code> || <code>receiverCount × ReceiverHealth</code> || See below.
|}

=== TransmitterHealth ===
Durations are in nanoseconds. ''Recent'' values cover a short sliding window.

{| class="wikitable mw-collapsible"
! Field !! Type !! Notes
|-
| <code>stationUuid</code> || <code>UTF</code> || 
|-
| <code>callsign</code> || <code>UTF</code> || 
|-
| <code>address</code> || <code>UTF</code> || Empty unless the session holds <code>monitor.any</code> or <code>moderation.manage</code>.
|-
| <code>sourceType</code> || <code>UTF</code> || 
|-
| <code>frequencyHz</code> || <code>f32</code> || 
|-
| <code>modulation</code> || <code>UTF</code> || 
|-
| <code>sampleRate</code> || <code>i32</code> || 
|-
| <code>bufferCapacitySamples</code> || <code>i32</code> || 
|-
| <code>bufferRetainedSamples</code> || <code>i32</code> || 
|-
| <code>bufferSequence</code> || <code>i64</code> || 
|-
| <code>wireComponentsReceived</code> || <code>i64</code> || 
|-
| <code>processedBlocks</code> || <code>i64</code> || 
|-
| <code>totalProcessingNanos</code> || <code>i64</code> || 
|-
| <code>connectedDurationNanos</code> || <code>i64</code> || 
|-
| <code>lastProgressAgeNanos</code> || <code>i64</code> || 
|-
| <code>recentProcessingNanos</code> || <code>i64</code> || 
|-
| <code>maxProcessingNanos</code> || <code>i64</code> || 
|-
| <code>currentWriteStallNanos</code> || <code>i64</code> || 
|-
| <code>recentWriteNanos</code> || <code>i64</code> || 
|-
| <code>maxWriteNanos</code> || <code>i64</code> || 
|-
| <code>totalWriteNanos</code> || <code>i64</code> || 
|}

=== ReceiverHealth ===
{| class="wikitable mw-collapsible"
! Field !! Type !! Notes
|-
| <code>stationUuid</code> || <code>UTF</code> || 
|-
| <code>callsign</code> || <code>UTF</code> || 
|-
| <code>address</code> || <code>UTF</code> || Empty unless the session holds <code>monitor.any</code> or <code>moderation.manage</code>.
|-
| <code>centerFrequencyHz</code> || <code>f32</code> || 
|-
| <code>sampleRate</code> || <code>i32</code> || 
|-
| <code>chunkSamples</code> || <code>i32</code> || 
|-
| <code>wideband</code> || <code>bool</code> || 
|-
| <code>sharedGroupMembers</code> || <code>i32</code> || 
|-
| <code>queuedFrames</code> || <code>i32</code> || 
|-
| <code>maxQueuedFrames</code> || <code>i32</code> || 
|-
| <code>queueCapacity</code> || <code>i32</code> || 
|-
| <code>framesWritten</code> || <code>i64</code> || 
|-
| <code>framesDropped</code> || <code>i64</code> || 
|-
| <code>groupProcessedChunks</code> || <code>i64</code> || 
|-
| <code>totalGroupProcessingNanos</code> || <code>i64</code> || 
|-
| <code>totalGroupDspNanos</code> || <code>i64</code> || 
|-
| <code>connectedDurationNanos</code> || <code>i64</code> || 
|-
| <code>groupProgressAgeNanos</code> || <code>i64</code> || 
|-
| <code>recentGroupProcessingNanos</code> || <code>i64</code> || 
|-
| <code>maxGroupProcessingNanos</code> || <code>i64</code> || 
|-
| <code>recentGroupDspNanos</code> || <code>i64</code> || 
|-
| <code>maxGroupDspNanos</code> || <code>i64</code> || 
|-
| <code>currentWriteStallNanos</code> || <code>i64</code> || 
|-
| <code>recentWriteNanos</code> || <code>i64</code> || 
|-
| <code>maxWriteNanos</code> || <code>i64</code> || 
|-
| <code>totalWriteNanos</code> || <code>i64</code> || 
|}

== Usage ==
* Through the public gateway, the request goes to every server node and the gateway merges their answers into one report.
* Useful summary values for a status page: <code>status</code>, <code>connectedStations</code>, <code>activeTransmitters</code>, <code>processCpuLoad</code>, and the ratio <code>worldTickDurationNanos / worldTickIntervalNanos</code> (below 1 means the simulation keeps up with real time).
* <code>receiverOverrunChunks</code> rising quickly indicates that clients are not reading fast enough, or that the server cannot keep up.

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