This new name better reflects what this option actually does: it allows
to flush a Buffer even if there were just added fields or tags. A tryely
empty Buffer, i.e., one which has neither added messages, fields, or
tags is never flushed.
This field is only relevant when actually sending JSON to Logstash.
Other formats don't need it. It is thus more desireable to only include
this field in a specific logstash JSON encoder.
Most of the time, these methods should be used. They are only required
for special cases where the Buffer needs to be flushed later than when
its poped. In this case, special precautions need to be made to ensure
that the Buffer is always reliably poped and flushed to avoid loosing
logs.
With this move, we can also optimize the sinplest case where there are
no fields or tags on the Buffer and no defines default_fields or
default_tags on the Sink. In that case, we don't need to merge them,
avoiding the creation of several unecessary objects on Buffer flush.
Since the fields are (through the thread-local BufferStack) only ever
accessed from a single Thread, there is no need to accept the additional
locking overhead of the Concurrent raw values.
We can just use simple Hashes and Arrays here for higher performance.
Using the core `NotInmplementedError` is not desireable since its
documentation includes:
> Note that if `fork` raises a `NotImplementedError`, then
> `respond_to?(:fork)` returns `false`.
Since we are responding to the method but still raise an error, our
usage of the exception does not fulfill its documentation.
A custom error instead of a default `NoMethodError` is still desireable
since it significantly helps with debugging. With a different Exception,
we make it clear that a method is expected to be there and just wasn't
implemented by a subclass as opposed to the caller just using an object
wrong and calling entirely unexpected methods on it.
During normal operation, the Flows will rescue all exceptions and log
them to the special error_flow. By default, we will write JSON logs to
STDERR.
The log location and format can either be change globally by setting (or
changing) the Rackstash.error_flow or for each Flow for a Logger
individually by setting Flow#error_flow.
These methods do not rescue any thrown errors. The usual loggers will
always want to use the non-bang methods which rescue errors and attempt
to log them.
A single BufferStack object is only ever accessed by a single thread.
This is guaranteed by the Logger. Exceptions to the rule are not special
enough to break the rules.
The optional keyword arguments are already cleaned by the keyword splat
in BufferStack#push. They are automatically unsplatted when calling
Buffer#initialize anyway.
