Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adds section to describe intended usage of pipeline.buffer.type #16083

Merged
merged 7 commits into from
May 13, 2024
Merged

Adds section to describe intended usage of pipeline.buffer.type #16083

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ee64254
[Doc] Adds section to describe the intended usage of and impact on m…
andsel Apr 16, 2024
16d9485
Use more inclusive language in referencing the new section.
andsel Apr 22, 2024
2458d58
Smoother rewording
andsel Apr 23, 2024
61beedc
Removed double anchor
andsel Apr 24, 2024
c827413
Apply suggestions from code review
andsel May 2, 2024
109d698
Integrate great phrasing and wording suggestions
andsel May 13, 2024
82e9755
Fixed description
andsel May 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
28 changes: 28 additions & 0 deletions docs/static/config-details.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,34 @@ 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]]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should better highlight this somehow. The use of this setting completely changes the way Logstash works. Also, it would give us the ability to better understand Logstash when troubleshooting.

However, the direct result of this is that will completely impact/affect JVM Heap sizing. So I propose we:

  1. Bring some more visibility into this setting, maybe say this will be the default in future versions of Logstash.
  2. Tell users that this is a recommended setting to be set?
  3. And, in the memory size/performance tuning sections to have references to this setting being turned on??

Any thoughts?

@jsvd @flexitrev

===== Troubleshooting out of memory errors in off-heap space: `pipeline.buffer.type`
andsel marked this conversation as resolved.
Show resolved Hide resolved

Plugins such as {agent}, {beats}, TCP, and HTTP inputs, use direct memory to get
better performance when interacting with the network stack.
andsel marked this conversation as resolved.
Show resolved Hide resolved
Under certain circumstances of heavy load, the direct memory space can be exhausted and lead to Out of Memory (OOM) errors in off-heap space.
andsel marked this conversation as resolved.
Show resolved Hide resolved

{ls} provides a `pipeline.buffer.type` setting in <<logstash-settings-file>> that can help you investigate and troubleshoot Out of Memory errors.
This setting lets you control where to allocate memory buffers for plugins that use them.
It is set to `direct` by default, but you can change it to `heap` to use Java heap space instead.
When set to `heap`, all IO buffer allocations used by plugins are configured to **prefer** the
Java Heap instead of direct memory.
andsel marked this conversation as resolved.
Show resolved Hide resolved

In the case of an out-of-memory condition, you have a better report for investigating memory leaks.
andsel marked this conversation as resolved.
Show resolved Hide resolved

Moving the allocation of IO buffers to Java heap generally doesn't impact the performance in terms of requests per second.
However, every event's payload has to be converted from raw bytes in direct memory space to {ls} events,
which are Java objects that live in the heap.

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.
andsel marked this conversation as resolved.
Show resolved Hide resolved

[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.
--

andsel marked this conversation as resolved.
Show resolved Hide resolved
[[memory-size-calculation]]
===== Memory sizing

Expand Down
2 changes: 1 addition & 1 deletion docs/static/settings-file.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -366,5 +366,5 @@ 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.
Default to `direct`, optionally can be switched to `heap` to select Java heap space.
andsel marked this conversation as resolved.
Show resolved Hide resolved
| `direct`
| `direct` Check out <<reducing-off-heap-usage>> for more info.
jsvd marked this conversation as resolved.
Show resolved Hide resolved
|=======================================================================