Skip to content

Commit f779c26

Browse files
ferdferd
committed
Switch main documentation to ex_doc format
This brings recon to a more modern standard. The old edoc format and site are still available, but this should bring everything up to date. Also fixes a few linking issues pointed out by ex_doc and updates the CI flow.
1 parent cf5bfc2 commit f779c26

12 files changed

+337
-150
lines changed

‎.github/workflows/ci.yml

+2-1
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,12 @@ jobs:
1515
image: erlang:${{matrix.otp_vsn}}
1616
strategy:
1717
matrix:
18-
otp_vsn: ['18.3', '19.3', '20.3', '21.3', '22.3', '23.3', '24.0']
18+
otp_vsn: ['18.3', '19.3', '20.3', '21.3', '22.3', '23.3', '24.0', '25.0']
1919
os: [ubuntu-latest]
2020
steps:
2121
- uses: actions/checkout@v2
2222
- run: rebar3 edoc
23+
- run: rebar3 ex_doc
2324
- run: rebar3 eunit
2425
- run: rebar3 ct
2526
- run: rebar3 dialyzer

‎.gitignore

+4-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,10 @@ erl_crash.dump
1212
/doc/edoc-info
1313
/doc/erlang.png
1414
/doc/stylesheet.css
15-
/site/*.html
15+
/doc/.build
16+
/doc/*.epub
17+
/doc/dist
18+
/site/*
1619
.rebar/
1720
_build/
1821

‎CHANGELOG.md

+164
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
Changelog
2+
=========
3+
4+
Branches are organized by version. `master` contains the bleeding edge, `2.x`
5+
contains all stable changes up to the latest release of v2, and `1.x` contains
6+
all stable changes of the first version of Recon.
7+
8+
## 2.5.3 (unpublished)
9+
- [Handle dead processes in `recon:info/2` types and edge cases](https://github.com/ferd/recon/pull/97)
10+
- Reworking documentation structure to support `ex_doc` and fit in with hex standard
11+
12+
## 2.5.2
13+
- [Increase Dialyzer strictness](https://github.com/ferd/recon/pull/88)
14+
- [Accumulate all block entries in `format_blocks`](https://github.com/ferd/recon/pull/83)
15+
- [option `io_server` can also be an `atom()` in traces doc](https://github.com/ferd/recon/pull/80)
16+
17+
## 2.5.1
18+
- Fix support for extra messages in traces (thanks to Péter Gömöri)
19+
- Fix some typespecs for match specs (thanks to @chenduo)
20+
- Support OTP-23 change of format in allocator blocks related to carrier migration support
21+
22+
## 2.5.0
23+
- Optional formatting of records in traces (thanks to @bartekgorny)
24+
- Basic support for OTP-22 in `recon_alloc` (base handling of `foreign_blocks` type)
25+
26+
## 2.4.0
27+
- Optional formatting of records in traces (thanks to @bartekgorny)
28+
29+
## 2.3.6
30+
- Adapting for OTP-21. Includes the 'deprecation' of `recon:files/0`
31+
since OTP-21 no longer supports listing all file descriptors, and
32+
removing `error_logger_queue_len` from node stats since a new
33+
logging mechanism was introduced in-process instead.
34+
35+
## 2.3.5
36+
- fixing timefold's first iteration to prevent errors at call-site
37+
by sleeping before sampling
38+
39+
## 2.3.4
40+
- fixing edoc tag that broke some downstream packaging attempts
41+
42+
## 2.3.3
43+
- fixing `bin_leak` arith errors
44+
- fixes to `recon_alloc:allocators/1` (incl. R16 compatibility)
45+
- fix errors in scheduler wall time calculations
46+
- `term_to_pid` supports binaries
47+
48+
## 2.3.2
49+
- Allow the `return_to` option in `recon_trace`
50+
- More efficient sorting function for procs and ports attributes
51+
(thanks to @zhongwencool and @pichi)
52+
- Allow the usage of `return_trace` in `recon_trace:calls/2-3` instead
53+
of `fun(_) -> return_trace() end`.
54+
55+
## 2.3.1
56+
- Updated `app_deps` script to run with rebar3 dependencies
57+
- Minor docs update
58+
59+
## 2.3.0
60+
- Doc made clearer around semantics of `recon:proc_count` and
61+
`recon:proc_window`.
62+
- Fix doc typos
63+
- Fix potential race condition on waiting for death of tracing process
64+
- Add an option which allows sending tracing output somewhere other than
65+
group_leader() (thanks @djnym)
66+
- Add ability to pass custom formatter function when tracing (thanks @iilyak)
67+
68+
## 2.2.1
69+
- Fixing type specs for `recon:port_types/0` and `recon_lib:count/1`,
70+
thanks to @lucafavatella
71+
- Minor documentation fixes.
72+
73+
## 2.2.0
74+
- Adding scheduler info metrics to get a more accurate picture than what
75+
top and CPU gives.
76+
- Broadening `recon_trace:calls/2` interface to allow multiple match specs,
77+
which was currently only allowed for `calls/3`.
78+
- Support for `mbcs_pool` data in `erts_alloc`, and some internal refactoring,
79+
thanks to Lukas Larsson.
80+
81+
## 2.1.2
82+
- Fixing tests for R15B02 and up
83+
- Fixing a backwards compatibility for R15B03 on `recon_alloc` operations
84+
with dumps on disk
85+
86+
## 2.1.1
87+
- Renaming `recon_trace:mfa()` type to `recon_trace:tspec()` to avoid
88+
issues in older Erlang versions regarding redefining an existing type
89+
(Thanks Roberto Aloi)
90+
91+
## 2.1.0
92+
- Adding `recon_trace` script to allow safe tracing of function calls
93+
on production nodes.
94+
- Adding `queue_fun.awk` script to inspect running functions of processes
95+
with large mailboxes in a crash dump.
96+
97+
## 2.0.2
98+
- Preventing crashes in `recon_alloc` when certain expected allocators
99+
do not return results (Thanks to Michal Ptaszek)
100+
101+
## 2.0.1
102+
- Add support for R16B03 in `recon_alloc`.
103+
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+
## 1.2.0
129+
- add `recon_alloc:snapshot*` functions, which allow memory allocation
130+
snapshots to be taken, saved on disk, reloaded, and analyzed on-demand.
131+
Thanks to Lukas Larsson for this functionality.
132+
- remove `parallelism` data from `port_info` for better OTP backwards
133+
compatibility with little loss of information.
134+
135+
## 1.1.0
136+
- add `recon_lib:term_to_port` to convert a string back to a
137+
usable port.
138+
- add `recon:port_info/1` and `recon:port_info/2`
139+
- add `recon_alloc` module
140+
141+
## 1.0.0
142+
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+
147+
## 0.4.2
148+
- extended `app_deps.erl` to read apps/ directories for releases
149+
150+
## 0.4.1
151+
- fixed bug where nodes with lots of processes could see the GC call
152+
fail if said processes failed between long calls within the `bin_leak`
153+
function call.
154+
155+
## 0.4.0
156+
- fixed bug where nodes with lots of processes or ports could see their
157+
count or window functions fail because a process or socket closed between the
158+
time the function started and before it finished. This ends up changing the
159+
API in `recon_lib` for the window and count functions that take a specific
160+
pid as an argument.
161+
162+
## 0.3.1
163+
- factored out some logic from `recon:info/1` into `recon_lib:term_to_pid`
164+
and allowed arbitrary terms to be used for pids in `recon:get_state/1`.

‎LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Copyright (c) 2012-2017, Frédéric Trottier-Hébert
1+
Copyright (c) 2012-2023, Fred Hebert
22
All rights reserved.
33

44
Redistribution and use in source and binary forms, with or without modification,

‎README.md

-139
Original file line numberDiff line numberDiff line change
@@ -17,142 +17,3 @@ Current Status
1717
[![Build Status](https://github.com/ferd/recon/workflows/build/badge.svg)](https://github.com/ferd/recon)
1818

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

‎doc/overview.edoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
@title Recon Application
22
@author Fred Hebert <[email protected]>
33
[http://ferd.ca/]
4-
@copyright 2012-2021 Fred Hebert (BSD 3-Clause License)
4+
@copyright 2012-2023 Fred Hebert (BSD 3-Clause License)
55

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

‎docsite.erl

+8-2
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@
1212
-define(DOCPATH, "doc/").
1313
-define(SITEPATH, "site/").
1414

15-
main() -> main([]).
15+
main() -> main(["ex_doc"]).
1616

17-
main(_) ->
17+
main(["edoc"]) ->
1818
ok = filelib:ensure_dir(?SITEPATH), % output directory
1919
Output = os:cmd("rebar3 edoc"), % build docs
2020
{match, _} = re:run(Output, "Running edoc"),
@@ -28,6 +28,12 @@ main(_) ->
2828
end,
2929
[Pre,content(File),Post])
3030
|| File <- [Overview|Modules]],
31+
halt(0);
32+
main(_) ->
33+
ok = filelib:ensure_dir(?SITEPATH), % output directory
34+
Output = os:cmd("rebar3 ex_doc"), % build docs
35+
{match, _} = re:run(Output, "Running ex_doc"),
36+
os:cmd("cp -r " ++ ?DOCPATH ++ " " ++ ?SITEPATH),
3137
halt(0).
3238

3339
content(File) ->

0 commit comments

Comments
 (0)