aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erl_tracer.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/erl_tracer.xml')
-rw-r--r--erts/doc/src/erl_tracer.xml882
1 files changed, 507 insertions, 375 deletions
diff --git a/erts/doc/src/erl_tracer.xml b/erts/doc/src/erl_tracer.xml
index 7841fdfd63..131157eef8 100644
--- a/erts/doc/src/erl_tracer.xml
+++ b/erts/doc/src/erl_tracer.xml
@@ -29,487 +29,618 @@
<rev></rev>
</header>
<module>erl_tracer</module>
- <modulesummary>Erlang Tracer Behaviour</modulesummary>
+ <modulesummary>Erlang tracer behavior.</modulesummary>
<description>
- <p>A behaviour module for implementing the back end of the erlang
- tracing system. The functions in this module will be called whenever
- a trace probe is triggered. Both the <c>enabled</c> and <c>trace</c>
- functions are called in the context of the entity that triggered the
- trace probe.
- This means that the overhead by having the tracing enabled will be
- greatly effected by how much time is spent in these functions. So do as
- little work as possible in these functions.</p>
+ <p>This behavior module implements the back end of the Erlang
+ tracing system. The functions in this module are called whenever
+ a trace probe is triggered. Both the <c>enabled</c> and <c>trace</c>
+ functions are called in the context of the entity that triggered the
+ trace probe.
+ This means that the overhead by having the tracing enabled is
+ greatly effected by how much time is spent in these functions. So, do as
+ little work as possible in these functions.</p>
+
<note>
- <p>All functions in this behaviour have to be implemented as NIF's.
- This is a limitation that may the lifted in the future.
- There is an <seealso marker="#example">example tracer module nif</seealso>
- implementation at the end of this page.</p>
+ <p>All functions in this behavior must be implemented as NIFs.
+ This limitation can be removed in a future releases.
+ An <seealso marker="#example">example tracer module NIF</seealso>
+ implementation is provided at the end of this page.</p>
</note>
+
<warning>
<p>Do not send messages or issue port commands to the <c>Tracee</c>
- in any of the callbacks. Doing so is not allowed and can cause all
- sorts of strange behaviour, including but not limited to infinite
- recursions.</p>
+ in any of the callbacks. This is not allowed and can cause all
+ sorts of strange behavior, including, but not limited to, infinite
+ recursions.</p>
</warning>
</description>
<datatypes>
- <datatype> <name name="trace_tag_send" /> </datatype>
- <datatype> <name name="trace_tag_receive" /> </datatype>
- <datatype> <name name="trace_tag_call" /> </datatype>
- <datatype> <name name="trace_tag_procs" /> </datatype>
- <datatype> <name name="trace_tag_ports" /> </datatype>
- <datatype> <name name="trace_tag_running_procs" /> </datatype>
- <datatype> <name name="trace_tag_running_ports" /> </datatype>
- <datatype> <name name="trace_tag_gc" /> </datatype>
<datatype>
- <name name="trace_tag" />
+ <name name="trace_tag_call"/>
+ </datatype>
+ <datatype>
+ <name name="trace_tag_gc"/>
+ </datatype>
+ <datatype>
+ <name name="trace_tag_ports"/>
+ </datatype>
+ <datatype>
+ <name name="trace_tag_procs"/>
+ </datatype>
+ <datatype>
+ <name name="trace_tag_receive"/>
+ </datatype>
+ <datatype>
+ <name name="trace_tag_running_ports"/>
+ </datatype>
+ <datatype>
+ <name name="trace_tag_running_procs"/>
+ </datatype>
+ <datatype>
+ <name name="trace_tag_send"/>
+ </datatype>
+ <datatype>
+ <name name="trace_tag"/>
<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/5">Module:trace/5</seealso>
- </p>
+ <p>The different trace tags that the tracer is called with.
+ Each trace tag is described in detail in
+ <seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso>.</p>
</desc>
</datatype>
<datatype>
- <name name="tracee" />
+ <name name="tracee"/>
<desc>
- <p>The process or port that the trace belongs to.
- </p>
+ <p>The process or port that the trace belongs to.</p>
</desc>
</datatype>
<datatype>
- <name name="trace_opts" />
+ <name name="trace_opts"/>
<desc>
- <p>The options for the tracee.</p>
+ <p>The options for the tracee:</p>
<taglist>
<tag><c>timestamp</c></tag>
- <item>If set the tracer has been requested to include a timestamp.</item>
+ <item>If set the tracer has been requested to include a
+ time stamp.</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>
+ 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 element 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 set the tracer has been requested to include the output
- of a match specification that was run.</item>
+ of a match specification that was run.</item>
<tag><c>scheduler_id</c></tag>
- <item>Set the scheduler id is to be included by the tracer.</item>
+ <item>If set the scheduler id is to be included by the tracer.</item>
</taglist>
</desc>
</datatype>
<datatype>
- <name name="tracer_state" />
+ <name name="tracer_state"/>
<desc>
- <p>
- The state which is given when calling
- <seealso marker="erlang#trace-3"><c>erlang:trace(PidPortSpec,true,[{tracer,Module,TracerState}])</c></seealso>.
- The tracer state is an immutable value that is passed to erl_tracer callbacks and should
- contain all the data that is needed to generate the trace event.
- </p>
+ <p>The state specified when calling
+ <seealso marker="erlang#trace-3">
+ <c>erlang:trace(PidPortSpec,true,[{tracer,Module,TracerState}])</c></seealso>.
+ The tracer state is an immutable value that is passed to
+ <c>erl_tracer</c> callbacks and is to
+ contain all the data that is needed to generate the trace event.</p>
</desc>
</datatype>
</datatypes>
<section>
- <title>CALLBACK FUNCTIONS</title>
- <p>The following functions
- should be exported from a <c>erl_tracer</c> callback module.</p>
- <taglist>
- <tag><seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso></tag>
- <item>Mandatory</item>
- <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/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/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/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/5"><c>Module:trace_running_procs/5</c></seealso></tag>
- <item>Optional</item>
+ <title>Callback Functions</title>
+ <p>The following functions are to be exported from an <c>erl_tracer</c>
+ callback module:</p>
+
+ <taglist>
+ <tag><seealso marker="#Module:enabled/3">
+ <c>Module:enabled/3</c></seealso></tag>
+ <item>Mandatory</item>
+ <tag><seealso marker="#Module:trace/5">
+ <c>Module:trace/5</c></seealso></tag>
+ <item>Mandatory</item>
+ <tag><seealso marker="#Module:enabled_call/3">
+ <c>Module:enabled_call/3</c></seealso></tag>
+ <item>Optional</item>
+ <tag><seealso marker="#Module:trace_call/5">
+ <c>Module:trace_call/5</c></seealso></tag>
+ <item>Optional</item>
+ <tag><seealso marker="#Module:enabled_garbage_collection/3">
+ <c>Module:enabled_garbage_collection/3</c></seealso></tag>
+ <item>Optional</item>
+ <tag><seealso marker="#Module:trace_garbage_collection/5">
+ <c>Module:trace_garbage_collection/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/5">
+ <c>Module:trace_ports/5</c></seealso></tag>
+ <item>Optional</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/5">
+ <c>Module:trace_procs/5</c></seealso></tag>
+ <item>Optional</item>
+ <tag><seealso marker="#Module:enabled_receive/3">
+ <c>Module:enabled_receive/3</c></seealso></tag>
+ <item>Optional</item>
+ <tag><seealso marker="#Module:trace_receive/5">
+ <c>Module:trace_receive/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/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/5">
+ <c>Module:trace_running_procs/5</c></seealso></tag>
+ <item>Optional</item>
+ <tag><seealso marker="#Module:enabled_send/3">
+ <c>Module:enabled_send/3</c></seealso></tag>
+ <item>Optional</item>
+ <tag><seealso marker="#Module:trace_send/5">
+ <c>Module:trace_send/5</c></seealso></tag>
+ <item>Optional</item>
</taglist>
-
</section>
<funcs>
<func>
<name>Module:enabled(TraceTag, TracerState, Tracee) -> Result</name>
- <fsummary>Check if a trace event should be generated.</fsummary>
+ <fsummary>Check if a trace event is to be generated.</fsummary>
<type>
- <v>TraceTag = <seealso marker="#type-trace_tag">trace_tag()</seealso> | trace_status</v>
+ <v>TraceTag = <seealso marker="#type-trace_tag">
+ trace_tag()</seealso> | trace_status</v>
<v>TracerState = term()</v>
<v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
- <v>Result = trace | discard | remove</v>
+ <v>Result = trace | discard | remove</v>
</type>
<desc>
- <p>This callback will be called whenever a tracepoint is triggered. It
- allows the tracer to decide whether a trace should be generated or not.
- This check is made as early as possible in order to limit the amount of
- overhead associated with tracing. If <c>trace</c> is returned the
- necessary trace data will be created and the trace call-back of the tracer
- will be called. If <c>discard</c> is returned, this trace call
- will be discarded and no call to trace will be done.
- </p>
- <p><c>trace_status</c> is a special type of <c>TraceTag</c> which is used
- to check if the tracer should still be active. It is called in multiple
- scenarios, but most significantly it is used when tracing is started
- using this tracer. If <c>remove</c> is returned when the <c>trace_status</c>
- is checked, the tracer will be removed from the tracee.</p>
- <p>This function may be called multiple times per tracepoint, so it
- is important that it is both fast and side effect free.</p>
+ <p>This callback is called whenever a tracepoint is triggered. It
+ allows the tracer to decide whether a trace is to be generated or not.
+ This check is made as early as possible to limit the amount of
+ overhead associated with tracing. If <c>trace</c> is returned, the
+ necessary trace data is created and the trace callback of the tracer
+ is called. If <c>discard</c> is returned, this trace call is
+ discarded and no call to trace is done.</p>
+ <p><c>trace_status</c> is a special type of <c>TraceTag</c>, which is
+ used to check if the tracer is still to be active. It is called in
+ multiple scenarios, but most significantly it is used when tracing
+ is started using this tracer. If <c>remove</c> is returned when the
+ <c>trace_status</c> is checked, the tracer is removed from the
+ tracee.</p>
+ <p>This function can be called multiple times per tracepoint, so it
+ is important that it is both fast and without side effects.</p>
</desc>
</func>
+
<func>
- <name>Module:trace(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
- <fsummary>Check if a trace event should be generated.</fsummary>
+ <name>Module:enabled_call(TraceTag, TracerState, Tracee) -> Result</name>
+ <fsummary>Check if a trace event is to be generated.</fsummary>
<type>
- <v>TraceTag = <seealso marker="#type-trace_tag">trace_tag()</seealso></v>
+ <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>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
- <v>Result = ok</v>
+ <v>Result = trace | discard | remove</v>
</type>
<desc>
- <p>This callback will be called when a tracepoint is triggered and
- 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>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 trace tuple has five elements, the fifth element will be sent as
- the <c>extra</c> value in the <c>Opts</c> maps.</p>
+ <p>This callback is called whenever a tracepoint with trace flag
+ <seealso marker="erlang#trace-3"><c>call | return_to</c></seealso>
+ is triggered.</p>
+ <p>If <c>enabled_call/3</c> is undefined,
+ <seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso>
+ is called instead.</p>
</desc>
</func>
+
<func>
- <name name="trace">Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, Opts) -> Result</name>
- <fsummary>Check if a sequence trace event should be generated.</fsummary>
+ <name>Module:enabled_garbage_collection(TraceTag, TracerState, Tracee) -> Result</name>
+ <fsummary>Check if a trace event is to be generated.</fsummary>
<type>
+ <v>TraceTag = <seealso marker="#type-trace_tag_gc">
+ trace_tag_gc()</seealso></v>
<v>TracerState = term()</v>
- <v>Label = term()</v>
- <v>SeqTraceInfo = term()</v>
- <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
- <v>Result = ok</v>
+ <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
+ <v>Result = trace | discard | remove</v>
</type>
<desc>
- <p>The <c>TraceTag</c> <c>seq_trace</c> is handled a little bit
- differently. There is not <c>Tracee</c> for seq_trace, instead the
- <c>Label</c> associated with the seq_trace event is given.
- For more info on what <c>Label</c> and <c>SeqTraceInfo</c> can be
- see the <seealso marker="kernel:seq_trace">seq_trace</seealso> manual.</p>
+ <p>This callback is called whenever a tracepoint with trace flag
+ <seealso marker="erlang#trace-3"><c>garbage_collection</c></seealso>
+ is triggered.</p>
+ <p>If <c>enabled_garbage_collection/3</c> is undefined,
+ <seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso>
+ is called instead.</p>
</desc>
</func>
<func>
- <name>Module:enabled_procs(TraceTag, TracerState, Tracee) -> Result</name>
- <fsummary>Check if a trace event should be generated.</fsummary>
- <type>
- <v>TraceTag = <seealso marker="#type-trace_tag_procs">trace_tag_procs()</seealso></v>
- <v>TracerState = term()</v>
- <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
- <v>Result = trace | discard | remove</v>
- </type>
- <desc>
- <p>This callback will be called whenever a tracepoint with trace flag
- <seealso marker="erlang#trace-3"><c>procs</c></seealso>
- is triggered.</p>
- <p>If <c>enabled_procs/3</c> is not defined <c>enabled/3</c> will be called instead.</p>
- </desc>
+ <name>Module:enabled_ports(TraceTag, TracerState, Tracee) -> Result</name>
+ <fsummary>Check if a trace event is to be generated.</fsummary>
+ <type>
+ <v>TraceTag = <seealso marker="#type-trace_tag_ports">
+ trace_tag_ports()</seealso></v>
+ <v>TracerState = term()</v>
+ <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
+ <v>Result = trace | discard | remove</v>
+ </type>
+ <desc>
+ <p>This callback is called whenever a tracepoint with trace flag
+ <seealso marker="erlang#trace-3"><c>ports</c></seealso>
+ is triggered.</p>
+ <p>If <c>enabled_ports/3</c> is undefined,
+ <seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <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>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
- <v>Result = ok</v>
- </type>
- <desc>
- <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/5</c> is not defined <c>trace/5</c> will be called instead.</p>
- </desc>
+ <name>Module:enabled_procs(TraceTag, TracerState, Tracee) -> Result</name>
+ <fsummary>Check if a trace event is to be generated.</fsummary>
+ <type>
+ <v>TraceTag = <seealso marker="#type-trace_tag_procs">
+ trace_tag_procs()</seealso></v>
+ <v>TracerState = term()</v>
+ <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
+ <v>Result = trace | discard | remove</v>
+ </type>
+ <desc>
+ <p>This callback is called whenever a tracepoint with trace flag
+ <seealso marker="erlang#trace-3"><c>procs</c></seealso>
+ is triggered.</p>
+ <p>If <c>enabled_procs/3</c> is undefined,
+ <seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <name>Module:enabled_ports(TraceTag, TracerState, Tracee) -> Result</name>
- <fsummary>Check if a trace event should be generated.</fsummary>
- <type>
- <v>TraceTag = <seealso marker="#type-trace_tag_ports">trace_tag_ports()</seealso></v>
- <v>TracerState = term()</v>
- <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
- <v>Result = trace | discard | remove</v>
- </type>
- <desc>
- <p>This callback will be called whenever a tracepoint with trace flag
- <seealso marker="erlang#trace-3"><c>ports</c></seealso>
- is triggered.</p>
- <p>If <c>enabled_ports/3</c> is not defined <c>enabled/3</c> will be called instead.</p>
- </desc>
+ <name>Module:enabled_receive(TraceTag, TracerState, Tracee) -> Result
+ </name>
+ <fsummary>Check if a trace event is to 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>Result = trace | discard | remove</v>
+ </type>
+ <desc>
+ <p>This callback is called whenever a tracepoint with trace flag
+ <seealso marker="erlang#trace-3"><c>'receive'</c></seealso>
+ is triggered.</p>
+ <p>If <c>enabled_receive/3</c> is undefined,
+ <seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <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>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
- <v>Result = ok</v>
- </type>
- <desc>
- <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/5</c> is not defined <c>trace/5</c> will be called instead.</p>
- </desc>
+ <name>Module:enabled_running_ports(TraceTag, TracerState, Tracee) ->
+ Result</name>
+ <fsummary>Check if a trace event is to 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>Result = trace | discard | remove</v>
+ </type>
+ <desc>
+ <p>This callback is called whenever a tracepoint with trace flag
+ <seealso marker="erlang#trace-3"><c>running_ports</c></seealso>
+ is triggered.</p>
+ <p>If <c>enabled_running_ports/3</c> is undefined,
+ <seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <name>Module:enabled_running_procs(TraceTag, TracerState, Tracee) -> 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>Result = trace | discard | remove</v>
- </type>
- <desc>
- <p>This callback will be called whenever a tracepoint with trace flag
- <seealso marker="erlang#trace-3"><c>running_procs | running</c></seealso>
- is triggered.</p>
- <p>If <c>enabled_running_procs/3</c> is not defined <c>enabled/3</c> will be called instead.</p>
- </desc>
+ <name>Module:enabled_running_procs(TraceTag, TracerState, Tracee) ->
+ Result</name>
+ <fsummary>Check if a trace event is to 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>Result = trace | discard | remove</v>
+ </type>
+ <desc>
+ <p>This callback is called whenever a tracepoint with trace flag
+ <seealso marker="erlang#trace-3">
+ <c>running_procs | running</c></seealso>
+ is triggered.</p>
+ <p>If <c>enabled_running_procs/3</c> is undefined,
+ <seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <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>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
- <v>Result = ok</v>
- </type>
- <desc>
- <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/5</c> is not defined <c>trace/5</c> will be called instead.</p>
- </desc>
+ <name>Module:enabled_send(TraceTag, TracerState, Tracee) -> Result</name>
+ <fsummary>Check if a trace event is to 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>Result = trace | discard | remove</v>
+ </type>
+ <desc>
+ <p>This callback is called whenever a tracepoint with trace flag
+ <seealso marker="erlang#trace-3"><c>send</c></seealso>
+ is triggered.</p>
+ <p>If <c>enabled_send/3</c> is undefined,
+ <seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <name>Module:enabled_running_ports(TraceTag, TracerState, Tracee) -> 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>Result = trace | discard | remove</v>
- </type>
- <desc>
- <p>This callback will be called whenever a tracepoint with trace flag
- <seealso marker="erlang#trace-3"><c>running_ports</c></seealso>
- is triggered.</p>
- <p>If <c>enabled_running_ports/3</c> is not defined <c>enabled/3</c> will be called instead.</p>
- </desc>
+ <name>Module:trace(TraceTag, TracerState, Tracee, TraceTerm,
+ Opts) -> Result</name>
+ <fsummary>Check if a trace event is to 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>TraceTerm = term()</v>
+ <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
+ <v>Result = ok</v>
+ </type>
+ <desc>
+ <p>This callback is called when a tracepoint is triggered and the
+ <seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso>
+ callback returned <c>trace</c>. In it any side effects needed by
+ the tracer are to be done. The tracepoint payload is located in
+ the <c>TraceTerm</c>. The content of the <c>TraceTerm</c>
+ depends on which <c>TraceTag</c> is triggered.
+ <c>TraceTerm</c> corresponds to the
+ fourth element in the trace tuples described in
+ <seealso marker="erlang#trace_3_trace_messages">
+ <c>erlang:trace/3</c></seealso>.</p>
+ <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>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>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
- <v>Result = ok</v>
- </type>
- <desc>
- <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/5</c> is not defined <c>trace/5</c> will be called instead.</p>
- </desc>
+ <name name="trace">Module:trace(seq_trace, TracerState, Label,
+ SeqTraceInfo, Opts) -> Result</name>
+ <fsummary>Check if a sequence trace event is to be generated.</fsummary>
+ <type>
+ <v>TracerState = term()</v>
+ <v>Label = term()</v>
+ <v>SeqTraceInfo = term()</v>
+ <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
+ <v>Result = ok</v>
+ </type>
+ <desc>
+ <p>The <c>TraceTag</c> <c>seq_trace</c> is handled slightly
+ differently. There is no <c>Tracee</c> for <c>seq_trace</c>, instead
+ the <c>Label</c> associated with the <c>seq_trace</c> event is
+ specified.</p>
+ <p>For more information on what <c>Label</c> and <c>SeqTraceInfo</c>
+ can be, see <seealso marker="kernel:seq_trace">
+ <c>kernel:seq_trace(3)</c></seealso>.</p>
+ </desc>
</func>
<func>
- <name>Module:enabled_call(TraceTag, TracerState, Tracee) -> 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>Result = trace | discard | remove</v>
- </type>
- <desc>
- <p>This callback will be called whenever a tracepoint with trace flag
- <seealso marker="erlang#trace-3"><c>call | return_to</c></seealso>
- is triggered.</p>
- <p>If <c>enabled_call/3</c> is not defined <c>enabled/3</c> will be called instead.</p>
- </desc>
+ <name>Module:trace_call(TraceTag, TracerState, Tracee, TraceTerm,
+ Opts) -> Result</name>
+ <fsummary>Check if a trace event is to 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>TraceTerm = term()</v>
+ <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
+ <v>Result = ok</v>
+ </type>
+ <desc>
+ <p>This callback is called when a tracepoint is triggered and the
+ <seealso marker="#Module:enabled_call/3">
+ <c>Module:enabled_call/3</c></seealso>
+ callback returned <c>trace</c>.</p>
+ <p>If <c>trace_call/5</c> is undefined,
+ <seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <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>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
- <v>Result = ok</v>
- </type>
- <desc>
- <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/5</c> is not defined <c>trace/5</c> will be called instead.</p>
- </desc>
+ <name>Module:trace_garbage_collection(TraceTag, TracerState, Tracee,
+ TraceTerm, Opts) -> Result</name>
+ <fsummary>Check if a trace event is to 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>TraceTerm = term()</v>
+ <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
+ <v>Result = ok</v>
+ </type>
+ <desc>
+ <p>This callback is called when a tracepoint is triggered and the
+ <seealso marker="#Module:enabled_garbage_collection/3">
+ <c>Module:enabled_garbage_collection/3</c></seealso>
+ callback returned <c>trace</c>.</p>
+ <p>If <c>trace_garbage_collection/5</c> is undefined,
+ <seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <name>Module:enabled_send(TraceTag, TracerState, Tracee) -> 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>Result = trace | discard | remove</v>
- </type>
- <desc>
- <p>This callback will be called whenever a tracepoint with trace flag
- <seealso marker="erlang#trace-3"><c>send</c></seealso>
- is triggered.</p>
- <p>If <c>enabled_send/3</c> is not defined <c>enabled/3</c> will be called instead.</p>
- </desc>
+ <name>Module:trace_ports(TraceTag, TracerState, Tracee, TraceTerm,
+ Opts) -> Result</name>
+ <fsummary>Check if a trace event is to 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>TraceTerm = term()</v>
+ <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
+ <v>Result = ok</v>
+ </type>
+ <desc>
+ <p>This callback is called when a tracepoint is triggered and the
+ <seealso marker="#Module:enabled_ports/3">
+ <c>Module:enabled_ports/3</c></seealso>
+ callback returned <c>trace</c>.</p>
+ <p>If <c>trace_ports/5</c> is undefined,
+ <seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <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>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
- <v>Result = ok</v>
- </type>
- <desc>
- <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/5</c> is not defined <c>trace/5</c> will be called instead.</p>
- </desc>
+ <name>Module:trace_procs(TraceTag, TracerState, Tracee, TraceTerm,
+ Opts) -> Result</name>
+ <fsummary>Check if a trace event is to 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>TraceTerm = term()</v>
+ <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
+ <v>Result = ok</v>
+ </type>
+ <desc>
+ <p>This callback is called when a tracepoint is triggered and the
+ <seealso marker="#Module:enabled_procs/3">
+ <c>Module:enabled_procs/3</c></seealso>
+ callback returned <c>trace</c>.</p>
+ <p>If <c>trace_procs/5</c> is undefined,
+ <seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <name>Module:enabled_receive(TraceTag, TracerState, Tracee) -> 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>Result = trace | discard | remove</v>
- </type>
- <desc>
- <p>This callback will be called whenever a tracepoint with trace flag
- <seealso marker="erlang#trace-3"><c>'receive'</c></seealso>
- is triggered.</p>
- <p>If <c>enabled_receive/3</c> is not defined <c>enabled/3</c> will be called instead.</p>
- </desc>
+ <name>Module:trace_receive(TraceTag, TracerState, Tracee, TraceTerm,
+ Opts) -> Result</name>
+ <fsummary>Check if a trace event is to 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>TraceTerm = term()</v>
+ <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
+ <v>Result = ok</v>
+ </type>
+ <desc>
+ <p>This callback is called when a tracepoint is triggered and the
+ <seealso marker="#Module:enabled_receive/3">
+ <c>Module:enabled_receive/3</c></seealso>
+ callback returned <c>trace</c>.</p>
+ <p>If <c>trace_receive/5</c> is undefined,
+ <seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <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>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
- <v>Result = ok</v>
- </type>
- <desc>
- <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/5</c> is not defined <c>trace/5</c> will be called instead.</p>
- </desc>
+ <name>Module:trace_running_ports(TraceTag, TracerState, Tracee,
+ TraceTerm, Opts) -> Result</name>
+ <fsummary>Check if a trace event is to 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>TraceTerm = term()</v>
+ <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
+ <v>Result = ok</v>
+ </type>
+ <desc>
+ <p>This callback is called when a tracepoint is triggered and the
+ <seealso marker="#Module:enabled_running_ports/3">
+ <c>Module:enabled_running_ports/3</c></seealso>
+ callback returned <c>trace</c>.</p>
+ <p>If <c>trace_running_ports/5</c> is undefined,
+ <seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <name>Module:enabled_garbage_collection(TraceTag, TracerState, Tracee) -> 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>Result = trace | discard | remove</v>
- </type>
- <desc>
- <p>This callback will be called whenever a tracepoint with trace flag
- <seealso marker="erlang#trace-3"><c>garbage_collection</c></seealso>
- is triggered.</p>
- <p>If <c>enabled_garbage_collection/3</c> is not defined <c>enabled/3</c> will be called instead.</p>
- </desc>
+ <name>Module:trace_running_procs(TraceTag, TracerState, Tracee,
+ TraceTerm, Opts) -> Result</name>
+ <fsummary>Check if a trace event is to 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>TraceTerm = term()</v>
+ <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
+ <v>Result = ok</v>
+ </type>
+ <desc>
+ <p>This callback is called when a tracepoint is triggered and the
+ <seealso marker="#Module:enabled_running_procs/3">
+ <c>Module:enabled_running_procs/3</c></seealso>
+ callback returned <c>trace</c>.</p>
+ <p>If <c>trace_running_procs/5</c> is undefined,
+ <seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
<func>
- <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>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
- <v>Result = ok</v>
- </type>
- <desc>
- <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/5</c> is not defined <c>trace/5</c> will be called instead.</p>
- </desc>
+ <name>Module:trace_send(TraceTag, TracerState, Tracee, TraceTerm,
+ Opts) -> Result</name>
+ <fsummary>Check if a trace event is to 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>TraceTerm = term()</v>
+ <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
+ <v>Result = ok</v>
+ </type>
+ <desc>
+ <p>This callback is called when a tracepoint is triggered and the
+ <seealso marker="#Module:enabled_send/3">
+ <c>Module:enabled_send/3</c></seealso>
+ callback returned <c>trace</c>.</p>
+ <p>If <c>trace_send/5</c> is undefined,
+ <seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso>
+ is called instead.</p>
+ </desc>
</func>
-
</funcs>
+
<section>
<marker id="example"></marker>
- <title>Erl Tracer Module example</title>
- <p>In the example below a tracer module with a nif backend sends a message
- for each <c>send</c> trace tag containing only the sender and receiver.
- Using this tracer module, a much more lightweight message tracer is
- used that only records who sent messages to who.</p>
- <p>Here is an example session using it on Linux.</p>
+ <title>Erl Tracer Module Example</title>
+ <p>In this example, a tracer module with a NIF back end sends a
+ message for each <c>send</c> trace tag containing only the sender and
+ receiver. Using this tracer module, a much more lightweight message
+ tracer is used, which only records who sent messages to who.</p>
+
+ <p>The following is an example session using it on Linux:</p>
+
<pre>
$ gcc -I erts-8.0/include/ -fPIC -shared -o erl_msg_tracer.so erl_msg_tracer.c
$ erl
@@ -532,9 +663,10 @@ ok
{trace,#Port&lt;0.490&gt;,&lt;0.4.0&gt;}
{ok,&lt;0.40.0&gt;}
{trace,&lt;0.41.0&gt;,&lt;0.27.0&gt;}
-5&gt;
- </pre>
- <p>erl_msg_tracer.erl</p>
+5&gt;</pre>
+
+ <p><c>erl_msg_tracer.erl</c>:</p>
+
<pre>
-module(erl_msg_tracer).
@@ -546,10 +678,11 @@ load() ->
enabled(_, _, _) ->
error.
-trace(_, _, _,_, _) ->
- error.
- </pre>
- <p>erl_msg_tracer.c</p>
+trace(_, _, _, _, _) ->
+ error.</pre>
+
+ <p><c>erl_msg_tracer.c</c>:</p>
+
<pre>
#include "erl_nif.h"
@@ -640,7 +773,6 @@ static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
}
return enif_make_atom(env, "ok");
-}
- </pre>
+}</pre>
</section>
</erlref>