Merge branch 'egil/erts/tracing-support-lttng/OTP-13532'

* egil/erts/tracing-support-lttng/OTP-13532: (28 commits)
  runtime_tools: User's guide to LTTng and dyntrace
  runtime_tools: Fix Dtrace build
  erts: Fix gc messages in tracer_SUITE
  erts: Fix gc messages in sensitive_SUITE
  erts: Fix gc messages in trace_port_SUITE
  tools: Update fprof tests
  tools: Update fprof with new gc traces
  runtime_tools: Update dyntrace_lttng_SUITE tests
  runtime_tools: Add 'return_to' for call tracing
  erts: Fix return_to trace callback
  erts: Update erl_tracer documentation
  erts: Fix erl_tracer documentation typos
  Update preloaded erl_tracer.beam
  erts: Update erl_tracer type specs
  runtime_tools: Add lttng dyntrace tests
  runtime_tools: Extend 'trace' and 'enabled' tracer callbacks
  erts: Extend 'enabled' and 'trace' tracer callbacks
  runtime_tools: Extend 'enabled' tracer callbacks
  erts: Extend 'enabled' tracer callbacks
  runtime_tools: Update lttng garbage collection trace
  ...

1 files changed, 351 insertions, 7 deletions

diff --git a/erts/doc/src/erl_tracer.xml b/erts/doc/src/erl_tracer.xml
index 1e8e78b25f..2075b962d8 100644
--- a/erts/doc/src/erl_tracer.xml
+++ b/erts/doc/src/erl_tracer.xml
@@ -54,6 +54,14 @@
   </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" />
       <desc>
@@ -105,6 +113,29 @@
     <title>CALLBACK FUNCTIONS</title>
     <p>The following functions
       should be exported from a <c>erl_tracer</c> callback module.</p>
+   <taglist>
+       <tag><seealso marker="#enabled"><c>Module:enabled/3</c></seealso></tag>
+       <item>Mandatory</item>
+       <tag><seealso marker="#trace"><c>Module:trace/6</c></seealso></tag>
+       <item>Mandatory</item>
+       <tag><seealso marker="#enabled_procs"><c>Module:enabled_procs/3</c></seealso></tag>
+       <item>Optional</item>
+       <tag><seealso marker="#trace_procs"><c>Module:trace_procs/6</c></seealso></tag>
+       <item>Optional</item>
+       <tag><seealso marker="#enabled_ports"><c>Module:enabled_ports/3</c></seealso></tag>
+       <item>Optional</item>
+       <tag><seealso marker="#trace_ports"><c>Module:trace_ports/6</c></seealso></tag>
+       <item>Optional</item>
+       <tag><seealso marker="#enabled_running_ports"><c>Module:enabled_running_ports/3</c></seealso></tag>
+       <item>Optional</item>
+       <tag><seealso marker="#trace_running_ports"><c>Module:trace_running_ports/6</c></seealso></tag>
+       <item>Optional</item>
+       <tag><seealso marker="#enabled_running_procs"><c>Module:enabled_running_procs/3</c></seealso></tag>
+       <item>Optional</item>
+       <tag><seealso marker="#trace_running_procs"><c>Module:trace_running_procs/6</c></seealso></tag>
+       <item>Optional</item>
+   </taglist>
+
   </section>
   <marker id="enabled"></marker>
   <funcs>
@@ -114,11 +145,11 @@
       <type>
         <v>TraceTag = <seealso marker="#type-trace_tag">trace_tag()</seealso> | trace_status</v>
         <v>TracerState = term()</v>
-        <v>Tracee = <seealso marker="#type-trace_tag">tracee()</seealso></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 trace point is triggered. It
+        <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
@@ -132,7 +163,7 @@
         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.</p>
-        <p>This function may be called multiple times per trace point, so it
+        <p>This function may be called multiple times per tracepoint, so it
         is important that it is both fast and side effect free.</p>
       </desc>
     </func>
@@ -143,17 +174,17 @@
       <type>
         <v>TraceTag = <seealso marker="#type-trace_tag">trace_tag()</seealso></v>
         <v>TracerState = term()</v>
-        <v>Tracee = <seealso marker="#type-trace_tag">tracee()</seealso></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>
       <desc>
-        <p>This callback will be called when a trace point is triggered and
+        <p>This callback will be called when a tracepoint is triggered and
         the <seealso marker="#enabled">Module:enabled/3</seealso>
         callback returned <c>trace</c>. In it any side effects needed by
-        the tracer should be done. The trace point payload is located in
+        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
@@ -181,6 +212,319 @@
         see the <seealso marker="kernel:seq_trace">seq_trace</seealso> manual.</p>
       </desc>
     </func>
+
+    <marker id="enabled_procs"></marker>
+    <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>
+    </func>
+
+    <marker id="trace_procs"></marker>
+    <func>
+        <name>Module:trace_procs(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, 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>
+        <desc>
+            <p>This callback will be called when a tracepoint is triggered and
+                the <seealso marker="#enabled_procs">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>
+        </desc>
+    </func>
+
+    <marker id="enabled_ports"></marker>
+    <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>
+    </func>
+
+    <marker id="trace_ports"></marker>
+    <func>
+        <name>Module:trace_ports(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, 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>
+        <desc>
+            <p>This callback will be called when a tracepoint is triggered and
+                the <seealso marker="#enabled_ports">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>
+        </desc>
+    </func>
+
+    <marker id="enabled_running_procs"></marker>
+    <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>
+    </func>
+
+    <marker id="trace_running_procs"></marker>
+    <func>
+        <name>Module:trace_running_procs(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, 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>
+        <desc>
+            <p>This callback will be called when a tracepoint is triggered and
+                the <seealso marker="#enabled_running_procs">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>
+        </desc>
+    </func>
+
+    <marker id="enabled_running_ports"></marker>
+    <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>
+    </func>
+
+    <marker id="trace_running_ports"></marker>
+    <func>
+        <name>Module:trace_running_ports(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, 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>
+        <desc>
+            <p>This callback will be called when a tracepoint is triggered and
+                the <seealso marker="#enabled_running_ports">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>
+        </desc>
+    </func>
+
+    <marker id="enabled_call"></marker>
+    <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>
+    </func>
+
+    <marker id="trace_call"></marker>
+    <func>
+        <name>Module:trace_call(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, 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>
+        <desc>
+            <p>This callback will be called when a tracepoint is triggered and
+                the <seealso marker="#enabled_call">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>
+        </desc>
+    </func>
+
+    <marker id="enabled_send"></marker>
+    <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>
+    </func>
+
+    <marker id="trace_send"></marker>
+    <func>
+        <name>Module:trace_send(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, 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>
+        <desc>
+            <p>This callback will be called when a tracepoint is triggered and
+                the <seealso marker="#enabled_send">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>
+        </desc>
+    </func>
+
+    <marker id="enabled_receive"></marker>
+    <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>
+    </func>
+
+    <marker id="trace_receive"></marker>
+    <func>
+        <name>Module:trace_receive(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, 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>
+        <desc>
+            <p>This callback will be called when a tracepoint is triggered and
+                the <seealso marker="#enabled_receive">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>
+        </desc>
+    </func>
+
+    <marker id="enabled_garbage_collection"></marker>
+    <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>
+    </func>
+
+    <marker id="trace_garbage_collection"></marker>
+    <func>
+        <name>Module:trace_garbage_collection(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, 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>
+        <desc>
+            <p>This callback will be called when a tracepoint is triggered and
+                the <seealso marker="#enabled_garbage_collection">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>
+        </desc>
+    </func>
+
   </funcs>
   <section>
     <marker id="example"></marker>
@@ -282,7 +626,7 @@ static ERL_NIF_TERM enabled(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
     ErlNifPid to_pid;
     if (enif_get_local_pid(env, argv[1], &amp;to_pid))
         if (!enif_is_process_alive(env, &amp;to_pid))
-            /* tracer is dead so we should remove this trace point */
+            /* tracer is dead so we should remove this tracepoint */
             return enif_make_atom(env, "remove");
 
     /* Only generate trace for when tracer != tracee */