View Source ZenMonitor.Truncator (ZenMonitor v2.0.1)
ZenMonitor.Truncator is used to truncate error messages to prevent error expansion issues.
Error Expansion
At the core of ZenMonitor is a system that collects local :DOWN
messages, batches them up and
relays them in bulk. This opens up a failure mode where each :DOWN
message individually is
deliverable, but the bulk summary grows to an unsupportable size due to the aggregation of large
reason payloads.
If no truncation is performed then the payload can cause instability on the sender or the receiver side.
Truncation Behavior
ZenMonitor will truncate error reasons if they exceed a certain size to prevent Error Expansion from breaking either the sender or the receiver.
Truncation is performed recursively on the term up to a maximum depth which can be provided to
the ZenMonitor.Truncator.truncate/2
function.
See below for an explanation of how the Truncator treats different values
Pass-Through Values
There are a number of types that the Truncator will pass through unmodified.
- Atoms
- Pids
- Numbers
- References
- Ports
- Binaries less than
@max_binary_size
(see the Binary section below for more information)
Binaries
There is a configurable value @max_binary_size
any binary encountered over this size will be
truncated to @max_binary_size - 3
and a trailing '...' will be appended to indicate the value
has been truncated. This guarantees that no binary will appear in the term with size greater
than @max_binary_size
Tuples
0-tuples through 4-tuples will be passed through with their interior terms recursively
truncated. If a tuple has more than 4 elements, it will be replaced with the :truncated
atom.
Lists
Lists with 0 to 4 elements will be passed through with each element recursively truncated. If a
list has more than 4 elements, it will be replaced with the :truncated
atom.
Maps
Maps with a map_size/1
less than 5 will be passed through with each value recursively
truncated. If a map has a size of 5 or greater then it will be replaced with the :truncated
atom.
Structs
Structs are converted into maps and then the map rules are applied, they are then converted back
into structs. The effect is that a Struct with 4 fields or fewer will be retained (with all
values recursively truncated) while Structs with 5 or more fields will be replaced with the
:truncated
atom.
Recursion Limit
The Truncator will only descend up to the depth
argument passed into
ZenMonitor.Truncator.truncate/2
, regardless of the value, if the recursion descends deeper
than this value then the :truncated
atom will be used in place of the original value.
Configuration
ZenMonitor.Truncator
exposes two different configuration options, and allows for one call-site
override. The configuration options are evaluated at compile time, changing these values at
run-time (through a facility like Application.put_env/3
) will have no effect.
Both configuration options reside under the :zen_monitor
app key.
:max_binary_size
is size in bytes over which the Truncator will truncate the binary. The
largest binary returned by the Truncator is defined to be the max_binary_size + 3, this is
because when the truncator Truncator a binary it will append ...
to indicate that truncation
has occurred.
:truncation_depth
is the default depth that the Truncator will recursively descend into the
term to be truncated. This is the value used for ZenMonitor.Truncator.truncate/2
if no second
argument is provided, providing a call-site second argument will override this configuration.
Link to this section Summary
Functions
Truncates a term to a given depth
Link to this section Functions
Specs
truncate(term(), depth :: pos_integer()) :: term()
Truncates a term to a given depth
See the module documentation for more information about how truncation works.