Mercurial > hg > orthanc-book
changeset 1293:8bbdca938605
review cache/memory performance
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Tue, 18 Aug 2026 14:13:10 +0200 |
| parents | 7f3d38f8a632 |
| children | 4c666b4f5955 |
| files | Sphinx/source/faq/scalability.rst |
| diffstat | 1 files changed, 91 insertions(+), 68 deletions(-) [+] |
line wrap: on
line diff
--- a/Sphinx/source/faq/scalability.rst Mon Aug 17 15:49:00 2026 +0200 +++ b/Sphinx/source/faq/scalability.rst Tue Aug 18 14:13:10 2026 +0200 @@ -159,87 +159,92 @@ Controlling the threads ----------------------- -Orthanc uses many `threads <https://en.wikipedia.org/wiki/Thread_(computing)>`__ -to perform operations in parallel. Depending on your infrastructure and -usage, you may fine tune many configurations related to threading: +Orthanc uses multiple `threads <https://en.wikipedia.org/wiki/Thread_(computing)>`__ +to perform operations in parallel. Depending on your infrastructure and +usage, you can fine-tune many configurations options related to multithreading: +---------------------------------------+-------------------------------------------------------------+---------+-------------------------------------------------+----------------------------------------------------------------------------------------------------------+ -| Option | Purpose | Default | Related metrics | Recommended Adjustments | +| Option | Purpose | Default | Related metrics | Recommended adjustments | +=======================================+=============================================================+=========+=================================================+==========================================================================================================+ -| ``HttpThreadsCount`` | Threads for handling the Rest API. | 50 | ``orthanc_available_http_threads_count`` | Increase when the number of available threads is too low. An alternative adjustment is to spin | -| | | | | another Orthanc on another VM, connected to the same PostgreSQL Database to spread the workload. | +| ``HttpThreadsCount`` | Threads for handling incoming requests to the REST API. | 50 | ``orthanc_available_http_threads_count`` | Increase when the number of available threads is too low. An alternative adjustment is to spin | +| | | | | another Orthanc on another VM, connected to the same PostgreSQL database to spread the workload. | +---------------------------------------+-------------------------------------------------------------+---------+-------------------------------------------------+----------------------------------------------------------------------------------------------------------+ -| ``DicomThreadsCount`` | Threads for handling DICOM SCP operations. | 4 | ``orthanc_available_dicom_threads`` | Increase when the number of available threads is too low e.g, if Orthanc must handle many C-STORE | -| | | | | and C-FIND in parallel. E.g: if Orthanc is connected to 100 DICOM modalities, statistically, there might | -| | | | | be 10 modalities that will try to communicate with Orthanc at a given time. You should therefore | -| | | | | increase it to 10. | +| ``DicomThreadsCount`` | Threads for handling incoming DICOM SCP connections. | 4 | ``orthanc_available_dicom_threads`` | Increase when the number of available threads is too low, typically if Orthanc must handle many C-STORE | +| | | | | and C-FIND in parallel. For instance: If Orthanc is connected to 100 DICOM modalities, statistically, | +| | | | | there might be 10 modalities that will try to communicate with Orthanc at any given time, so you should | +| | | | | increase this option to 10. | +---------------------------------------+-------------------------------------------------------------+---------+-------------------------------------------------+----------------------------------------------------------------------------------------------------------+ -| ``ConcurrentJobs`` | Maximum number of processing jobs that are simultaneously | 2 | ``orthanc_jobs_running`` | Increase when the number of pending jobs is too high. Note that each job may itself use multiple | -| | running at any given time. | | ``orthanc_jobs_pending`` | to execute. | +| ``ConcurrentJobs`` | Maximum number of processing jobs that are simultaneously | 2 | ``orthanc_jobs_running`` | Increase when the number of pending jobs is too high. Note that each job may itself use multiple | +| | running at any given time. | | ``orthanc_jobs_pending`` | threads to execute. | +---------------------------------------+-------------------------------------------------------------+---------+-------------------------------------------------+----------------------------------------------------------------------------------------------------------+ -| ``JobsEngineThreadsCount.`` | Number of threads that are used to perform a resource | 1 | | Increase to 8-16 if you are using a distributed object storage for the Orthanc Storage. | +| ``JobsEngineThreadsCount``, | Number of threads that are used to perform a resource | 1 | | Increase to 8-16 if you are using a distributed object storage as the Orthanc storage area. | | ``ResourceModification`` | modification or anonymization. | | | | +---------------------------------------+-------------------------------------------------------------+---------+-------------------------------------------------+----------------------------------------------------------------------------------------------------------+ -| ``StorageLoaderThreadsCount`` | Number of threads that are used to read files from Storage. | 4 | ``orthanc_storage_available_threads`` | Increase when the number of available threads is too low. Typically if you are using a distributed | -| | | | | object storage for the Orthanc Storage, increase to e.g. 20. | +| ``StorageLoaderThreadsCount`` | Number of threads that are used to read files from the | 4 | ``orthanc_storage_available_threads`` | Increase when the number of available threads is too low. Typically, if you are using a distributed | +| | storage area. | | | object storage for the Orthanc storage area, increase to, say, 20. | +---------------------------------------+-------------------------------------------------------------+---------+-------------------------------------------------+----------------------------------------------------------------------------------------------------------+ | ``DicomParserThreadsCount`` | Number of threads that are used to parse DICOM files and | 2 | ``orthanc_dicom_parser_available_threads`` | Increase when the number of available threads is too low. | -| | access DICOM Tags that are not in the SQL Database. | | | | +| | access DICOM tags that are not indexed in the database. | | | | +---------------------------------------+-------------------------------------------------------------+---------+-------------------------------------------------+----------------------------------------------------------------------------------------------------------+ -| ``TranscoderThreadsCount`` | Number of threads that are used to transcode DICOM files | 4 | ``orthanc_transcoder_available_threads`` | Increase when the number of available threads is too low. | +| ``TranscoderThreadsCount`` | Number of threads that are used to transcode DICOM files. | 4 | ``orthanc_transcoder_available_threads`` | Increase when the number of available threads is too low. | | | | | | | +---------------------------------------+-------------------------------------------------------------+---------+-------------------------------------------------+----------------------------------------------------------------------------------------------------------+ | ``SequentialDicomReaderThreadsCount`` | Number of threads used for the sequential access to DICOM | 4 | ``orthanc_sequential_reader_available_threads`` | Increase when the number of available threads is too low. If not defined, the default value is | -| | instances (for archive jobs, C-STORE SCU, C-GET SCP and | | | identical to ``StorageLoaderThreadsCount`` so you should probably never adjust this value. | -| | C-MOVE SCP) | | | | +| | instances (for archive jobs, C-STORE SCU, C-GET SCP, and | | | identical to ``StorageLoaderThreadsCount``, so you should probably never adjust this value. | +| | C-MOVE SCP). | | | | +---------------------------------------+-------------------------------------------------------------+---------+-------------------------------------------------+----------------------------------------------------------------------------------------------------------+ -Pay attention that all these threads might consume a lot of memory and you might need to limit the memory usage. +Pay attention that all these threads might consume a lot of memory and +you might need to limit the memory usage, so check out the :ref:`next +section <scalability-memory>`. .. _scalability-memory: Controlling memory usage ------------------------ -Starting with Orthanc 1.13.0, you may fine tune many configurations related to -the memory consumption. However, you should always keep in mind that, when -handling large DICOM files, Orthanc needs to store the full file in memory and, -possibly multiple times during a transcoding or a compression so, even if you -have set limits on memory usage, Orthanc might overpass these limits and this might -result in an Out Of memory error (OOM). E.g. if, at some point, Orthanc must handle -a 3 GB DICOM file while there is only 2 GB RAM on the system, the system will crash ! +Starting with Orthanc 1.13.0, you can fine-tune many configuration +options related to the memory consumption. However, you should always +keep in mind that, when handling large DICOM files, Orthanc needs to +store the full file in RAM, possibly multiple times during transcoding +or compression. As a consequence, even if you set limits on memory +usage, Orthanc may punctually exceed these limits, which can result in +an out-of-memory (OOM) error. For instance, if, at some point, Orthanc +must handle a 3GB DICOM file while there is only 2GB RAM on the +system, the system would crash. +-----------------------------------------+-------------------------------------------------------------------------------------+---------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ -| Option | Purpose | Default | Related metrics | Recommended Adjustments | +| Option | Purpose | Default | Related metrics | Recommended adjustments | +=========================================+=====================================================================================+=========+==============================================+=========================================================================================================================+ -| ``MaximumStorageCacheSize`` | Maximum size of the storage cache in MB. The storage cache | 128 | ``orthanc_storage_cache_miss_count`` | The cache is relevant mainly if you are using the received DICOM data directly after you have | -| | is stored in RAM and contains a copy of recently accessed files | | ``orthanc_storage_cache_hit_count`` | received it. E.g. when you are viewing data directly after acquisition or if you are using | -| | | | ``orthanc_storage_cache_count`` | Orthanc as a router. In this case, it might be interesting to have a large cache size (possibly | -| | | | ``orthanc_storage_cache_size_mb`` | of multiple GB) to avoid reading data from disk. | +| ``MaximumStorageCacheSize`` | Maximum size of the storage cache (in MB). The storage cache | 128 | ``orthanc_storage_cache_miss_count`` | This cache is mainly useful when you use the received DICOM data immediately after receiving it, | +| | is stored in RAM and contains the content of the recently accessed | | ``orthanc_storage_cache_hit_count`` | or when REST API clients access the same DICOM instances across multiple calls. For instance, when you are viewing data | +| | :ref:`attachments <attachments>` from the storage area, which notably | | ``orthanc_storage_cache_count`` | directly after acquisition, if you are using Orthanc as a router, or if multiple users access the same study in a | +| | include the DICOM files. | | ``orthanc_storage_cache_size_mb`` | viewer. In such situations, it might be interesting to have a large cache size (possibly of multiple GB) to avoid | +| | | | | reading the same data multiple times from the disk or from the distributed filesystem. | +-----------------------------------------+-------------------------------------------------------------------------------------+---------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ -| ``DicomParserCacheSize`` | Maximum size of the cache of parsed DICOM files in MB. | 256 | ``orthanc_dicom_parser_cache_miss_count`` | This cache is relevant when e.g. a viewer or the Rest API request the same DICOM tags multiple times. | -| | is stored in RAM and contains a copy of recently accessed files | | ``orthanc_dicom_parser_cache_hit_count`` | However, it is expected that the cache miss is very high and you should probably not worry about it. | -| | | | ``orthanc_dicom_parser_cache_count`` | | +| ``DicomParserCacheSize`` | Maximum size of the cache of parsed DICOM files (in MB). | 256 | ``orthanc_dicom_parser_cache_miss_count`` | This cache is relevant when, e.g., a viewer or the REST API successively request different DICOM tags from the same | +| | This cache is stored in RAM and contains a parsed version of the most recently | | ``orthanc_dicom_parser_cache_hit_count`` | DICOM instance. However, it is expected that the cache miss is very high and you should probably not worry about it. | +| | accessed DICOM instances. | | ``orthanc_dicom_parser_cache_count`` | | | | | | ``orthanc_dicom_parser_cache_size_mb`` | | +-----------------------------------------+-------------------------------------------------------------------------------------+---------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ -| ``TranscoderCacheSize`` | Maximum size of the cache of transcoded DICOM files in MB. | 256 | ``orthanc_transcoder_cache_miss_count`` | This cache is relevant when e.g. a viewer or the Rest API request the same transcoded DICOM files multiple times. | -| | is stored in RAM and contains a copy of recently accessed files | | ``orthanc_transcoder_cache_hit_count`` | However, it is expected that the cache miss is very high and you should probably not worry about it. | -| | | | ``orthanc_transcoder_cache_count`` | | +| ``TranscoderCacheSize`` | Maximum size of the cache of transcoded DICOM files (in MB). | 256 | ``orthanc_transcoder_cache_miss_count`` | This cache is relevant when, e.g., a viewer or the REST API request the same transcoded DICOM instance multiple times. | +| | This cache is stored in RAM and contains a parsed version of the most recently | | ``orthanc_transcoder_cache_hit_count`` | This cache is useful because trancsoding a DICOM instance can be a highly costly operation. | +| | transcoded DICOM instances. | | ``orthanc_transcoder_cache_count`` | However, it is expected that the cache miss is very high and you should probably not worry about it. | | | | | ``orthanc_transcoder_cache_size_mb`` | | +-----------------------------------------+-------------------------------------------------------------------------------------+---------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ | ``StorageMemoryCapacity`` | Peak amount of RAM (in MB) that can be allocated by the threads | 512 | ``orthanc_storage_memory_usage_mb`` | Monitor ``orthanc_storage_memory_usage_mb``. If it is regularly close to the configured capacity, this means that | -| | loading from the storage area. | | ``orthanc_storage_memory_max_usage_mb`` | some storage loader threads might will have to wait until more RAM is available which will degrade the performance. | +| | loading from the storage area. | | ``orthanc_storage_memory_max_usage_mb`` | some storage loader threads might have to wait until more RAM is available, which can degrade the performance. | | | Note that this limit can be exceeded when a single file is larger than this option. | | ``orthanc_storage_memory_count`` | | | | | | ``orthanc_storage_memory_capacity_mb`` | | +-----------------------------------------+-------------------------------------------------------------------------------------+---------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ | ``DicomParserMemoryCapacity`` | Peak amount of RAM (in MB) that can be allocated by the threads | 256 | ``orthanc_dicom_parser_memory_usage_mb`` | Monitor ``orthanc_dicom_parser_memory_usage_mb``. If it is regularly close to the configured capacity, this means that | -| | that parse the DICOM files. | | ``orthanc_dicom_parser_memory_max_usage_mb`` | some DICOM parser threads might will have to wait until more RAM is available which will degrade the performance. | -| | Note that this limit can be exceeded when a single file is larger than this option. | | ``orthanc_dicom_parser_memory_count`` | | +| | that parse the DICOM files. Note that this limit can be exceeded | | ``orthanc_dicom_parser_memory_max_usage_mb`` | some DICOM parser threads might have to wait until more RAM is available, which can degrade the performance. | +| | when a single DICOM instance is larger than this option. | | ``orthanc_dicom_parser_memory_count`` | | | | | | ``orthanc_dicom_parser_memory_capacity_mb`` | | +-----------------------------------------+-------------------------------------------------------------------------------------+---------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ | ``TranscoderMemoryCapacity`` | Peak amount of RAM (in MB) that can be allocated by the threads | 256 | ``orthanc_transcoder_memory_usage_mb`` | Monitor ``orthanc_transcoder_memory_usage_mb``. If it is regularly close to the configured capacity, this means that | -| | that transcode the DICOM files. | | ``orthanc_transcoder_memory_max_usage_mb`` | some transcoder threads might will have to wait until more RAM is available which will degrade the performance. | -| | Note that this limit can be exceeded when a single file is larger than this option. | | ``orthanc_transcoder_memory_count`` | | +| | that transcode the DICOM files. Note that this limit can be exceeded | | ``orthanc_transcoder_memory_max_usage_mb`` | some transcoder threads might have to wait until more RAM is available, which can degrade the performance. | +| | when a single transcoded DICOM instance is larger than this option. | | ``orthanc_transcoder_memory_count`` | | | | | | ``orthanc_transcoder_memory_capacity_mb`` | | +-----------------------------------------+-------------------------------------------------------------------------------------+---------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ | ``SequentialDicomReaderWindowCapacity`` | Maximum amount of RAM (in MB) allocated to each local | 128 | | There is currently no way to monitor these memory consumptions. | @@ -248,32 +253,49 @@ | | Note that this limit can be exceeded when a single file is larger than this option. | | | | +-----------------------------------------+-------------------------------------------------------------------------------------+---------+----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ -All the **Caches** will always fill to their full capacity as soon as they are used so you should always expect them to consume the declared amount of RAM. +All the **caches** will progressively fill to their full capacity as +soon as they are used, so you should always expect them to consume +their allocated amount of RAM. -For the **MemoryCapacities**, the RAM will be used only when a thread requires RAM in this particular RAM space and the RAM will be released as soon -as the thread has finished its job with this particular data. If, at some point, a thread requires X MB of RAM and this amount of RAM is currently not -available, it will have to wait until other threads have freed X MB. +For the **memory capacities**, RAM is allocated only when a thread +requires memory from the corresponding memory area, and is released as +soon as the thread has finished its job with this particular data. +If, at some point, a thread requires X MB of RAM and this amount of +RAM is currently not available, the thread must wait until other +threads have freed X MB. -E.g. If you have declared 512 MB of ``StorageMemoryCapacity`` and if have 2 threads that have reserved 200 MB each to each handle a 200 MB file and -a third thread would like to reserve 200 MB for another file, the third thread will have to wait until one of the first two threads has completed -its work and until there are at least 200 MB of available memory in that RAM space. +For instance, if you have configured ``StorageMemoryCapacity`` to 512 +MB and two threads have each reserved 200 MB to process a 200 MB file, +a third thread that needs to reserve 200 MB for another file will have +to wait until one of the first two threads has finished its work and +at least 200 MB of memory is available in the corresponding memory +capacity. -If you have declared 512 MB of ``StorageMemoryCapacity`` and if have 2 threads that have reserved 200 MB each to each handle a 200 MB file and -a third thread would like to reserve 600 MB for another file, the third thread will have to wait until both threads have completed their work and, -only at that time, the 3rd thread will be allocated 600 MB (more than the declared maximum capacity !!!). The maximum usage of this RAM space will be recorded -in the ``orthanc_*_memory_max_usage_mb`` metrics. +Conversely, if you have configured ``StorageMemoryCapacity`` to 512 MB +and two threads have each reserved 200 MB to process a 200 MB file, a +third thread that needs to reserve 600 MB for another file will have +to wait until both threads have finished their work. Only then will +the third thread be allocated 600 MB, punctually exceeding the +declared maximum capacity. The maximum usage of this memory space will +be recorded in the ``orthanc_*_memory_max_usage_mb`` metrics. -**Note**: Orthanc also uses RAM that is not part of these RAM spaces where the memory is controlled. It is very difficult to evaluate the amount -of RAM that is not controlled but you should consider that an extra 128 MB is required. +**Note**: Orthanc also uses RAM that is not part of the memory areas +controlled by these memory capacities. It is difficult to estimate the +amount of RAM used outside these controlled areas, as it depends on +your usage patterns, but you should allow for an additional 128 MB of +RAM. -How can I compute the total amount of memory Orthanc will consume ? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +How can I compute the total amount of memory Orthanc will consume? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this section, we will consider 2 scenarios: -In this section, we will consider 2 scenario: -- in the first one, you know that your Orthanc -instance only handles `small` DICOM files that are less than 10-20 MB (MRI, CT, CR, DX, standard US, ...) -- in the second one, where Orthanc also handles `large` DICOM files between 300 MB and 4 GB (Mammography, Cardiac US, ...). +* In the first one, your Orthanc server only handles `small` DICOM + instances that are less than 10-20 MB (MRI, CT, CR, DX, standard US,...). + +* In the second one, Orthanc also handles `large` DICOM instances between + 300 MB and 4 GB (videos, cardiac US, whole-slide images,...). For both scenario, consider we have these configurations: @@ -298,7 +320,7 @@ "TranscoderMemoryCapacity": 256 } -In the first scenario, where Orthanc handles small files, Orthanc should never exceed the ``*MemoryCapacity`` configurations: +In the first scenario, where Orthanc handles small instances, Orthanc should never exceed the ``*MemoryCapacity`` configurations: .. code-block:: txt @@ -349,11 +371,12 @@ Running Orthanc on a system with limited RAM ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you are running Orthanc on a system with very limited memory, you should -configure Orthanc accordingly. - -You should probably leave 64 MB to the OS, don't use any caches in Orthanc, reduce the number of **SequentialDicomReaderThreadsCount** -and reduce all **MemoryCapacities** and reduce the number of HTTP and DICOM threads. E.g.: +If you are running Orthanc on a system with very limited memory, you +should configure Orthanc accordingly. You should probably leave 64 MB +to the OS, disable caches in Orthanc, reduce the number of +``SequentialDicomReaderThreadsCount``, reduce all +``MemoryCapacities``, and reduce the number of HTTP and DICOM +threads. Here is an example: .. code-block:: txt
