SimTX API v24/Packets/ServerHealthReport: Difference between revisions

Latest revision as of 16:17, 24 October 2026

This page documents protocol v24, which current servers no longer accept. See SimTX API for v25.

v24 overviewQuick startAccount serviceHandshakeAll packetsData typesLimits and errorsCurrent reference (v25)

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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.

SimTX API v24 reference (protocol v24, archived)
Start	OverviewQuick startData typesLimits and errorsPacket list
Account service	OverviewDevice loginServer directoryGame ticketsPermissionsPublic endpoints
Game protocol	Connection and handshakeReceiver sessionTransmitter sessionControl sessionCatalogModeration
Handshake	HandshakeHandshakeResult
Receiver	ReceiverSessionRequestReceiverRetuneForwardedClientAddressIqStreamDescriptorIqBlockTimedIqBlock
Transmitter	TransmitterSessionRequestSampleBlockTxModeInfoTxUpdateTxQueueTxAcceptTxRejectTxKickTxTelemetryTxUpdateAck
Control	ControlAckBannerListStationsStationListServerHealthRequestServerHealthReportCoverageMapRequestCoverageMapResponseWeatherMapRequestWeatherMapResponseStartMonitorStopMonitorMonitorBlockMonitorEnd
Catalog	CatalogListRequestCatalogListCatalogFetchCatalogEntryCatalogUploadCatalogUploadResultCatalogDeleteCatalogDeleteResult
Moderation	KickRequestKickResultIpModerationRequestIpModerationResultBroadcastBannerModerationErrorStationImpactList
Current	Protocol v25 reference

@@ Line 1: / Line 1: @@
-{{SimTX API navigation}}
+{{SimTX API v24 navigation}}
-{{SimTX packet
+{{SimTX packet v24
 | name = ServerHealthReport
 | id = 16
 | hex = 0x10
 | direction = s2c
-| session = [[SimTX API/Control session|Control]]
+| session = [[SimTX API v24/Control session|Control]]
 | size = Variable
 | permission = None
-| answers = [[SimTX API/Packets/ServerHealthRequest|ServerHealthRequest]]
+| answers = [[SimTX API v24/Packets/ServerHealthRequest|ServerHealthRequest]]
 | group = control
 }}
@@ Line 213: / Line 213: @@
 * <code>receiverOverrunChunks</code> rising quickly indicates that clients are not reading fast enough, or that the server cannot keep up.
-{{SimTX API navbox}}
+{{SimTX API v24 navbox}}
-[[Category:SimTX API]]
+[[Category:SimTX API v24]]