Z-Pulse — the pulse of your server: measured lag instead of "it feels laggy"
Demo
Z-Pulse times every server tick and turns it into facts: average updates per second, worst tick, number of stalls by threshold, and a daily plain-text report that says hour by hour when the server paused and for how long. With the investigation tools on (off by default), it also names what was probably blocking it.
It is built to cost (almost) nothing: a monitor that slows the server down would measure its own presence. On a normal tick it only does arithmetic; the rest happens once per measurement window, and files are written off the game thread. If an ARK update breaks one of its hooks, Z-Pulse says so in its log and stays loaded.
Install
Drop the
Z-Pulse folder into ShooterGame/Binaries/Win64/ArkApi/Plugins/. Requires AsaApi 2.03+. Loads at server start.What it writes (in its own folder)
pulse.json— the last measurement window (Window.Seconds, 30 s by default): ticks, average, worst, stalls.pulse-histo.jsonl— every window, one line each (rotated), for graphs.pulse-report-<date>.txt— the daily report, readable by anyone: summary, hour-by-hour table (TPS, players, pauses of 1 s / 3 s, worst stall), the longest pauses, with the engine stage and the probable cause when the investigation tools are on. Rewritten every 10 minutes, 14 days kept. Language: EN, FR, DE or ES.- Optional diagnostics, only when you turn them on:
probe.jsonl(freeze probe), stack samples, creature census, slow network receptions.
Optional diagnostics (all OFF by default)
Turn them on while you are hunting a lag problem:
WatchLoading,WatchEngineStages,WatchRPC(+RpcThresholdMs) — name the blocked engine stage and the slow network call behind a pause. These hooks are placed when the server starts: restart it after enabling them.CaptureContext— context of a slow cryo capture.ActorCensus(+CensusEverySeconds) — which creatures are awake and keep the server busy.TraceTeleports— teleports around a pause.StackSampler(+SamplerHz,PauseSamplerHz,PauseSamplerAfterMs,MaxFrames) — samples the game thread to show the share of time spent in each plugin.Probe.Enabled— the freeze probe: times stasis wake-ups, player arrivals, saves and slow Blueprint calls, and names the slow ones (class, mod, owner, position). File capped atProbe.MaxFileMB.
RCON commands
ZPulse.Status— current window and last complete window, settings.ZPulse.Reload— re-reads most settings (window length, thresholds, report language); theWatch*switches need a server restart.ZPulse.Census— counts dinos and structures, awake or in stasis, with the top awake classes.ZPulse.Probe— state of the freeze probe and of its hooks.ZPulse.WakeAt <x> <y> <z> [radius]— wakes what is in stasis around a point, like a player arriving, to reproduce a freeze on demand. A test tool: use it on a test server first.
Configure (config.json)
General.Enabled—falseputs the plugin to sleep without unloading it.General.Language— language of the daily report. The report texts are added underTextsat first load: translate or adjust them there (keep the%s/%dmarkers in the same order).General.DailyReport— the daily text report (on by default).General.DetailThresholdMs/MaxDetailsPerWindow— ticks slower than this are listed in each window (default 500 ms, at most 40).Window.Seconds— length of a measurement window (10 to 3600).
Compatibility
Built and tested against AsaApi 2.03 (ARK: Survival Ascended dedicated server, Windows).
External connections and data
- No network connection. The plugin opens no connection of its own and sends nothing anywhere: no web request, no telemetry, no licence check, no update check.
WatchRPCtimes the game's own traffic from players; it opens nothing. - Files written, all in its own folder. Always:
pulse.json,pulse-histo.jsonl(rotated),pulse-report-<date>.txt(14 days kept) withpulse-report-state.json, andpulse-battement.json, a heartbeat refreshed every few seconds by a background thread (time of the last tick, process id, committed memory), so that an external tool can tell a frozen server from a busy one. Only when you turn the matching tool on:probe.jsonl(slow wake-ups: class, mod, tribe id, owner name, position, name of the nearest player),pulse-piles.jsonl(stack samples: module names and offsets),pulse-recensement.jsonl(creature counts),pulse-receptions.jsonl(slow network receptions, with the sending player's EOS id and name).config.jsongets the report texts added at first load. - Files read: its own
config.json, and AsaApi's own offset cache (each game function is looked up there before a hook is placed). It also reads the server process's own memory counters. - The stack sampler, explained (
StackSampler, off by default). To show which plugin or engine function holds the game thread during a stall, a background thread of Z-Pulse briefly pauses the server's own game thread (SuspendThread), reads its registers (GetThreadContext), copies the top of its stack (256 KB at most) and resumes it (ResumeThread): 10 times per second by default, 50 during a stall. The copy is decoded afterwards, while the game runs, against the modules loaded in the server process (EnumProcessModules) and their unwind tables. Only module names and offsets are kept. For safety it also usesOpenThreadandNtQueryInformationThread(to locate the game thread's stack),LdrRegisterDllNotification(no sample for 5 minutes after any DLL loads or unloads, because plugins place or remove hooks then), a memory-locked buffer (VirtualLock, with the process's working set raised to match) so that the copy never waits on the disk, and a watchdog thread that resumes the game thread if a pause ever lasts over one second, then switches the sampler off. Debuggers and profilers use the same calls, so a security tool may flag them: here they only ever target the server's own game thread, inside its own process. - When
WatchEngineStages,WatchRPCor the probe's Blueprint detail is on, Z-Pulse pins itself in memory (GetModuleHandleEx): a hot reload cannot unload it, and an update waits for a server restart. - No registry access, no external program started, no other data collected.
Dependencies and limitations
- No required dependency. Z-ARK, if you use it, reads Z-Pulse's files to draw graphs; the daily text report works without it.
- Always on: one hook on the game-mode tick (
AShooterGameMode.Tick). The investigation tools add their own hooks, placed at server start: restart after switching aWatch*setting. ZPulse.WakeAtchanges the game state (it wakes what is in stasis around a point): try it on a test server first.- Known limit of the stack sampler: if another plugin places or removes a hook at the exact moment of a sample (a window of a few microseconds, outside the 5-minute quiet periods), the server could freeze. Unlikely, not impossible: that is why the sampler is off by default and meant for short investigations.
Updates
Z-ARK (server manager, https://z-ark.fr/en/) checks for new versions of this plugin and installs them from its dashboard; it also draws Z-Pulse's measurements as graphs.
Without Z-ARK: click Watch at the top of this page to be notified of every new version; what changed is listed in the Updates tab. To update, stop the server, replace the plugin's .dll and PluginInfo.json, keep your config.json, then start the server again.
Built with AI, knowingly
This plugin was written with an artificial intelligence, and we would rather say it plainly. It is not code thrown together at random: behind it is someone from the trade (software development, server operations, community management) who decides every feature, reviews it and puts it to the test on a real cluster, with real players, before it reaches you. The same goes for the ZMenu client mod. Bugs reported in the Discussion tab get fixed.
