Migration Guide for `v0.16.x`
Migration guide for self-hosted Measure v0.16.x. Drains queued sessions before moving to the new message queue version.
Use this guide only when you are on less than v0.16.0 and upgrading to v0.16.x.
Steps mentioned in this document will cause downtime.
Follow these steps when upgrading to 0.16.x. v0.16.x upgrades the message queue to a version that cannot read the old queue data. Queued sessions must be processed before the upgrade, otherwise they are lost. There is some downtime involved. During the downtime SDKs would receive a 503 Service Unavailable when sending sessions. Once the upgrade is complete, ingestion should resume normally. SDKs will retry sending unsent sessions automatically.
1. Fetch the upgrade
Measure keeps running during this step.
Visit Releases page to capture the latest tag matching the v[MAJOR].[MINOR].[PATCH] format. For example, v0.16.0.
SSH into the VM where Measure is hosted.
cd ~/measuregit reset --hard # only applies if you have local modificationsgit fetch --tags# replace <git-tag> with the chosen tag. example: v0.16.0
git checkout <git-tag>2. Drain the queue
This stops accepting new sessions & waits for queued sessions to be processed. Measure services other than ingestion keep running. The script exits successfully once the queue is empty.
cd ~/measure/self-hostsudo ./migrations/v0.16.x-drain-iggy.shIf the queue does not empty within 10 minutes, the script fails. Make sure all services are healthy & run it again. To wait longer, set DRAIN_TIMEOUT in seconds.
sudo DRAIN_TIMEOUT=1800 ./migrations/v0.16.x-drain-iggy.sh3. Shutdown all Measure services
sudo docker compose -f compose.yml -f compose.prod.yml --profile migrate down --remove-orphans4. Start Measure services
sudo ./install.sh5. Remove the old queue data
Once Measure is healthy & ingesting sessions, remove the old queue data.
sudo docker volume rm measure_iggy-dataRollback
Until you remove the old queue data, you can go back to the previous version. Checkout the previous tag & run sudo ./install.sh again.
Sessions received after the upgrade are not available in the previous version's queue.
Think this page can be better?
Open an issue