From 4ec470dedb903e0113416edf3f590b85b1dedc9a Mon Sep 17 00:00:00 2001
From: Vladimir Gordeev <gordeev.vladimir.v@gmail.com>
Date: Thu, 15 Mar 2018 17:26:47 +0300
Subject: Tracing MatchSpec docs update

I was running this code in shell and expected it to take default `self()` meta tracer,
and start tracing `erlang:put/2`.

```
F = fun F() -> timer:sleep(5000), erlang:get(unique_field), erlang:put(unique_field, 123), F() end.
erlang:trace_pattern({erlang, put, 2}, [{['$1', '_'], [{'==', '$1', unique_field}], []}], [global]).
erlang:trace_pattern({erlang, get, 1}, [{['_'], [], [{trace, [], [call, timestamp]}]}], [meta]).
Pid = spawn(F).
```

But tracing didn't start:
```
6> flush().
Shell got {trace_ts,<0.70.0>,call,
                    {erlang,get,[unique_field]},
                    {1521,118606,753838}}
Shell got {trace_ts,<0.70.0>,call,
                    {erlang,get,[unique_field]},
                    {1521,118611,754798}}
Shell got {trace_ts,<0.70.0>,call,
                    {erlang,get,[unique_field]},
                    {1521,118616,755705}}
ok
7> erlang:trace_info(Pid, flags).
{flags,[]}
```

Turns out that I had false expectations, that `{trace, _, _}` would enable tracing on that process, inheriting meta tracer process as consumer of trace messages.

Instead it tried to take tracer from executing process (which is pointed out in docs). But there was none, so no tracing was started and flags were simply ignored (which is not that obvious from docs).

Updated docs to point out that there are cases when flags would be simply ignored, and no tracing would start.
---
 erts/doc/src/match_spec.xml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'erts/doc/src/match_spec.xml')

diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml
index 2a14f1e47b..644b989800 100644
--- a/erts/doc/src/match_spec.xml
+++ b/erts/doc/src/match_spec.xml
@@ -405,7 +405,8 @@
             <c><![CDATA[tracer]]></c>.</p>
           <p>If a tracer is specified in both lists, the tracer in the
             enable list takes precedence. If no tracer is specified, the same
-            tracer as the process executing the match specification is used.</p>
+            tracer as the process executing the match specification is used (not the meta tracer).
+            If that process doesn't have tracer either, then trace flags are ignored.</p>
           <p>When using a <seealso marker="erl_tracer">tracer module</seealso>,
             the module must be loaded before the match specification is
             executed. If it is not loaded, the match fails.</p>
-- 
cgit v1.2.3