diff --git a/config/logstash.yml b/config/logstash.yml index 62b5912c498..6315577c622 100644 --- a/config/logstash.yml +++ b/config/logstash.yml @@ -331,8 +331,8 @@ # pipeline.separate_logs: false # # Determine where to allocate memory buffers, for plugins that leverage them. -# Default to direct, optionally can be switched to heap to select Java heap space. -# pipeline.buffer.type: direct +# Defaults to heap, optionally can be switched to direct to select direct memory space. +# pipeline.buffer.type: heap # # ------------ X-Pack Settings (not applicable for OSS build)-------------- # diff --git a/docs/static/config-details.asciidoc b/docs/static/config-details.asciidoc index a68e89e2673..a76e9ed46fb 100644 --- a/docs/static/config-details.asciidoc +++ b/docs/static/config-details.asciidoc @@ -118,30 +118,18 @@ To summarize, we have 3 categories of memory usage, where 2 can be limited by th Keep these memory requirements in mind as you calculate your ideal memory allocation. -[[reducing-off-heap-usage]] -===== Upcoming changes to Buffer Allocation and Troubleshooting Out of Memory errors - -Plugins such as {agent}, {beats}, TCP, and HTTP inputs, currently default to using direct memory as it tends -to provide better performance, especially when interacting with the network stack. -Under heavy load, namely large number of connections and large messages, the direct memory space can be exhausted and lead to Out of Memory (OOM) errors in off-heap space. - -An off-heap OOM is difficult to debug, so {ls} provides a `pipeline.buffer.type` setting in <> that lets you control where to allocate memory buffers for plugins that use them. -Currently it is set to `direct` by default, but you can change it to `heap` to use Java heap space instead, which will be become the default in the future. -When set to `heap`, buffer allocations used by plugins are configured to **prefer** the -Java Heap instead of direct memory, as direct memory allocations may still be necessary depending on the plugin. - -When set to "heap", in the event of an out-of-memory, Logstash will produce a heap dump to facilitate debugging. - -It is important to note that the Java heap sizing requirements will be impacted by this change since -allocations that previously resided on the direct memory will use heap instead. - -Performance-wise there shouldn't be a noticeable impact, since while direct memory IO is faster, Logstash Event objects produced by these plugins end up being allocated on the Java Heap, incurring the cost of copying from direct memory to heap memory regardless of the setting. - -[NOTE] --- -* When you set `pipeline.buffer.type` to `heap`, consider incrementing the Java heap by the -amount of memory that had been reserved for direct space. --- +[[off-heap-buffers-allocation]] +===== Buffer Allocation types +Input plugins such as {agent}, {beats}, TCP, and HTTP will allocate buffers in Java heap memory to read events from the network. +This is the preferred allocation method as it facilitates debugging memory usage problems (such as leaks and Out of Memory errors) through the analysis of heap dumps. + +Before version 9.0.0, Logstash defaulted to allocate direct memory for this purpose instead of heap. To re-enable the previous behaviour {ls} provides +a `pipeline.buffer.type` setting in <> that lets you control where to allocate +memory buffers for plugins that use them. + +There shouldn't be a noticeable performance impact in switching between `direct` and `heap`. +While copying bytes from OS buffers to direct memory buffers is faster, Logstash Event objects produced by these plugins end up +being allocated on the Java Heap incurring the cost of copying from direct memory to heap memory, regardless of the setting. [[memory-size-calculation]] ===== Memory sizing diff --git a/docs/static/settings-file.asciidoc b/docs/static/settings-file.asciidoc index d06327cce3d..2293e96f6fa 100644 --- a/docs/static/settings-file.asciidoc +++ b/docs/static/settings-file.asciidoc @@ -369,6 +369,6 @@ Setting this flag to `warn` is deprecated and will be removed in a future releas | `pipeline.buffer.type` | Determine where to allocate memory buffers, for plugins that leverage them. -Currently defaults to `direct` but can be switched to `heap` to select Java heap space, which will become the default in the future. -| `direct` Check out <> for more info. +Defaults to `heap` but can be switched to `direct` to instruct Logstash to prefer allocation of buffers in direct memory. +| `heap` Check out <> for more info. |======================================================================= diff --git a/logstash-core/lib/logstash/environment.rb b/logstash-core/lib/logstash/environment.rb index 164a190eb69..8d796950065 100644 --- a/logstash-core/lib/logstash/environment.rb +++ b/logstash-core/lib/logstash/environment.rb @@ -111,7 +111,7 @@ module Environment Setting::String.new("keystore.classname", "org.logstash.secret.store.backend.JavaKeyStore"), Setting::String.new("keystore.file", ::File.join(::File.join(LogStash::Environment::LOGSTASH_HOME, "config"), "logstash.keystore"), false), # will be populated on Setting::NullableString.new("monitoring.cluster_uuid"), - Setting::String.new("pipeline.buffer.type", "direct", true, ["direct", "heap"]) + Setting::String.new("pipeline.buffer.type", "heap", true, ["direct", "heap"]) # post_process ].each {|setting| SETTINGS.register(setting) }