aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src
diff options
context:
space:
mode:
authorLukas Larsson <[email protected]>2016-05-27 09:34:25 +0200
committerLukas Larsson <[email protected]>2016-05-27 09:34:25 +0200
commit3f2eea83dd133c597580d7c2b5056bc90219d025 (patch)
treef46ad339fc2b21f3bd0c1260b06e218ebd4550fb /erts/doc/src
parentea8064b1bbda0ef59420ec8a805f3ee52630d704 (diff)
parentd9e0f376b36baa5453717606f373daa5b7a1b0aa (diff)
downloadotp-3f2eea83dd133c597580d7c2b5056bc90219d025.tar.gz
otp-3f2eea83dd133c597580d7c2b5056bc90219d025.tar.bz2
otp-3f2eea83dd133c597580d7c2b5056bc90219d025.zip
Merge branch 'lukas/erts/tracing/tracer-move-extra-to-map/OTP-10267'
* lukas/erts/tracing/tracer-move-extra-to-map/OTP-10267: runtime_tools: Fix erl_tracer testcases runtime_tools: Fix documentation for dbg:p erts: Move tracer SecondTraceTerm to Opts map
Diffstat (limited to 'erts/doc/src')
-rw-r--r--erts/doc/src/erl_tracer.xml96
1 files changed, 45 insertions, 51 deletions
diff --git a/erts/doc/src/erl_tracer.xml b/erts/doc/src/erl_tracer.xml
index d4c8bbad31..7841fdfd63 100644
--- a/erts/doc/src/erl_tracer.xml
+++ b/erts/doc/src/erl_tracer.xml
@@ -67,7 +67,7 @@
<desc>
<p>The different trace tags that the tracer will be called with.
Each trace tag is described in greater detail in
- <seealso marker="#Module:trace/6">Module:trace/6</seealso>
+ <seealso marker="#Module:trace/5">Module:trace/5</seealso>
</p>
</desc>
</datatype>
@@ -84,14 +84,18 @@
<p>The options for the tracee.</p>
<taglist>
<tag><c>timestamp</c></tag>
- <item>If not set to <c>undefined</c>, the tracer has been requested to
- include a timestamp.</item>
+ <item>If set the tracer has been requested to include a timestamp.</item>
+ <tag><c>extra</c></tag>
+ <item>If set the tracepoint has included additonal data about
+ the trace event. What the additional data is depends on which
+ <c>TraceTag</c> has been triggered. The <c>extra</c> trace data
+ corresponds to the fifth elemnt in the trace tuples described in
+ <seealso marker="erlang#trace_3_trace_messages">erlang:trace/3</seealso>.</item>
<tag><c>match_spec_result</c></tag>
- <item>If not set to <c>true</c>, the tracer has been requested to
- include the output of a match specification that was run.</item>
+ <item>If set the tracer has been requested to include the output
+ of a match specification that was run.</item>
<tag><c>scheduler_id</c></tag>
- <item>Set to a number if the scheduler id is to be included by the tracer.
- Otherwise it is set to <c>undefined</c>.</item>
+ <item>Set the scheduler id is to be included by the tracer.</item>
</taglist>
</desc>
</datatype>
@@ -115,23 +119,23 @@
<taglist>
<tag><seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso></tag>
<item>Mandatory</item>
- <tag><seealso marker="#Module:trace/6"><c>Module:trace/6</c></seealso></tag>
+ <tag><seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso></tag>
<item>Mandatory</item>
<tag><seealso marker="#Module:enabled_procs/3"><c>Module:enabled_procs/3</c></seealso></tag>
<item>Optional</item>
- <tag><seealso marker="#Module:trace_procs/6"><c>Module:trace_procs/6</c></seealso></tag>
+ <tag><seealso marker="#Module:trace_procs/5"><c>Module:trace_procs/5</c></seealso></tag>
<item>Optional</item>
<tag><seealso marker="#Module:enabled_ports/3"><c>Module:enabled_ports/3</c></seealso></tag>
<item>Optional</item>
- <tag><seealso marker="#Module:trace_ports/6"><c>Module:trace_ports/6</c></seealso></tag>
+ <tag><seealso marker="#Module:trace_ports/5"><c>Module:trace_ports/5</c></seealso></tag>
<item>Optional</item>
<tag><seealso marker="#Module:enabled_running_ports/3"><c>Module:enabled_running_ports/3</c></seealso></tag>
<item>Optional</item>
- <tag><seealso marker="#Module:trace_running_ports/6"><c>Module:trace_running_ports/6</c></seealso></tag>
+ <tag><seealso marker="#Module:trace_running_ports/5"><c>Module:trace_running_ports/5</c></seealso></tag>
<item>Optional</item>
<tag><seealso marker="#Module:enabled_running_procs/3"><c>Module:enabled_running_procs/3</c></seealso></tag>
<item>Optional</item>
- <tag><seealso marker="#Module:trace_running_procs/6"><c>Module:trace_running_procs/6</c></seealso></tag>
+ <tag><seealso marker="#Module:trace_running_procs/5"><c>Module:trace_running_procs/5</c></seealso></tag>
<item>Optional</item>
</taglist>
@@ -166,14 +170,13 @@
</desc>
</func>
<func>
- <name>Module:trace(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag">trace_tag()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -182,17 +185,17 @@
the <seealso marker="#Module:enabled/3">Module:enabled/3</seealso>
callback returned <c>trace</c>. In it any side effects needed by
the tracer should be done. The tracepoint payload is located in
- the <c>FirstTraceTerm</c> and <c>SecondTraceTerm</c>. The content
- of the TraceTerms depends on which <c>TraceTag</c> has been triggered.
- The <c>FirstTraceTerm</c> and <c>SecondTraceTerm</c> correspond to the
- fourth and fifth slot in the trace tuples described in
+ the <c>TraceTerm</c>. The content of the TraceTerm depends on which
+ <c>TraceTag</c> has been triggered.
+ The <c>TraceTerm</c> corresponds to the
+ fourth element in the trace tuples described in
<seealso marker="erlang#trace_3_trace_messages">erlang:trace/3</seealso>.
- If the tuple only has four elements, <c>SecondTraceTerm</c> will be
- <c>undefined</c>.</p>
+ If the trace tuple has five elements, the fifth element will be sent as
+ the <c>extra</c> value in the <c>Opts</c> maps.</p>
</desc>
</func>
<func>
- <name name="trace">Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, undefined, Opts) -> Result</name>
+ <name name="trace">Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, Opts) -> Result</name>
<fsummary>Check if a sequence trace event should be generated.</fsummary>
<type>
<v>TracerState = term()</v>
@@ -228,14 +231,13 @@
</func>
<func>
- <name>Module:trace_procs(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_procs">trace_tag()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -243,7 +245,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_procs/3">Module:enabled_procs/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_procs/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_procs/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -265,14 +267,13 @@
</func>
<func>
- <name>Module:trace_ports(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_ports">trace_tag()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -280,7 +281,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_ports/3">Module:enabled_ports/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_ports/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_ports/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -302,14 +303,13 @@
</func>
<func>
- <name>Module:trace_running_procs(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_running_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_running_procs">trace_tag_running_procs()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -317,7 +317,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_running_procs/3">Module:enabled_running_procs/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_running_procs/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_running_procs/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -339,14 +339,13 @@
</func>
<func>
- <name>Module:trace_running_ports(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_running_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_running_ports">trace_tag_running_ports()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -354,7 +353,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_running_ports/3">Module:enabled_running_ports/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_running_ports/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_running_ports/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -376,14 +375,13 @@
</func>
<func>
- <name>Module:trace_call(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_call(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_call">trace_tag_call()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -391,7 +389,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_call/3">Module:enabled_call/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_call/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_call/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -413,14 +411,13 @@
</func>
<func>
- <name>Module:trace_send(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_send(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_send">trace_tag_send()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -428,7 +425,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_send/3">Module:enabled_send/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_send/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_send/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -450,14 +447,13 @@
</func>
<func>
- <name>Module:trace_receive(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_receive(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_receive">trace_tag_receive()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -465,7 +461,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_receive/3">Module:enabled_receive/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_receive/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_receive/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -487,14 +483,13 @@
</func>
<func>
- <name>Module:trace_garbage_collection(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+ <name>Module:trace_garbage_collection(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
<fsummary>Check if a trace event should be generated.</fsummary>
<type>
<v>TraceTag = <seealso marker="#type-trace_tag_gc">trace_tag_gc()</seealso></v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
<v>FirstTraceTerm = term()</v>
- <v>SecondTraceTerm = term() | undefined</v>
<v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
<v>Result = ok</v>
</type>
@@ -502,7 +497,7 @@
<p>This callback will be called when a tracepoint is triggered and
the <seealso marker="#Module:enabled_garbage_collection/3">Module:enabled_garbage_collection/3</seealso>
callback returned <c>trace</c>.</p>
- <p>If <c>trace_garbage_collection/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+ <p>If <c>trace_garbage_collection/5</c> is not defined <c>trace/5</c> will be called instead.</p>
</desc>
</func>
@@ -543,7 +538,7 @@ ok
<pre>
-module(erl_msg_tracer).
--export([enabled/3, trace/6, load/0]).
+-export([enabled/3, trace/5, load/0]).
load() ->
erlang:load_nif("erl_msg_tracer", []).
@@ -551,7 +546,7 @@ load() ->
enabled(_, _, _) ->
error.
-trace(_, _, _,_, _, _) ->
+trace(_, _, _,_, _) ->
error.
</pre>
<p>erl_msg_tracer.c</p>
@@ -569,7 +564,7 @@ static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
static ErlNifFunc nif_funcs[] = {
{"enabled", 3, enabled},
- {"trace", 6, trace}
+ {"trace", 5, trace}
};
ERL_NIF_INIT(erl_msg_tracer, nif_funcs, load, NULL, upgrade, unload)
@@ -632,9 +627,8 @@ static ERL_NIF_TERM enabled(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
* argv[0]: TraceTag, should only be 'send'
* argv[1]: TracerState, process to send {argv[2], argv[4]} to
* argv[2]: Tracee
- * argv[3]: Message, ignored
- * argv[4]: Recipient
- * argv[5]: Options, ignored
+ * argv[3]: Recipient
+ * argv[4]: Options, ignored
*/
static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
{