Update docs

README.md

@@ -71,6 +71,7 @@ Massive processing of remote images is a potentially dangerous thing, security-w
    * [Prometheus metrics](./docs/configuration.md#prometheus-metrics)
    * [Error reporting](./docs/configuration.md#error-reporting)
    * [Syslog](./docs/configuration.md#syslog)
+   * [Memory usage tweaks](./docs/configuration.md#memory-usage-tweaks)
    * [Miscellaneous](./docs/configuration.md#miscellaneous)
 4. [Generating the URL](./docs/generating_the_url_basic.md)
    * [Basic](./docs/generating_the_url_basic.md)
@@ -86,6 +87,7 @@ Massive processing of remote images is a potentially dangerous thing, security-w
 12. [Image formats support](./docs/image_formats_support.md)
 13. [About processing pipeline](./docs/about_processing_pipeline.md)
 14. [Health check](./docs/healthcheck.md)
+15. [Memory usage tweaks](./docs/memory_usage_tweaks.md)
 
 ## Author
 

docs/configuration.md

@@ -186,6 +186,14 @@ imgproxy can send logs to syslog, but this feature is disabled by default. To en
 * `IMGPROXY_SYSLOG_NETWORK`: network that will be used to connect to syslog. When blank, the local syslog server will be used. Known networks are `tcp`, `tcp4`, `tcp6`, `udp`, `udp4`, `udp6`, `ip`, `ip4`, `ip6`, `unix`, `unixgram` and `unixpacket`. Default: blank;
 * `IMGPROXY_SYSLOG_ADDRESS`: address of the syslog service. Not used if `IMGPROXY_SYSLOG_NETWORK` is blank. Default: blank;
 
+### Memory usage tweaks
+
+**Warning:** It's highly recommended to read [Memory usage tweaks](./memory_usage_tweaks.md) guide before changing this settings.
+
+* `IMGPROXY_DOWNLOAD_BUFFER_SIZE`: the initial size (in bytes) of a single download buffer. When zero, initializes empty download buffers. Default: `0`;
+* `IMGPROXY_GZIP_BUFFER_SIZE`: the initial size (in bytes) of a single GZip buffer. When zero, initializes empty GZip buffers. Makes sense only when GZip compression is enabled. Default: `0`;
+* `IMGPROXY_FREE_MEMORY_INTERVAL`: the interval (in seconds) at which unused memory will be returned to the OS. Default: `10`.
+
 ### Miscellaneous
 
 * `IMGPROXY_BASE_URL`: base URL prefix that will be added to every requested image URL. For example, if the base URL is `http://example.com/images` and `/path/to/image.png` is requested, imgproxy will download the source image from `http://example.com/images/path/to/image.png`. Default: blank.

docs/memory_usage_tweaks.md

@@ -0,0 +1,17 @@
+# Memory usage tweaks
+
+There are some imgproxy options that can help you to optimize memory usage and decrease memory fragmentation.
+
+**Warning:** This is an advanced part. Please make sure that you know what're you doing before changing anything.
+
+### `IMGPROXY_DOWNLOAD_BUFFER_SIZE`
+
+imgproxy uses memory buffers to download source images. While these buffers are empty at the start by default, they can grow to a required size when imgproxy downloads an image. Allocating new memory to grow the buffers can cause memory fragmentation. Allocating required memory at the start can eliminate much of memory fragmentation since buffers won't grow. Setting `IMGPROXY_DOWNLOAD_BUFFER_SIZE` will tell imgproxy to initialize download buffers with _at least_ the specified size. It's recommended to use the estimates size of your biggest image as the initial download buffers size.
+
+### `IMGPROXY_GZIP_BUFFER_SIZE`
+
+The same as `IMGPROXY_DOWNLOAD_BUFFER_SIZE` but for GZip buffers. If you use GZip compression of the resulting images, you can reduce memory fragmentation by using the estimated maximum size of the GZipped resulting image as the initial size of GZip buffers.
+
+### `IMGPROXY_FREE_MEMORY_INTERVAL`
+
+Working with a large amount of data can cause allocating some memory that is not used most of the time. That's why imgproxy enforces Go's garbage collector to free as much memory as possible and return it to the OS. The default interval of this action is 10 seconds, but you can change it by setting `IMGPROXY_FREE_MEMORY_INTERVAL`. Decreasing the interval can smooth the memory usage graph but it can also slow down imgproxy a little. Increasing has the opposite effect.