Skip to content

Commit

Permalink
Bump version number to 0.2.7
Browse files Browse the repository at this point in the history
  • Loading branch information
chrzaszcz committed Aug 1, 2024
1 parent 5942933 commit 5a87f52
Show file tree
Hide file tree
Showing 2 changed files with 10 additions and 10 deletions.
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ You can follow these examples on your own - just call `rebar3 as test shell` in

The first thing to do is to start the tracer with `tr:start/0`.

There is also `tr:start/1`, which accepts a [map of options](https://hexdocs.pm/erlang_doctor/0.2.6/tr.html#t:init_options/0), including:
There is also `tr:start/1`, which accepts a [map of options](https://hexdocs.pm/erlang_doctor/0.2.7/tr.html#t:init_options/0), including:

- `tab`: collected traces are stored in an ETS table with this name (default: `trace`),
- `limit`: maximum number of traces in the table - when it is reached, tracing is stopped (default: no limit).
Expand Down Expand Up @@ -93,7 +93,7 @@ If you want to trace selected processes instead of all of them, you can use `tr:
tr:trace([Module1, Module2], [Pid1, Pid2]).
```

The `tr:trace/1` function accepts a [map of options](https://hexdocs.pm/erlang_doctor/0.2.6/tr.html#t:trace_options/0), which include:
The `tr:trace/1` function accepts a [map of options](https://hexdocs.pm/erlang_doctor/0.2.7/tr.html#t:trace_options/0), which include:

- `modules`: a list of module names or `{Module, Function, Arity}` tuples. The list is empty by default.
- `pids`: a list of Pids of processes to trace, or the atom `all` (default) to trace all processes.
Expand Down Expand Up @@ -130,7 +130,7 @@ tr:trace(Modules), timer:sleep(1000), tr:stop_tracing().
## Debugging: data analysis

The collected traces are stored in an ETS table (default name: `trace`).
They are stored as [`tr`](https://hexdocs.pm/erlang_doctor/0.2.6/tr.html#t:tr/0) records with the following fields:
They are stored as [`tr`](https://hexdocs.pm/erlang_doctor/0.2.7/tr.html#t:tr/0) records with the following fields:

- `index`: trace identifier, auto-incremented for each received trace.
- `pid`: process identifier associated with the trace.
Expand Down Expand Up @@ -186,7 +186,7 @@ Use `tr:select/0` to select all collected traces.
```

The `tr:select/1` function accepts a fun that is passed to `ets:fun2ms/1`.
This way you can limit the selection to specific items and select only some fields from the [`tr`](https://hexdocs.pm/erlang_doctor/0.2.6/tr.html#t:tr/0) record:
This way you can limit the selection to specific items and select only some fields from the [`tr`](https://hexdocs.pm/erlang_doctor/0.2.7/tr.html#t:tr/0) record:

```erlang
7> tr:select(fun(#tr{event = call, data = [N]}) -> N end).
Expand Down Expand Up @@ -323,15 +323,15 @@ The third possibility is `output => longest` which does the opposite of pruning,
ts = 1705475521743239,info = no_info}]]
```

Possible [options](https://hexdocs.pm/erlang_doctor/0.2.6/tr.html#t:tb_options/0) for `tr:tracebacks/2` include:
Possible [options](https://hexdocs.pm/erlang_doctor/0.2.7/tr.html#t:tb_options/0) for `tr:tracebacks/2` include:

- `tab` is the table or list which is like the second argument of `tr:filter/2`,
- `output` - `shortest` (default), `all`, `longest` - see above.
- `format` - `list` (default), `tree` - returns a call tree instead of a list of tracebacks. Trees don't distinguish between `all` and `longest` output formats.
- `order` - `top_down` (default), `bottom_up` - call order in each tracaback; only for the `list` format.
- `limit` - positive integer or `infinity` (default) - limits the number of matched traces. The actual number of tracebacks returned can be smaller unless `output => all`

There are also functions `tr:traceback/1` and `tr:traceback/2`. They set `limit` to one and return only one trace if it exists. The options for `tr:traceback/2` are the same as for `tr:traceback/2` except `limit` and `format`. Additionally, it is possible to pass a [`tr`](https://hexdocs.pm/erlang_doctor/0.2.6/tr.html#t:tr/0) record (or an index) directly to `tr:traceback/1` to obtain the traceback for the provided trace event.
There are also functions `tr:traceback/1` and `tr:traceback/2`. They set `limit` to one and return only one trace if it exists. The options for `tr:traceback/2` are the same as for `tr:traceback/2` except `limit` and `format`. Additionally, it is possible to pass a [`tr`](https://hexdocs.pm/erlang_doctor/0.2.7/tr.html#t:tr/0) record (or an index) directly to `tr:traceback/1` to obtain the traceback for the provided trace event.

### Trace ranges for filtered traces: `ranges`

Expand All @@ -355,13 +355,13 @@ To get a list of traces between each matching call and the corresponding return,
data = 1,ts = 1705475521750453,info = no_info}]]
```

There is also `tr:ranges/2` - it accepts a [map of options](https://hexdocs.pm/erlang_doctor/0.2.6/tr.html#t:range_options/0), including:
There is also `tr:ranges/2` - it accepts a [map of options](https://hexdocs.pm/erlang_doctor/0.2.7/tr.html#t:range_options/0), including:

- `tab` is the table or list which is like the second argument of `tr:filter/2`,
- `max_depth` is the maximum depth of nested calls. A message event also adds 1 to the depth.
You can use `#{max_depth => 1}` to see only the top-level call and the corresponding return.

There are two additional function: `tr:range/1` and `tr:range/2`, which return only one range if it exists. It is possible to pass a [`tr`](https://hexdocs.pm/erlang_doctor/0.2.6/tr.html#t:tr/0) record or an index to `tr:range/1` as well.
There are two additional function: `tr:range/1` and `tr:range/2`, which return only one range if it exists. It is possible to pass a [`tr`](https://hexdocs.pm/erlang_doctor/0.2.7/tr.html#t:tr/0) record or an index to `tr:range/1` as well.

### Calling function from a trace: `do`

Expand Down Expand Up @@ -494,7 +494,7 @@ and `Count` is the number of times the tree repeated. The list is sorted by `Tim
In the example above `fib(2)` was called twice and `fib(1)` was called 3 times,
what already shows that the recursive implementation is suboptimal.

There is also `tr:top_call_trees/1`, which takes a [map of options](https://hexdocs.pm/erlang_doctor/0.2.6/tr.html#t:top_call_trees_options/0), including:
There is also `tr:top_call_trees/1`, which takes a [map of options](https://hexdocs.pm/erlang_doctor/0.2.7/tr.html#t:top_call_trees_options/0), including:
- `output` is `reduced` by default, but it can be set to `complete` where subtrees of already listed trees are also listed.
- `min_count` is the minimum number of times a tree has to occur to be listed, the default is 2.
- `min_time` is the minimum accumulated time for a tree, by default there is no minimum.
Expand Down
2 changes: 1 addition & 1 deletion src/erlang_doctor.app.src
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{application, erlang_doctor,
[{description, "Lightweight tracing, debugging and profiling utility for Erlang"},
{vsn, "0.2.6"},
{vsn, "0.2.7"},
{registered, []},
{mod, { erlang_doctor_app, []}},
{applications,
Expand Down

0 comments on commit 5a87f52

Please sign in to comment.