@title Recon Application
@author Fred Hebert <mononcqc@ferd.ca>
  [http://ferd.ca/]
@copyright 2012-2023 Fred Hebert (BSD 3-Clause License)

@doc Recon is a library to be dropped into any other Erlang project,
to be used to assist DevOps people diagnose problems in production
nodes.

The source code can be obtained from <a href="https://github.com/ferd/recon">the github repo</a>.

Included modules are:

<dl>
    <dt>{@link recon}</dt>
    <dd>
        Main module, contains basic functionality to interact with
        the `recon' application. It includes functions to gather
        information about processes and the general state of the
        virtual machine, ports, and OTP behaviours running in the
        node. It also includes a few functions to facilitate RPC
        calls with distributed Erlang nodes.
    </dd>

    <dt>{@link recon_alloc}</dt>
    <dd>
        Regroups functions to deal with Erlang's memory allocators, or
        particularly, to try to present the allocator data in a way that
        makes it simpler to discover the presence of possible problems.
    </dd>

    <dt>{@link recon_lib}</dt>
    <dd>
        Regroups useful functionality used by {@link recon} when dealing
        with data from the node. Would be an interesting place to look
        if you were looking to extend Recon's functionality
    </dd>

    <dt>{@link recon_trace}</dt>
    <dd>
        Provides production-safe tracing facilities, to dig into the
        execution of programs and function calls as they are running.
    </dd>

    <dt>{@link recon_rec}</dt>
    <dd>
        An extension to recon_trace, enables printing out records in a more readable format
        based on known record definitions.
    </dd>
</dl>

This library contains few tests -- most of the functionality has been
tried directly in production instead, and for many Erlang installs, Recon
functionality should be safe to use directly in production, assuming there
is still memory left to be used in the node.

To help with regular DevOps tasks, a variety of scripts has also been included
in the repository's `script/' directory:

<dl>
    <dt>`app_deps.erl'</dt>
    <dd>
        Escript that relies on graphviz, and produces a dependency graph of all
        applications in the repository. The script can be run directly from an
        Erlang shell (if compiled), or as `escript app_deps.erl'.
    </dd>

    <dt>`erl_crashdump_analyzer.sh'</dt>
    <dd>
        Bash script to run on an Erlang crash dump as
        `./erl_crashdump_analyzer.sh <crashdump>' and will extract generic
        information that can be useful in determining the most common causes
        of node failure.
    </dd>

    <dt>`queue_fun.awk'</dt>
    <dd>
        Awk script to run on an Erlang Crash dump as
        `awk -v threshold=<queue size> -f queue_fun.awk <crashdump>' and will
        show what function processes with queue sizes larger or equal to
        `<queue size>' were operating at the time of the crash dump. May help
        find out if most processes were stuck blocking on a given function
        call while accumulating messages forever.
    </dd>
</dl>
@end
