diff options
Diffstat (limited to 'erts/doc/src/erl_tracer.xml')
| -rw-r--r-- | erts/doc/src/erl_tracer.xml | 882 |
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<0.490>,<0.4.0>} {ok,<0.40.0>} {trace,<0.41.0>,<0.27.0>} -5> - </pre> - <p>erl_msg_tracer.erl</p> +5></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> |