From 00a42d3f18e005994ac797d0fe85d7b2d25c7923 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Tue, 5 May 2026 17:56:40 +0200 Subject: [PATCH 01/10] fix(docs): correct event name from `app_deploy` to `app_deployed` --- .../platform/app/troubleshooting/2000-01-01-runtime-issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md b/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md index 031820d95..628f8c575 100644 --- a/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md +++ b/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md @@ -112,5 +112,5 @@ when a Timeout Error occurs). You can modify this behavior by tweaking your [Notifier's configuration]({% post_url platform/app/2000-01-01-notifiers %}). -The `app_crashed`, `app_crashed_repeated` and the `app_deploy` events can be +The `app_crashed`, `app_crashed_repeated` and the `app_deployed` events can be particularly worth considering. From 7280e1a9dd7d39be93ed5416ad2c85f0a6b82f80 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Tue, 5 May 2026 18:36:47 +0200 Subject: [PATCH 02/10] Table is converted to markdown and various changes --- .../internals/2000-01-01-container-sizes.md | 89 ++++++------------- 1 file changed, 26 insertions(+), 63 deletions(-) diff --git a/src/_posts/platform/internals/2000-01-01-container-sizes.md b/src/_posts/platform/internals/2000-01-01-container-sizes.md index f92bbd290..1fb693e5e 100644 --- a/src/_posts/platform/internals/2000-01-01-container-sizes.md +++ b/src/_posts/platform/internals/2000-01-01-container-sizes.md @@ -1,83 +1,46 @@ --- title: Container Sizes -modified_at: 2015-12-02 00:00:00 -tags: internals containers sizes +modified_at: 2026-05-05 00:00:00 +tags: containers sizes index: 2 --- ## Comparative Table -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameMemoryCPU PriorityPID LimitPrice
S - Small256MBLow1280.01€/h
M - Medium (Default)512MBStandard2560.02€/h
L - Large1GBStandard5120.04€/h
XL - eXtra Large2GBHigh10240.08€/h
2XL - eXtra eXtra Large4GBHigh20480.16€/h
+
+| Name | Memory | CPU Priority | PID Limit[^pid-limit] | +| -------------------------- | ------- | ------------ | --------- | +| S - Small | 256 MB | Low | 128 | +| M - Medium (Default) | 512 MB | Standard | 256 | +| L - Large | 1 GB | Standard | 512 | +| XL - eXtra Large | 2 GB | High | 1024 | +| 2XL - eXtra eXtra Large | 4 GB | High | 2048 | +{: .table }
-Bigger container sizes are available upon request on the support. -As a note, each new process requires a PID. And inside each process, each thread needs one too. +Prices are available on the [Scalingo pricing page](https://scalingo.com/pricing). +Bigger container sizes are available upon request on the support. -## Availability of the Sizes - -Our 30 days free trial only gives you access to small and medium containers, if you want -to use another kind of size, please [fill your billing profile and payment -method](https://dashboard.scalingo.com/billing). +{% note %} +Limits apply when using Scalingo under the free trial. For more information, +see [what you can do under the free trial][free-trial-limits]. +{% endnote %} ## Container Limits Containers have various limits depending on their size. Here is a comprehensive list: -- RAM: cf. above-mentioned table -- Swap: twice the amount of RAM. -- CPU access: all containers have access to all CPU cores. But higher priority +- **Memory**: see the comparative table above. +- **Swap**: twice the amount of RAM. +- **CPU**: all containers have access to all CPU cores. But higher priority means twice as much priority compared to standard priority. For example, consider three containers, one has a high priority and two others have a standard priority. When processes in all three containers attempt to use 100% of CPU, the first container would receive 50% of the total CPU time and the two others would receive 25%. -- PID limits: from 128 (S) to 2048 (2XL). -- Ulimit nofile: 1048576. Maximum number of files an application can open. +- **PID limit**: see the comparative table above. +- **Open file limit** (`nofile`): 1,048,576. This is the maximum number of files an application can open. + +[^pid-limit]: Each new process requires a PID. + +[free-trial-limits]: {% post_url platform/getting-started/2000-01-01-free-trial %}#what-can-i-do-under-the-free-trial From 650382aceef24d339da10d6059c2f6ec7e80a219 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Tue, 5 May 2026 18:37:37 +0200 Subject: [PATCH 03/10] Update the page position --- src/_posts/platform/app/2000-01-01-filesystem.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/_posts/platform/app/2000-01-01-filesystem.md b/src/_posts/platform/app/2000-01-01-filesystem.md index e4981abda..38adb0e94 100644 --- a/src/_posts/platform/app/2000-01-01-filesystem.md +++ b/src/_posts/platform/app/2000-01-01-filesystem.md @@ -2,7 +2,7 @@ title: File System and File Storage modified_at: 2023-07-27 00:00:00 tags: app runtime file system disk storage -index: 1 +index: 2 --- ## Introduction From a70546372589f4e42da12cb8be6456880f4d3a99 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Tue, 5 May 2026 18:37:55 +0200 Subject: [PATCH 04/10] Precisions about OOM Crash --- .../platform/app/troubleshooting/2000-01-01-runtime-issues.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md b/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md index 628f8c575..a9baba245 100644 --- a/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md +++ b/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md @@ -25,7 +25,8 @@ The most common causes are: - Configuration issues - Bugs in your application code - Uncaught exception in your code (especially with non-compiled languages) -- Insufficient resources +- Insufficient resources, such as an Out of Memory (OOM) crash when the + application consumes all its allocated memory - Temporary error/unavailability of an external resource A Runtime Error can have several consequences, depending on the severity of the From 4211433836cc54e23a15cb499ca8ca51dad4c352 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Tue, 5 May 2026 18:38:30 +0200 Subject: [PATCH 05/10] add Application Resources documentation and move the OOM section from Metrics to this new page --- .../app/2000-01-01-application-resources.md | 68 +++++++++++++++++++ src/_posts/platform/app/2000-01-01-metrics.md | 51 ++++---------- 2 files changed, 81 insertions(+), 38 deletions(-) create mode 100644 src/_posts/platform/app/2000-01-01-application-resources.md diff --git a/src/_posts/platform/app/2000-01-01-application-resources.md b/src/_posts/platform/app/2000-01-01-application-resources.md new file mode 100644 index 000000000..694bccaed --- /dev/null +++ b/src/_posts/platform/app/2000-01-01-application-resources.md @@ -0,0 +1,68 @@ +--- +title: Application Resources +nav: Resources +modified_at: 2026-05-05 00:00:00 +tags: app resources cpu memory ram swap storage oom +index: 1 +--- + +Application resources define the CPU, memory, swap, and storage available to +each container running your application. + +## Container Sizing + + + +For the full list of available container sizes and their limits, see +[Container Sizes][container-sizes]. + + +## CPU + +## Memory + +### RAM + +### Swap + +### Out of Memory Crashes + +When an application consumes all its allocated memory (RAM + swap), the system +applies a protection mechanism called the **OOM Killer** (Out of Memory Killer). + +#### Sequence of events + +1. The application progressively uses all available RAM +2. The system starts using swap space +3. When memory and swap reach 100% usage, the OOM Killer intervenes +4. The application is immediately terminated by the system + +#### Observable consequences + +* **Abrupt termination:** The application stops without a graceful shutdown process +* **Automatic restart:** The container restarts according to its configuration +* **Restart event:** A "Restart" event appears in the metrics timeline +* **Data loss:** All non-persisted data in memory is lost + +#### Prevention and monitoring + +To avoid this scenario: + +* Regularly monitor memory charts in the [Metrics tab][metrics] +* Set up [alerts][alerts] before reaching memory limits +* Analyze usage spikes in correlation with deployment events +* Consider upgrading to a larger [container size][container-sizes] if needed + +**Note:** The OOM Killer is a system protection mechanism. If your application regularly experiences OOM events, it typically indicates a need for code optimization or increased allocated resources. + +## Storage + +### Ephemeral Filesystem + +## Monitoring Resource Usage + +## Preventing Resource Exhaustion + +[alerts]: {% post_url platform/app/2000-01-01-alerts %} +[container-sizes]: {% post_url platform/internals/2000-01-01-container-sizes %} +[metrics]: {% post_url platform/app/2000-01-01-metrics %} diff --git a/src/_posts/platform/app/2000-01-01-metrics.md b/src/_posts/platform/app/2000-01-01-metrics.md index 882b91079..f172c69a8 100644 --- a/src/_posts/platform/app/2000-01-01-metrics.md +++ b/src/_posts/platform/app/2000-01-01-metrics.md @@ -1,7 +1,7 @@ --- title: Application Metrics nav: Metrics -modified_at: 2026-01-02 12:00:00 +modified_at: 2026-05-05 00:00:00 tags: app metrics index: 35 --- @@ -23,17 +23,20 @@ The application chart displays global data that are not container specific: events and routing metrics. The **Requests per minute** chart show the number of requests the application -receives per minute, the famous **RPM**. The number of server error responses generated by the application (HTTP responses in the 500 range) is displayed on the same chart as red bars. +receives per minute, the famous **RPM**. The number of server error responses +generated by the application (HTTP responses in the 500 range) is displayed on +the same chart as red bars. **Note**: 504 and 503 errors can be generated by our reverse proxy. More information is available in the [routing documentation][routing-errors]. On top of this chart, all the events that happened during the -viewing period are displayed. This can help you link the application behaviour with events -that happened on the platform, e.g. spot a deployment that contains a memory -leak or follow your application behaviour after a scale operation. +viewing period are displayed. This can help you link the application behaviour +with events that happened on the platform, e.g. spot a deployment that contains +a memory leak or follow your application behaviour after a scale operation. -A lot of events are available on the application timeline but only a few relevant are displayed on the metrics view: +A lot of events are available on the application timeline but only a few +relevant are displayed on the metrics view: - Restart event - Deploy event @@ -61,10 +64,11 @@ The container charts use the container types defined in your [Procfile]({% post_url platform/app/2000-01-01-procfile %}). For each container type, two charts are shown. The first one shows the **CPU -usage** and the second one the **memory** and **swap** usage of this type of -container. +usage** and the second one the **memory usage** and **swap usage** usage of this +type of container. -The CPU chart may exceed 100% if the application uses more than one core of the CPU. +The CPU chart may exceed 100% if the application uses more than one core of the +CPU. For the memory chart, the memory (in blue) and swap usage (in red) are stacked. That way the total memory usage of the application can be @@ -94,35 +98,6 @@ platform/internals/2000-01-01-container-sizes %}). If the application has more than one container of a specific type, these charts show the mean CPU usage / memory consumption of all containers of the same type. -## Behavior when memory and swap are fully consumed - -When an application consumes all its allocated memory (RAM + swap), the system applies a protection mechanism called the **OOM Killer** (Out of Memory Killer). - -### Sequence of events - -1. The application progressively uses all available RAM -2. The system starts using swap space (visible in red on the memory chart) -3. When memory and swap reach 100% usage, the OOM Killer intervenes -4. The application is immediately terminated by the system - -### Observable consequences - -* **Abrupt termination:** The application stops without a graceful shutdown process -* **Automatic restart:** The container restarts according its configuration -* **Restart event:** A "Restart" event appears in the metrics timeline -* **Data loss:** All non-persisted data in memory is lost - -### Prevention and monitoring - -To avoid this scenario: - -* Regularly monitor memory charts in the Metrics tab -* Set up alerts before reaching memory limits -* Analyse usage spikes in correlation with deployment events -* Consider upgrading to a larger [container size](/platform/internals/container-sizes) if needed - -**Note:** The OOM Killer is a system protection mechanism. If your application regularly experiences OOM events, it typically indicates a need for code optimization or increased allocated resources. - ## Detailed View If the application has more than one container of a type defined in its From a8f73bb1d3cbceccf35af5bbe636275122282a74 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Mon, 11 May 2026 17:05:29 +0200 Subject: [PATCH 06/10] docs(app): move OOM guidance to runtime issues --- .../app/2000-01-01-application-resources.md | 68 ------------------- .../2000-01-01-runtime-issues.md | 38 ++++++++++- 2 files changed, 36 insertions(+), 70 deletions(-) delete mode 100644 src/_posts/platform/app/2000-01-01-application-resources.md diff --git a/src/_posts/platform/app/2000-01-01-application-resources.md b/src/_posts/platform/app/2000-01-01-application-resources.md deleted file mode 100644 index 694bccaed..000000000 --- a/src/_posts/platform/app/2000-01-01-application-resources.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Application Resources -nav: Resources -modified_at: 2026-05-05 00:00:00 -tags: app resources cpu memory ram swap storage oom -index: 1 ---- - -Application resources define the CPU, memory, swap, and storage available to -each container running your application. - -## Container Sizing - - - -For the full list of available container sizes and their limits, see -[Container Sizes][container-sizes]. - - -## CPU - -## Memory - -### RAM - -### Swap - -### Out of Memory Crashes - -When an application consumes all its allocated memory (RAM + swap), the system -applies a protection mechanism called the **OOM Killer** (Out of Memory Killer). - -#### Sequence of events - -1. The application progressively uses all available RAM -2. The system starts using swap space -3. When memory and swap reach 100% usage, the OOM Killer intervenes -4. The application is immediately terminated by the system - -#### Observable consequences - -* **Abrupt termination:** The application stops without a graceful shutdown process -* **Automatic restart:** The container restarts according to its configuration -* **Restart event:** A "Restart" event appears in the metrics timeline -* **Data loss:** All non-persisted data in memory is lost - -#### Prevention and monitoring - -To avoid this scenario: - -* Regularly monitor memory charts in the [Metrics tab][metrics] -* Set up [alerts][alerts] before reaching memory limits -* Analyze usage spikes in correlation with deployment events -* Consider upgrading to a larger [container size][container-sizes] if needed - -**Note:** The OOM Killer is a system protection mechanism. If your application regularly experiences OOM events, it typically indicates a need for code optimization or increased allocated resources. - -## Storage - -### Ephemeral Filesystem - -## Monitoring Resource Usage - -## Preventing Resource Exhaustion - -[alerts]: {% post_url platform/app/2000-01-01-alerts %} -[container-sizes]: {% post_url platform/internals/2000-01-01-container-sizes %} -[metrics]: {% post_url platform/app/2000-01-01-metrics %} diff --git a/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md b/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md index a9baba245..366964f03 100644 --- a/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md +++ b/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md @@ -1,7 +1,7 @@ --- title: Runtime Issues -modified_at: 2026-05-04 00:00:00 -tags: app runtime crash recovery troubleshooting +modified_at: 2026-05-11 00:00:00 +tags: app runtime crash recovery troubleshooting oom memory index: 3 --- @@ -43,6 +43,36 @@ error and the impact it has on your application: especially if your application is too verbose. This can lead to sensitive data leak and further exploitation. +## Out of Memory Crashes + +When an application consumes all its allocated memory (RAM + swap), the system +applies a protection mechanism called the **OOM Killer** (Out of Memory Killer). + +The usual sequence is: + +1. The application progressively uses all available RAM. +2. The system starts using swap space. +3. When memory and swap reach 100% usage, the OOM Killer intervenes. +4. The application is immediately terminated by the system. + +This can have several observable consequences: + +- Abrupt termination: the application stops without a graceful shutdown process. +- Automatic restart: the container restarts according to its configuration. +- Restart event: a "Restart" event appears in the metrics timeline. +- Data loss: all non-persisted data in memory is lost. + +To reduce the risk of OOM crashes: + +- Regularly monitor memory charts in the [Metrics tab][metrics]. +- Set up [alerts][alerts] before reaching memory limits. +- Analyze usage spikes in correlation with deployment events. +- Consider upgrading to a larger [container size][container-sizes] if needed. + +The OOM Killer is a system protection mechanism. If your application regularly +experiences OOM events, it typically indicates a need for code optimization or +increased allocated resources. + ## Mitigating and Preventing Runtime Errors The very first step to mitigate the consequences of a Runtime Error is @@ -115,3 +145,7 @@ You can modify this behavior by tweaking your [Notifier's configuration]({% post_url platform/app/2000-01-01-notifiers %}). The `app_crashed`, `app_crashed_repeated` and the `app_deployed` events can be particularly worth considering. + +[alerts]: {% post_url platform/app/2000-01-01-alerts %} +[container-sizes]: {% post_url platform/internals/2000-01-01-container-sizes %} +[metrics]: {% post_url platform/app/2000-01-01-metrics %} From 08a1e4f03d4bfe24c3df7504c4737afdb8c961c8 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Mon, 11 May 2026 17:08:16 +0200 Subject: [PATCH 07/10] Restore initial position --- src/_posts/platform/app/2000-01-01-filesystem.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/_posts/platform/app/2000-01-01-filesystem.md b/src/_posts/platform/app/2000-01-01-filesystem.md index 38adb0e94..e4981abda 100644 --- a/src/_posts/platform/app/2000-01-01-filesystem.md +++ b/src/_posts/platform/app/2000-01-01-filesystem.md @@ -2,7 +2,7 @@ title: File System and File Storage modified_at: 2023-07-27 00:00:00 tags: app runtime file system disk storage -index: 2 +index: 1 --- ## Introduction From ad8d2fba84c788a77313bc07295a04a120d00e46 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Mon, 11 May 2026 17:20:22 +0200 Subject: [PATCH 08/10] docs(runtime): move OOM details to error patterns --- .../2000-01-01-runtime-issues.md | 62 ++++++++++--------- 1 file changed, 32 insertions(+), 30 deletions(-) diff --git a/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md b/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md index 366964f03..ee4d5136c 100644 --- a/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md +++ b/src/_posts/platform/app/troubleshooting/2000-01-01-runtime-issues.md @@ -43,36 +43,6 @@ error and the impact it has on your application: especially if your application is too verbose. This can lead to sensitive data leak and further exploitation. -## Out of Memory Crashes - -When an application consumes all its allocated memory (RAM + swap), the system -applies a protection mechanism called the **OOM Killer** (Out of Memory Killer). - -The usual sequence is: - -1. The application progressively uses all available RAM. -2. The system starts using swap space. -3. When memory and swap reach 100% usage, the OOM Killer intervenes. -4. The application is immediately terminated by the system. - -This can have several observable consequences: - -- Abrupt termination: the application stops without a graceful shutdown process. -- Automatic restart: the container restarts according to its configuration. -- Restart event: a "Restart" event appears in the metrics timeline. -- Data loss: all non-persisted data in memory is lost. - -To reduce the risk of OOM crashes: - -- Regularly monitor memory charts in the [Metrics tab][metrics]. -- Set up [alerts][alerts] before reaching memory limits. -- Analyze usage spikes in correlation with deployment events. -- Consider upgrading to a larger [container size][container-sizes] if needed. - -The OOM Killer is a system protection mechanism. If your application regularly -experiences OOM events, it typically indicates a need for code optimization or -increased allocated resources. - ## Mitigating and Preventing Runtime Errors The very first step to mitigate the consequences of a Runtime Error is @@ -146,6 +116,38 @@ You can modify this behavior by tweaking your The `app_crashed`, `app_crashed_repeated` and the `app_deployed` events can be particularly worth considering. +## Common Runtime Error Patterns + +### Out of Memory Crashes + +When an application consumes all its allocated memory (RAM + swap), the system +applies a protection mechanism called the **OOM Killer** (Out of Memory Killer). + +The usual sequence is: + +1. The application progressively uses all available RAM. +2. The system starts using swap space. +3. When memory and swap reach 100% usage, the OOM Killer intervenes. +4. The application is immediately terminated by the system. + +This can have several observable consequences: + +- Abrupt termination: the application stops without a graceful shutdown process. +- Automatic restart: the container restarts according to its configuration. +- Restart event: a "Restart" event appears in the metrics timeline. +- Data loss: all non-persisted data in memory is lost. + +To reduce the risk of OOM crashes: + +- Regularly monitor memory charts in the [Metrics tab][metrics]. +- Set up [alerts][alerts] before reaching memory limits. +- Analyze usage spikes in correlation with deployment events. +- Consider upgrading to a larger [container size][container-sizes] if needed. + +The OOM Killer is a system protection mechanism. If your application regularly +experiences OOM events, it typically indicates a need for code optimization or +increased allocated resources. + [alerts]: {% post_url platform/app/2000-01-01-alerts %} [container-sizes]: {% post_url platform/internals/2000-01-01-container-sizes %} [metrics]: {% post_url platform/app/2000-01-01-metrics %} From 549065b318b29a3e02cf5ca1363469a8da10f587 Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Mon, 11 May 2026 17:50:12 +0200 Subject: [PATCH 09/10] docs: clarify container memory references --- src/_posts/languages/java/2000-01-01-start.md | 14 +++++++------- src/_posts/languages/php/2000-01-01-start.md | 1 - src/_posts/platform/app/2000-01-01-metrics.md | 7 ++++--- .../platform/app/scaling/2000-01-01-scaling.md | 7 ++++--- .../app/scaling/2000-01-01-scalingo-autoscaler.md | 7 ++++--- .../2000-01-01-scalingo-scheduler.md | 5 ++++- 6 files changed, 23 insertions(+), 18 deletions(-) diff --git a/src/_posts/languages/java/2000-01-01-start.md b/src/_posts/languages/java/2000-01-01-start.md index 6655a4e89..80301061b 100644 --- a/src/_posts/languages/java/2000-01-01-start.md +++ b/src/_posts/languages/java/2000-01-01-start.md @@ -114,13 +114,13 @@ faster dependency resolution. However neither the `mvn` executable nor the By default the `-Xmx` configuration of the JVM depends on the size of container you selected for your application: -| Container Size | Maximum Heap Size (MB) | -| -------------: | ------------------------------------: | -| S | `160` | -| M | `300` | -| L | `671` | -| XL | `1536` | -| 2XL and above | ~80% of the RAM allocated in the plan | +| Container Size | Memory (MB) | Maximum Heap Size (MB) | +| -------------: | -------------: | ------------------------------------: | +| S | 256 | `160` | +| M | 512 | `300` | +| L | 1024 | `671` | +| XL | 2048 | `1536` | +| 2XL and above | 4096 and above | ~80% of the RAM allocated in the plan | ### Choose a Maven Version diff --git a/src/_posts/languages/php/2000-01-01-start.md b/src/_posts/languages/php/2000-01-01-start.md index 86fbd0969..53e1a4b4d 100644 --- a/src/_posts/languages/php/2000-01-01-start.md +++ b/src/_posts/languages/php/2000-01-01-start.md @@ -114,7 +114,6 @@ The default values for `pm.max_children` are based on the `memory_limit` parameter of the [PHP configuration](https://github.com/Scalingo/php-buildpack/blob/master/conf/php/php.ini#L15), the used formula is: `floor(available_memory / php_memory_limit) + 2` -{: .table } | Container Size | Memory (MB) | Default Concurrency | | -------------: | ----------: | ------------------: | | S | 256 | 3 | diff --git a/src/_posts/platform/app/2000-01-01-metrics.md b/src/_posts/platform/app/2000-01-01-metrics.md index f172c69a8..e629afdca 100644 --- a/src/_posts/platform/app/2000-01-01-metrics.md +++ b/src/_posts/platform/app/2000-01-01-metrics.md @@ -88,12 +88,12 @@ The swap usage can increase in two different situations: {% note %} Protip: Is your application slow? Check your swap usage! If your app swaps a lot it will significantly alter your application performance. You'd -better reduce its memory usage or use a bigger container size. +better reduce its memory usage or use a bigger +[container size][container-sizes]. {% endnote %} **Note**: The swap line is only shown if the swap usage exceeds 2% of the -[container memory limit]({% post_url -platform/internals/2000-01-01-container-sizes %}). +[container memory limit][container-sizes]. If the application has more than one container of a specific type, these charts show the mean CPU usage / memory consumption of all containers of the same type. @@ -109,3 +109,4 @@ debugging process. [notifiers]: {% post_url platform/app/2000-01-01-notifiers %} [routing-errors]: {% post_url platform/networking/public/2000-01-01-routing %}#http-errors +[container-sizes]: {% post_url platform/internals/2000-01-01-container-sizes %} diff --git a/src/_posts/platform/app/scaling/2000-01-01-scaling.md b/src/_posts/platform/app/scaling/2000-01-01-scaling.md index da50929f0..5ea77ee7c 100644 --- a/src/_posts/platform/app/scaling/2000-01-01-scaling.md +++ b/src/_posts/platform/app/scaling/2000-01-01-scaling.md @@ -74,9 +74,9 @@ Here is a quick comparison table, in the context of a Platform as a Service: ## Limitations - Vertical scaling is limited by the platform. The biggest container we can - currently boot is the `2XL` container, with 4GB of RAM. For a comprehensive - list of container sizes and corresponding specifications, please see our - [dedicated documentation page]({% post_url platform/internals/2000-01-01-container-sizes %}). + currently boot is the `2XL` container, with 4GB of RAM. See the + [container sizes][container-sizes] documentation for the full list of sizes + and their specifications. - Horizontal scaling is limited by default to a maximum of 10 containers per [process type]({% post_url platform/app/2000-01-01-procfile %}). This limit can be increased via our support team. @@ -233,3 +233,4 @@ To learn more about events and notifiers, please visit the page dedicated to [routing-requests]: {% post_url platform/networking/public/2000-01-01-routing %}#requests-distribution [Scalingo Autoscaler]: {% post_url platform/app/scaling/2000-01-01-scalingo-autoscaler %} +[container-sizes]: {% post_url platform/internals/2000-01-01-container-sizes %} diff --git a/src/_posts/platform/app/scaling/2000-01-01-scalingo-autoscaler.md b/src/_posts/platform/app/scaling/2000-01-01-scalingo-autoscaler.md index 5460348c6..66d06a694 100644 --- a/src/_posts/platform/app/scaling/2000-01-01-scalingo-autoscaler.md +++ b/src/_posts/platform/app/scaling/2000-01-01-scalingo-autoscaler.md @@ -238,9 +238,9 @@ started during a scale-out operation are billed like any other container (on the other hand, scaling-in allows to save costs). Consequently, billing depends on the type of container you chose for your -application (M is the default container size), on the maximum number of -containers set in the Autoscaler configuration and on your application -workload. +application (M is the default +[container size][container-sizes]), on the maximum number of containers set in +the Autoscaler configuration and on your application workload. ## Creating an Autoscaler @@ -439,3 +439,4 @@ To learn more about events and notifiers, please visit the page dedicated to [app notifiers]({% post_url platform/app/2000-01-01-notifiers %}). [scaling-v]: {% post_url platform/app/scaling/2000-01-01-scaling %}#vertical-scaling +[container-sizes]: {% post_url platform/internals/2000-01-01-container-sizes %} diff --git a/src/_posts/platform/app/task-scheduling/2000-01-01-scalingo-scheduler.md b/src/_posts/platform/app/task-scheduling/2000-01-01-scalingo-scheduler.md index c02de6d08..63f3f9ce9 100644 --- a/src/_posts/platform/app/task-scheduling/2000-01-01-scalingo-scheduler.md +++ b/src/_posts/platform/app/task-scheduling/2000-01-01-scalingo-scheduler.md @@ -76,7 +76,8 @@ the commands are run are billed like any other [one-off container]({% post_url platform/app/2000-01-01-tasks %}). Consequently, billing depends on the type of container you defined in your task -(M is the default container size) and on the job lifespan. +(M is the default +[container size][container-sizes]) and on the job lifespan. For example, if your job runs during 5 minutes, you will be billed 5 minutes of an M container. @@ -187,3 +188,5 @@ remove the file. Logs for scheduled tasks are included in the [application logs]({% post_url platform/app/2000-01-01-logs %}), next to other containers logs. + +[container-sizes]: {% post_url platform/internals/2000-01-01-container-sizes %} From 18a94cebd296894b818e0e7fc3a6bfdead6e7a7a Mon Sep 17 00:00:00 2001 From: Benjamin ACH Date: Mon, 11 May 2026 22:42:28 +0200 Subject: [PATCH 10/10] docs(languages): add memory management pointers --- src/_posts/languages/go/2000-01-01-start.md | 18 +++++++++++++- src/_posts/languages/java/2000-01-01-start.md | 24 ++++++++++++++++--- .../languages/nodejs/2000-01-01-start.md | 23 +++++++++++++++++- src/_posts/languages/php/2000-01-01-start.md | 15 ++++++++---- .../languages/python/2000-01-01-start.md | 13 +++++++++- src/_posts/languages/ruby/2000-01-01-start.md | 19 ++++++++++++++- 6 files changed, 101 insertions(+), 11 deletions(-) diff --git a/src/_posts/languages/go/2000-01-01-start.md b/src/_posts/languages/go/2000-01-01-start.md index 9e825a158..e03fbee06 100644 --- a/src/_posts/languages/go/2000-01-01-start.md +++ b/src/_posts/languages/go/2000-01-01-start.md @@ -1,7 +1,7 @@ --- title: Go nav: Introduction -modified_at: 2026-04-09 12:00:00 +modified_at: 2026-05-11 12:00:00 tags: go index: 1 --- @@ -68,6 +68,22 @@ Because the buildpack installs compiled executables to `bin`, the `go-post-compile` hook can be written in Go if it's installed by the specified [``]({% post_url languages/go/2000-01-01-gomod %}). +## Memory Management + +Go applications can use `GOMEMLIMIT` to define a soft memory limit for the Go +runtime. In a Scalingo container, set it explicitly when you need tighter memory +control: + +```bash +$ scalingo --app my-app env-set GOMEMLIMIT=400MiB +``` + +Choose a value lower than `CONTAINER_MEMORY`, because `GOMEMLIMIT` is not a hard +limit for the full process memory. For more details, refer to the +[Go runtime environment variables][go-runtime-env]. + ## Buildpack More information at [https://github.com/Scalingo/go-buildpack](https://github.com/Scalingo/go-buildpack). + +[go-runtime-env]: https://pkg.go.dev/runtime#hdr-Environment_Variables diff --git a/src/_posts/languages/java/2000-01-01-start.md b/src/_posts/languages/java/2000-01-01-start.md index 80301061b..d75a885c6 100644 --- a/src/_posts/languages/java/2000-01-01-start.md +++ b/src/_posts/languages/java/2000-01-01-start.md @@ -1,7 +1,7 @@ --- title: Java on Scalingo nav: Introduction -modified_at: 2026-04-23 12:00:00 +modified_at: 2026-05-11 12:00:00 tags: java index: 1 --- @@ -122,6 +122,22 @@ you selected for your application: | XL | 2048 | `1536` | | 2XL and above | 4096 and above | ~80% of the RAM allocated in the plan | +### Memory Management + +Scalingo sets the default JVM heap size according to the selected container +size. This setting controls the Java heap, not every memory allocation made by +the JVM process. + +If your application needs an explicit heap limit, define it with +`JAVA_TOOL_OPTIONS`: + +```bash +$ scalingo --app my-app env-set JAVA_TOOL_OPTIONS="-Xmx512m" +``` + +For more information about JVM memory options, refer to the +[Java command documentation][java-command]. + ### Choose a Maven Version The `system.properties` file also allows for `maven.version` entry @@ -159,8 +175,8 @@ $ scalingo env-set MAVEN_CUSTOM_GOALS="clean package" $ scalingo env-set MAVEN_CUSTOM_OPTS="--update-snapshots -DskipTests=true" ``` -Other options are available for [defining custom a `settings.xml` -file](https://devcenter.heroku.com/articles/using-a-custom-maven-settings-xml). +Other options are available for [defining a custom `settings.xml` +file](https://maven.apache.org/settings.html). ### Installation of JDK only (no Maven) @@ -196,3 +212,5 @@ account. More information at [https://github.com/Scalingo/java-buildpack](https://github.com/Scalingo/java-buildpack). + +[java-command]: https://docs.oracle.com/en/java/javase/25/docs/specs/man/java.html diff --git a/src/_posts/languages/nodejs/2000-01-01-start.md b/src/_posts/languages/nodejs/2000-01-01-start.md index ee4ceffbe..08b12ab6f 100644 --- a/src/_posts/languages/nodejs/2000-01-01-start.md +++ b/src/_posts/languages/nodejs/2000-01-01-start.md @@ -1,7 +1,7 @@ --- title: Node.js nav: Introduction -modified_at: 2026-04-21 12:00:00 +modified_at: 2026-05-11 12:00:00 tags: nodejs index: 1 --- @@ -216,6 +216,24 @@ Example of `package.json`: } ``` +## Memory Management + +Modern Node.js versions are container-aware and usually do not require setting +`--max-old-space-size` by default. For Node.js 20 and later, the default V8 heap +size is commonly around 50% of the container memory up to 4 GiB, then levels out +around 2 GiB, as documented for [Node.js 20 in containers][nodejs-container-memory]. + +If your application needs an explicit V8 old-space limit, use `NODE_OPTIONS`: + +```bash +$ scalingo --app my-app env-set NODE_OPTIONS="--max-old-space-size=512" +``` + +The value is expressed in megabytes. This setting can help make memory usage +more predictable, but increasing it does not fix memory leaks. + +For more details, refer to the [official Node.js memory guide][nodejs-memory-guide]. + ### Node.js Build Hooks If your application has a build step that you would like to run when you @@ -438,3 +456,6 @@ The solution is to change the content of the Procfile to directly start the Node ```yaml web: node server.js ``` + +[nodejs-memory-guide]: https://nodejs.org/learn/diagnostics/memory/understanding-and-tuning-memory +[nodejs-container-memory]: https://developers.redhat.com/articles/2025/10/10/nodejs-20-memory-management-containers diff --git a/src/_posts/languages/php/2000-01-01-start.md b/src/_posts/languages/php/2000-01-01-start.md index 53e1a4b4d..8fb154b1b 100644 --- a/src/_posts/languages/php/2000-01-01-start.md +++ b/src/_posts/languages/php/2000-01-01-start.md @@ -1,7 +1,7 @@ --- title: PHP on Scalingo nav: Introduction -modified_at: 2026-04-10 12:00:00 +modified_at: 2026-05-11 12:00:00 tags: php index: 1 --- @@ -122,14 +122,21 @@ the used formula is: `floor(available_memory / php_memory_limit) + 2` | XL | 2048 | 12 | | 2XL | 4096 | 22 | +### Memory Management + +For PHP-FPM applications, `WEB_CONCURRENCY`, `pm.max_children`, and +`memory_limit` are the main memory management levers. Each PHP-FPM child handles +one request at a time, so increasing concurrency can also increase the maximum +memory used by the application. + ### Concurrency Fine Tuning Fine tuning the value of the `WEB_CONCURRENCY` environment variable is a bit -tricky and must be handled with care. There is no magic formulae and one must -load test his application to find the best value matching his use case. If the +tricky and must be handled with care. There is no magic formula and you should +load test your application to find the best value matching your use case. If the application is swapping, you might need to lower the value of `WEB_CONCURRENCY` and increase the amount of containers. On the contrary, if your application -does not use all his memory, one can try to slightly increase the +does not use all its memory, you can try to slightly increase the `WEB_CONCURRENCY` value and make sure the application does not start swapping. Note that if the `WEB_CONCURRENCY` value is too high your application will not diff --git a/src/_posts/languages/python/2000-01-01-start.md b/src/_posts/languages/python/2000-01-01-start.md index 52a5f2e29..dc0d3e1ff 100644 --- a/src/_posts/languages/python/2000-01-01-start.md +++ b/src/_posts/languages/python/2000-01-01-start.md @@ -1,7 +1,7 @@ --- title: Python nav: Introduction -modified_at: 2026-04-08 12:00:00 +modified_at: 2026-05-11 12:00:00 tags: python index: 1 --- @@ -130,3 +130,14 @@ The default level of concurrency is automatically defined, depending on the amou For further details about this calculation, please see the [WEB_CONCURRENCY.sh](https://github.com/Scalingo/python-buildpack/blob/master/vendor/WEB_CONCURRENCY.sh) script of the Python buildpack. To override the automatically defined value, set the `WEB_CONCURRENCY` environment variable to the desired value. + +### Memory Management + +`WEB_CONCURRENCY` controls how many application worker processes are started by +servers such as [Gunicorn][gunicorn-settings] or [Uvicorn][uvicorn-settings]. +Lowering this value can reduce memory usage when your application uses too much +RAM or starts swapping. If you set a fixed value, review it when you change the +container size. + +[gunicorn-settings]: https://docs.gunicorn.org/en/stable/settings.html#workers +[uvicorn-settings]: https://www.uvicorn.org/settings/#production diff --git a/src/_posts/languages/ruby/2000-01-01-start.md b/src/_posts/languages/ruby/2000-01-01-start.md index a25803923..f1fc59ba9 100644 --- a/src/_posts/languages/ruby/2000-01-01-start.md +++ b/src/_posts/languages/ruby/2000-01-01-start.md @@ -1,7 +1,7 @@ --- title: Ruby nav: Introduction -modified_at: 2026-04-22 12:00:00 +modified_at: 2026-05-11 12:00:00 tags: ruby index: 1 --- @@ -172,5 +172,22 @@ For further details about this calculation, please see the To override the automatically defined value, set the `WEB_CONCURRENCY` environment variable to the desired value. +### Memory Management + +Each Puma worker is a separate Ruby process. If your application uses too much +memory, tune `WEB_CONCURRENCY` and `MAX_THREADS` using your application metrics. + +For new Ruby applications, the buildpack sets `MALLOC_ARENA_MAX=2` by default +to limit glibc memory arenas. On memory-constrained threaded workloads, you can +test `MALLOC_ARENA_MAX=1`, but this may reduce performance: + +```bash +$ scalingo --app my-app env-set MALLOC_ARENA_MAX=1 +``` + +If memory fragmentation remains an issue, you can also test the +[jemalloc buildpack][jemalloc-buildpack]. + [web_concurrency_file]: https://github.com/Scalingo/ruby-buildpack/blob/master/lib/language_pack/ruby.rb +[jemalloc-buildpack]: {% post_url platform/deployment/buildpacks/2000-01-01-jemalloc %}