README.md
1recon
2=====
3
4Recon wants to be a set of tools usable in production to diagnose Erlang problems or inspect production environment safely.
5
6To build the library:
7
8 rebar3 compile
9
10Documentation for the library can be obtained at http://ferd.github.io/recon/
11
12It is recommended that you use tags if you do not want bleeding edge and development content for this library.
13
14Current Status
15--------------
16
17[](https://github.com/ferd/recon)
18
19Versions supported: OTP-18 and up. Support of OTP-17 down to R15B02 is best effort. Builds with Rebar3 require OTP-18.3 and up because that's what the build tools support. Testing may eventually clamp up to OTP-supported releases (current and the two prior).
20
21Changelog
22---------
23
24Branches are organized by version. `master` contains the bleeding edge, `2.x`
25contains all stable changes up to the latest release of v2, and `1.x` contains
26all stable changes of the first version of Recon.
27
28*2.x*
29
30- 2.5.2
31 - [Increase Dialyzer strictness](https://github.com/ferd/recon/pull/88)
32 - [Accumulate all block entries in `format_blocks`](https://github.com/ferd/recon/pull/83)
33 - [option `io_server` can also be an `atom()` in traces doc](https://github.com/ferd/recon/pull/80)
34- 2.5.1
35 - Fix support for extra messages in traces (thanks to Péter Gömöri)
36 - Fix some typespecs for match specs (thanks to @chenduo)
37 - Support OTP-23 change of format in allocator blocks related to carrier migration support
38- 2.5.0
39 - Optional formatting of records in traces (thanks to @bartekgorny)
40 - Basic support for OTP-22 in `recon_alloc` (base handling of `foreign_blocks` type)
41- 2.4.0
42 - Optional formatting of records in traces (thanks to @bartekgorny)
43- 2.3.6
44 - Adapting for OTP-21. Includes the 'deprecation' of `recon:files/0`
45 since OTP-21 no longer supports listing all file descriptors, and
46 removing `error_logger_queue_len` from node stats since a new
47 logging mechanism was introduced in-process instead.
48- 2.3.5
49 - fixing timefold's first iteration to prevent errors at call-site
50 by sleeping before sampling
51- 2.3.4
52 - fixing edoc tag that broke some downstream packaging attempts
53- 2.3.3
54 - fixing `bin_leak` arith errors
55 - fixes to `recon_alloc:allocators/1` (incl. R16 compatibility)
56 - fix errors in scheduler wall time calculations
57 - `term_to_pid` supports binaries
58- 2.3.2
59 - Allow the `return_to` option in `recon_trace`
60 - More efficient sorting function for procs and ports attributes
61 (thanks to @zhongwencool and @pichi)
62 - Allow the usage of `return_trace` in `recon_trace:calls/2-3` instead
63 of `fun(_) -> return_trace() end`.
64- 2.3.1
65 - Updated `app_deps` script to run with rebar3 dependencies
66 - Minor docs update
67- 2.3.0
68 - Doc made clearer around semantics of `recon:proc_count` and
69 `recon:proc_window`.
70 - Fix doc typos
71 - Fix potential race condition on waiting for death of tracing process
72 - Add an option which allows sending tracing output somewhere other than
73 group_leader() (thanks @djnym)
74 - Add ability to pass custom formatter function when tracing (thanks @iilyak)
75- 2.2.1
76 - Fixing type specs for `recon:port_types/0` and `recon_lib:count/1`,
77 thanks to @lucafavatella
78 - Minor documentation fixes.
79- 2.2.0:
80 - Adding scheduler info metrics to get a more accurate picture than what
81 top and CPU gives.
82 - Broadening `recon_trace:calls/2` interface to allow multiple match specs,
83 which was currently only allowed for `calls/3`.
84 - Support for `mbcs_pool` data in `erts_alloc`, and some internal refactoring,
85 thanks to Lukas Larsson.
86- 2.1.2:
87 - Fixing tests for R15B02 and up
88 - Fixing a backwards compatibility for R15B03 on `recon_alloc` operations
89 with dumps on disk
90- 2.1.1:
91 - Renaming `recon_trace:mfa()` type to `recon_trace:tspec()` to avoid
92 issues in older Erlang versions regarding redefining an existing type
93 (Thanks Roberto Aloi)
94- 2.1.0:
95 - Adding `recon_trace` script to allow safe tracing of function calls
96 on production nodes.
97 - Adding `queue_fun.awk` script to inspect running functions of processes
98 with large mailboxes in a crash dump.
99- 2.0.2:
100 - Preventing crashes in `recon_alloc` when certain expected allocators
101 do not return results (Thanks to Michal Ptaszek)
102- 2.0.1:
103 - Add support for R16B03 in `recon_alloc`.
104- 2.0.0:
105 - Test suite added
106 - Major rewrite of `recon_alloc`, thanks to Lukas Larsson. Things that changed include:
107 - `average_sizes/0` is renamed `average_block_sizes/1` and now takes
108 the keywords `current` and `max`.
109 - Documentation updates.
110 - `memory/1` has new options in `allocated_types` and `allocated_instances`.
111 - `memory/2` has been added, which allows to choose between `current` and
112 `max` values. `memory(Term)` is made equivalent to `memory(Term, current)`.
113 - Allow `sbcs_to_mbcs/0` to take the arguments `current` and `max`.
114 - Added unit conversion function `set_unit/1`, which allows to get the
115 `recon_alloc` results in bytes (default), kilobytes, megabytes, and
116 gigabytes, to help with readability.
117 - Updated the internal rebar version, if anybody were to use it.
118 - `recon:port_info/1` no longer includes the `parallelism` option by default
119 within the `meta` category as this would hurt backwards compatibility on
120 some installations.
121 - `recon:get_state/2` is added in order to specify timeouts.
122 `recon:get_state/1` keeps its 5000 milliseconds timeout.
123 - Addition of a fake attribute called `binary_memory`, which is callable in
124 `recon:info/2,4`, `recon:proc_count/2`, and `recon:proc_window/3`. This
125 attribute allows to fetch the amount of memory used by refc binaries for
126 a process, and to sort by that value for counts and windows.
127
128
129*1.x*
130
131- 1.2.0:
132 - add `recon_alloc:snapshot*` functions, which allow memory allocation
133 snapshots to be taken, saved on disk, reloaded, and analyzed on-demand.
134 Thanks to Lukas Larsson for this functionality.
135 - remove `parallelism` data from `port_info` for better OTP backwards
136 compatibility with little loss of information.
137- 1.1.0:
138 - add `recon_lib:term_to_port` to convert a string back to a
139 usable port.
140 - add `recon:port_info/1` and `recon:port_info/2`
141 - add `recon_alloc` module
142- 1.0.0: add `info/2` and `info/4`. The `memory` info type thus gets renamed
143 to `memory_used`, in order to avoid conflicts when picking between a type
144 and a specific process attribute. Types exported by the module also get
145 updated.
146- 0.4.2: extended `app_deps.erl` to read apps/ directories for releases
147- 0.4.1: fixed bug where nodes with lots of processes could see the GC call
148 fail if said processes failed between long calls within the `bin_leak`
149 function call.
150- 0.4.0: fixed bug where nodes with lots of processes or ports could see their
151 count or window functions fail because a process or socket closed between the
152 time the function started and before it finished. This ends up changing the
153 API in `recon_lib` for the window and count functions that take a specific
154 pid as an argument.
155- 0.3.1: factored out some logic from `recon:info/1` into `recon_lib:term_to_pid`
156 and allowed arbitrary terms to be used for pids in `recon:get_state/1`.
157
){kind=link}