Pulse v0.2.1-indev.1

The first prerelease of 0.2.1. It brings three changes since 0.2.0, and two of them can touch what you built around Pulse: if your server's log is shipped somewhere, or its OTLP series feed a dashboard or an alert, read the first two sections before you upgrade.

Log lines now carry the mod's id

Both mods now write through the logger the game gives each mod, so every line they write has the mod's id right after the severity. [Notification] Pulse serving metrics on http://127.0.0.1:9464/metrics becomes [Notification] [pulse] Pulse serving metrics on http://127.0.0.1:9464/metrics, and Pulse OTLP's lines carry [pulseotlp]. The messages themselves are word for word what they were. A pattern in a log shipper or an alert rule that expects Pulse's words straight after the severity needs the tag in between. pulse_log_entries_total and pulse_engine_warnings_total count exactly what they counted before.

Pulse OTLP: one instance label per server, across restarts

0.2.0 exported a service.instance.id that the OpenTelemetry SDK generated at random on every start (unless OTEL_SERVICE_NAME was set). Prometheus, Mimir and Grafana Cloud turn it into the instance label, so every restart started a new set of series, and an alert keyed on instance saw a new server each time.

The id now lives in a new ServiceInstanceId key of pulse-otlp.json. Left blank, which is what an upgraded file has, it gets a generated GUID on the first start, written into the file, and every start after that reuses it. That first start changes the label one last time. You can also put a readable id in the key yourself, survival-eu-1 say. The first start logs Pulse OTLP wrote these keys into pulse-otlp.json: ServiceInstanceId. Everything else in the file was kept as it was., and the startup line now names the id: Pulse OTLP exporting ... as service 'vintagestory', instance '<id>'.

Check three things when you upgrade:

• Each server needs an id of its own. A pulse-otlp.json copied to a second server, or a template several servers' ModConfig folders are built from, gives all of them one id, and two servers with the same ServiceName and the same id are one server to a backend. Clear the key in the copies, or give each server its own value.
• Pulse OTLP cannot save the generated id when ModConfig is read-only. It then logs a warning naming the id and saying the next start will export a different one. Put ServiceInstanceId in the file yourself, or set OTEL_RESOURCE_ATTRIBUTES=service.instance.id=<id> in the server's environment. A ModConfig that does not survive a restart (a container without a volume for it) loses the id the same way, with no warning.
• The first start rewrites pulse-otlp.json to add the key. Like every config upgrade, the rewrite drops comments in the file, and names any key Pulse does not know in a warning before dropping it.

The environment still has the last word. A service.instance.id in OTEL_RESOURCE_ATTRIBUTES wins over the key, and it now survives on its own, where 0.2.0 replaced it on every start unless OTEL_SERVICE_NAME was set too. With OTEL_SERVICE_NAME set, nothing changes: the environment decides the whole identity, as before.

Attribution: the game's own work no longer lands in unattributed

This one only matters with attribution on. Part of the game's own entity behaviours (despawn timers, name tags, creature physics and more) was filed under unattributed, because the name a behaviour marks the tick with is often not the code its class was registered under. Pulse now reads the loaded entities to learn which mod ships each behaviour, and that time goes to game, survival or engine. On a test server with 1,691 entities, unattributed went from about 2.5% of the sampled tick to under 0.1%.

The read happens outside the profiled ticks. The first burst after attribution starts reads every loaded entity: about 3 to 4 ms with 1,700 entities, 7 ms with 4,000, 23 to 40 ms with 8,000. After that a burst costs about 0.1 ms, plus the entities that loaded in between.

Documentation

The getting-started guide now covers macOS, gives the right data path for the server.sh that ships with the server (/var/vintagestory/data/Mods), and explains how to load the bundled alert rules into Prometheus.

Upgrading

Replace pulse_0.2.0.zip in Mods/ with pulse_0.2.1-indev.1.zip, do the same for pulseotlp if you push OTLP, and restart. This is a prerelease: try it on a server you can restart. The stable 0.2.1 follows once it has run on a real one.

Full changelog: v0.2.0...v0.2.1-indev.1