From 776b12ddf159c2e2bc7da1c34da055a96213c9b1 Mon Sep 17 00:00:00 2001 From: TechnicJelle <22576047+TechnicJelle@users.noreply.github.com> Date: Thu, 17 Oct 2024 14:38:59 +0200 Subject: [PATCH 1/5] Create RAM.md --- community/RAM.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 community/RAM.md diff --git a/community/RAM.md b/community/RAM.md new file mode 100644 index 0000000..50bc524 --- /dev/null +++ b/community/RAM.md @@ -0,0 +1,50 @@ +--- +layout: page +title: BlueMap and RAM +parent: Community Guides +nav_order: 16 +--- + +# BlueMap and RAM +{: .no_toc } + +Do not be alarmed if you notice that BlueMap seems to be using a lot of RAM. +This is actually perfectly normal and should not be an actual problem. + +There are multiple things that contribute to this effect: + +### 1. Unused RAM +BlueMap is using **unused** heap-space (RAM) to cache some things +like e.g. chunk-data and resources to improve performance. +But as soon as your JVM (your server) needs this cache-space somewhere else, it can do so! +BlueMap is not hard-reserving that space, so it can't cause an OOM because of this. +*(Technically this is done using a [SoftValue-Cache]())* +After all, it is always said that unused RAM is wasted RAM. + +### 2. Garbage Collection +RAM/Heap management in your JVM is done using a Garbage Collector. +Your JVM runs this GC in intervals to free up heap-space that is no-longer used. +If you have a big heap of multiple GBs, depending on your GC-configuration, +it can wait for a long time until it decides to run the GC and free some space. +This has the effect that your RAM-Usage will keep climbing until the GC is ran. +**Or:** until you restart the server. + +So if you remove BlueMap to prove that it is using a lot of RAM, +what you actually did is you restarted the server, +resetting your heap that has risen to a higher amount +and now it looks like you have much less heap-usage, +but all it actually is just a freshly cleaned heap +which will rise again if the server runs for a while, +even if BlueMap is removed now. + +## Conclusion +If you are having OOM errors, it is usually unlikely that BlueMap is causing them. +In fact, BlueMap has been tested to run fine with only 500MB of RAM! +However, if you still believe it's BlueMap causing your OOM, +then please use the Java startup flag `-XX:+HeapDumpOnOutOfMemoryError` +to create a heap-dump the next time an OOM occurs, +and send it in the [Discord](https://bluecolo.red/map-discord) in some way. +(Heap-dumps are very big unfortunately, so you may need to use a cloud service) +We are willing to analyse that heap-dump to check what actually has caused your OOM +and if it really was BlueMap :) + From df3491dfdf0ef2a53f8e0032cc028dee2988cfc4 Mon Sep 17 00:00:00 2001 From: TechnicJelle <22576047+TechnicJelle@users.noreply.github.com> Date: Sat, 7 Dec 2024 14:07:18 +0100 Subject: [PATCH 2/5] RAM guide: Improve intro --- community/RAM.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/community/RAM.md b/community/RAM.md index 50bc524..60a6e06 100644 --- a/community/RAM.md +++ b/community/RAM.md @@ -8,7 +8,14 @@ nav_order: 16 # BlueMap and RAM {: .no_toc } -Do not be alarmed if you notice that BlueMap seems to be using a lot of RAM. +BlueMap generally does not *need* a lot of memory. +In fact, it has been proven to work with just 512MB! + +The more render-threads you have assigned (in `core.conf`), the more RAM BlueMap will need. + +However, this does not mean that BlueMap won't use more RAM if it is available. + +So do not be alarmed if you notice that BlueMap seems to be using a lot of RAM. This is actually perfectly normal and should not be an actual problem. There are multiple things that contribute to this effect: From 4d302fbb8dbd770ffb4c42b9221c2b1327aeda69 Mon Sep 17 00:00:00 2001 From: TechnicJelle <22576047+TechnicJelle@users.noreply.github.com> Date: Sat, 7 Dec 2024 14:14:09 +0100 Subject: [PATCH 3/5] RAM guide: slightly edited the intro some more --- community/RAM.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/community/RAM.md b/community/RAM.md index 60a6e06..55028c1 100644 --- a/community/RAM.md +++ b/community/RAM.md @@ -8,12 +8,13 @@ nav_order: 16 # BlueMap and RAM {: .no_toc } -BlueMap generally does not *need* a lot of memory. -In fact, it has been proven to work with just 512MB! +BlueMap generally does not *need* a lot of memory. -The more render-threads you have assigned (in `core.conf`), the more RAM BlueMap will need. +In fact, BlueMap has been proven to work with just 512MB of assigned memory! -However, this does not mean that BlueMap won't use more RAM if it is available. +The more render-threads you have assigned (in `core.conf`), the more RAM BlueMap will need, so you can lower the amount of used memory by lowering the amount of threads. + +However, this does not mean that BlueMap won't use more RAM *if it is available*. So do not be alarmed if you notice that BlueMap seems to be using a lot of RAM. This is actually perfectly normal and should not be an actual problem. From 23701c92512590774c0f46bbe59b64105491db5d Mon Sep 17 00:00:00 2001 From: TechnicJelle <22576047+TechnicJelle@users.noreply.github.com> Date: Mon, 1 Jun 2026 01:21:37 +0200 Subject: [PATCH 4/5] Added some more to the RAM page --- community/RAM.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/community/RAM.md b/community/RAM.md index 55028c1..60c117b 100644 --- a/community/RAM.md +++ b/community/RAM.md @@ -26,7 +26,7 @@ BlueMap is using **unused** heap-space (RAM) to cache some things like e.g. chunk-data and resources to improve performance. But as soon as your JVM (your server) needs this cache-space somewhere else, it can do so! BlueMap is not hard-reserving that space, so it can't cause an OOM because of this. -*(Technically this is done using a [SoftValue-Cache]())* +*(Technically this is done using a [SoftValue-Cache](https://www.baeldung.com/java-caching-caffeine#3-reference-based-eviction))* After all, it is always said that unused RAM is wasted RAM. ### 2. Garbage Collection @@ -35,7 +35,7 @@ Your JVM runs this GC in intervals to free up heap-space that is no-longer used. If you have a big heap of multiple GBs, depending on your GC-configuration, it can wait for a long time until it decides to run the GC and free some space. This has the effect that your RAM-Usage will keep climbing until the GC is ran. -**Or:** until you restart the server. +**Or:** until you restart BlueMap through `/bluemap reload` or through restarting the Minecraft server. So if you remove BlueMap to prove that it is using a lot of RAM, what you actually did is you restarted the server, @@ -48,6 +48,11 @@ even if BlueMap is removed now. ## Conclusion If you are having OOM errors, it is usually unlikely that BlueMap is causing them. In fact, BlueMap has been tested to run fine with only 500MB of RAM! + +Programs that are looking into the Java process from the outside cannot understand these concepts, so OOM-Killers often kill the server when nothing is going wrong at all! +It is highly recommend that you disable your OOM-Killer, and let Java itself crash if it's out of memory. +You will likely see that this is unlikely to actually happen. + However, if you still believe it's BlueMap causing your OOM, then please use the Java startup flag `-XX:+HeapDumpOnOutOfMemoryError` to create a heap-dump the next time an OOM occurs, From 7bbb7cbdc2e5cf310dd59594903cfa98c5b1d96b Mon Sep 17 00:00:00 2001 From: TechnicJelle <22576047+TechnicJelle@users.noreply.github.com> Date: Tue, 2 Jun 2026 16:25:12 +0200 Subject: [PATCH 5/5] Implemented feedback --- community/RAM.md | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/community/RAM.md b/community/RAM.md index 60c117b..9e47fae 100644 --- a/community/RAM.md +++ b/community/RAM.md @@ -21,21 +21,28 @@ This is actually perfectly normal and should not be an actual problem. There are multiple things that contribute to this effect: +## Concepts + ### 1. Unused RAM BlueMap is using **unused** heap-space (RAM) to cache some things like e.g. chunk-data and resources to improve performance. But as soon as your JVM (your server) needs this cache-space somewhere else, it can do so! -BlueMap is not hard-reserving that space, so it can't cause an OOM because of this. +BlueMap is not hard-reserving that space, so it can't cause an Out-Of-Memory crash because of this. *(Technically this is done using a [SoftValue-Cache](https://www.baeldung.com/java-caching-caffeine#3-reference-based-eviction))* After all, it is always said that unused RAM is wasted RAM. -### 2. Garbage Collection -RAM/Heap management in your JVM is done using a Garbage Collector. +### 2. Heap-size +The biggest factor for RAM-Usage climbing and not dropping is that the JVM increases the heap-size when it's under load. +However, later on, it is typically reluctant to _reduce_ that heap-size again. +This balance can be influenced with various settings and startup flags, which is one of the things that stuff like like [Aikar's Flags](https://docs.papermc.io/paper/aikars-flags/) do. + +### 3. Garbage Collection +Aside from the growing-but-not-shrinking heap-size, there is also the Garbage Collector (GC). Your JVM runs this GC in intervals to free up heap-space that is no-longer used. If you have a big heap of multiple GBs, depending on your GC-configuration, it can wait for a long time until it decides to run the GC and free some space. This has the effect that your RAM-Usage will keep climbing until the GC is ran. -**Or:** until you restart BlueMap through `/bluemap reload` or through restarting the Minecraft server. +**Or:** until you restart the JVM, which is what restarting the Minecraft server is. So if you remove BlueMap to prove that it is using a lot of RAM, what you actually did is you restarted the server, @@ -45,14 +52,19 @@ but all it actually is just a freshly cleaned heap which will rise again if the server runs for a while, even if BlueMap is removed now. -## Conclusion -If you are having OOM errors, it is usually unlikely that BlueMap is causing them. -In fact, BlueMap has been tested to run fine with only 500MB of RAM! +## OOM Killers +Some server panel softwares have so-called "OOM-Killer" features, +which are programs that look into the Java process from the outside and kill the process if it's using too much RAM. +However, programs that look into the Java process from the outside do not understand these concepts, +so OOM-Killers often kill the server when nothing is going wrong at all! +Java itself already keeps a close eye on the memory that it uses, and if something goes wrong, it will tell you. -Programs that are looking into the Java process from the outside cannot understand these concepts, so OOM-Killers often kill the server when nothing is going wrong at all! -It is highly recommend that you disable your OOM-Killer, and let Java itself crash if it's out of memory. +It is highly recommend that you disable your OOM-Killer, and let _Java itself_ crash if it's out of memory. You will likely see that this is unlikely to actually happen. +## Conclusion +If you are having OOM errors, it is usually unlikely that BlueMap is causing them. + However, if you still believe it's BlueMap causing your OOM, then please use the Java startup flag `-XX:+HeapDumpOnOutOfMemoryError` to create a heap-dump the next time an OOM occurs,