SimTX API v24/Packets/ServerHealthReport

ServerHealthReport

Packet ID	16(0x10)
Direction	Server → client
Session	Control
Body size	Variable
Permission	None
Answered by
Answers	ServerHealthRequest

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

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

TransmitterHealth

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

Field	Type	Notes
stationUuid	UTF
callsign	UTF
address	UTF	Empty unless the session holds monitor.any or moderation.manage.
sourceType	UTF
frequencyHz	f32
modulation	UTF
sampleRate	i32
bufferCapacitySamples	i32
bufferRetainedSamples	i32
bufferSequence	i64
wireComponentsReceived	i64
processedBlocks	i64
totalProcessingNanos	i64
connectedDurationNanos	i64
lastProgressAgeNanos	i64
recentProcessingNanos	i64
maxProcessingNanos	i64
currentWriteStallNanos	i64
recentWriteNanos	i64
maxWriteNanos	i64
totalWriteNanos	i64

ReceiverHealth

Field	Type	Notes
stationUuid	UTF
callsign	UTF
address	UTF	Empty unless the session holds monitor.any or moderation.manage.
centerFrequencyHz	f32
sampleRate	i32
chunkSamples	i32
wideband	bool
sharedGroupMembers	i32
queuedFrames	i32
maxQueuedFrames	i32
queueCapacity	i32
framesWritten	i64
framesDropped	i64
groupProcessedChunks	i64
totalGroupProcessingNanos	i64
totalGroupDspNanos	i64
connectedDurationNanos	i64
groupProgressAgeNanos	i64
recentGroupProcessingNanos	i64
maxGroupProcessingNanos	i64
recentGroupDspNanos	i64
maxGroupDspNanos	i64
currentWriteStallNanos	i64
recentWriteNanos	i64
maxWriteNanos	i64
totalWriteNanos	i64

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: status, connectedStations, activeTransmitters, processCpuLoad, and the ratio worldTickDurationNanos / worldTickIntervalNanos (below 1 means the simulation keeps up with real time).
• receiverOverrunChunks rising quickly indicates that clients are not reading fast enough, or that the server cannot keep up.