erl_tracer

模块

erl_tracer

模块摘要

Erlang示踪剂行为。

描述

这个行为模块实现了Erlang跟踪系统的后端。只要跟踪探测器被触发，就会调用该模块中的功能。无论是enabled和trace函数调用在触发跟踪探测器的实体的范围内。这意味着启用跟踪的开销会受到这些函数花费多少时间的巨大影响。所以，在这些功能上尽可能少做一些工作。

注

此行为中的所有功能都必须作为NIF实施。未来版本中可以删除此限制。example tracer module NIF本页末尾提供了一个实现。

警告

不要向Tracee任何回调中发送消息或发出端口命令。这是不允许的，并可能导致各种奇怪的行为，包括但不限于无限递归。

数据类型

trace_tag_call() =

call | return_to | return_from | exception_from

trace_tag_gc() =

gc_minor_start | gc_minor_end | gc_major_start | gc_major_end

trace_tag_ports() =

open |

closed |

link |

unlink |

getting_linked |

getting_unlinked

trace_tag_procs() =

spawn |

spawned |

exit |

link |

unlink |

getting_linked |

getting_unlinked |

register |

unregister

trace_tag_receive() = 'receive'

trace_tag_running_ports() =

in | out | in_exiting | out_exiting | out_exited

trace_tag_running_procs() =

in | out | in_exiting | out_exiting | out_exited

trace_tag_send() = send | send_to_non_existing_process

trace_tag() =

trace_tag_send()|

trace_tag_receive()|

trace_tag_call()|

trace_tag_procs()|

trace_tag_ports()|

trace_tag_running_procs()|

trace_tag_running_ports()|

trace_tag_gc()

使用跟踪器调用的不同跟踪标记。每个跟踪标记详细描述在Module:trace/5...

tracee() = port() | pid() | undefined

跟踪所属的进程或端口。

trace_opts() =

#{extra => term(),

match_spec_result => term(),

scheduler_id => integer() >= 0,

timestamp =>

timestamp | cpu_timestamp | monotonic | strict_monotonic}

Tracee的选项：

timestamp如果设置了示踪剂已被请求包括时间戳记。extra如果设置跟踪点已包含有关跟踪事件的其他数据。附加数据取决于哪一个TraceTag被触发。所述extra跟踪数据对应于在所描述的跟踪元组的第五元素erlang:trace/3。match_spec_result如果设置了跟踪器，请求包含运行的匹配规范的输出。scheduler_id如果设置了调度器标识符将被包含在跟踪器中。

tracer_state() = term()

调用时指定的状态erlang:trace(PidPortSpec,true,[{tracer,Module,TracerState}])。跟踪器状态是传递给erl_tracer回调函数的不可变值，并且包含生成跟踪事件所需的所有数据。

回调函数

以下函数将从erl_tracer回调模块导出：

Module:enabled/3强制性Module:trace/5强制性Module:enabled_call/3任选Module:trace_call/5任选Module:enabled_garbage_collection/3任选Module:trace_garbage_collection/5任选Module:enabled_ports/3任选Module:trace_ports/5任选Module:enabled_procs/3任选Module:trace_procs/5任选Module:enabled_receive/3任选Module:trace_receive/5任选Module:enabled_running_ports/3任选Module:trace_running_ports/5任选Module:enabled_running_procs/3任选Module:trace_running_procs/5任选Module:enabled_send/3任选Module:trace_send/5任选

出口

Module:enabled(TraceTag, TracerState, Tracee) -> Result

类型

只要触发了跟踪点，就会调用此回调。它允许跟踪器决定是否生成跟踪。该检查尽可能早，以限制跟踪相关的开销量。如果trace返回，则创建必要的跟踪数据并调用跟踪器的跟踪回调。如果discard返回，则此跟踪调用将被丢弃，并且不会调用跟踪。

trace_status是一种特殊类型TraceTag，用于检查示踪剂是否仍然有效。它在多种情况下被调用，但最重要的是在使用此跟踪器开始跟踪时使用。如果remove在trace_status检查时返回，示踪剂将从Tracee中移除。

该功能可以在每个追踪点多次调用，因此重要的是它既快又无副作用。

Module:enabled_call(TraceTag, TracerState, Tracee) -> Result

类型

只要带有跟踪标志的跟踪点call | return_to被触发，就会调用此回调。

如果enabled_call/3未定义，Module:enabled/3则调用。

Module:enabled_garbage_collection(TraceTag, TracerState, Tracee) -> Result

类型

只要带有跟踪标志的跟踪点garbage_collection被触发，就会调用此回调。

如果enabled_garbage_collection/3未定义，Module:enabled/3则调用。

Module:enabled_ports(TraceTag, TracerState, Tracee) -> Result

类型

只要带有跟踪标志的跟踪点ports被触发，就会调用此回调。

如果enabled_ports/3未定义，Module:enabled/3则调用。

Module:enabled_procs(TraceTag, TracerState, Tracee) -> Result

类型

只要带有跟踪标志的跟踪点procs被触发，就会调用此回调。

如果enabled_procs/3未定义，Module:enabled/3则调用。

Module:enabled_receive(TraceTag, TracerState, Tracee) -> Result

类型

只要带有跟踪标志的跟踪点'receive'被触发，就会调用此回调。

如果enabled_receive/3未定义，Module:enabled/3则调用。

Module:enabled_running_ports(TraceTag, TracerState, Tracee) -> Result

类型

只要带有跟踪标志的跟踪点running_ports被触发，就会调用此回调。

如果enabled_running_ports/3未定义，Module:enabled/3则调用。

Module:enabled_running_procs(TraceTag, TracerState, Tracee) -> Result

类型

只要带有跟踪标志的跟踪点running_procs | running被触发，就会调用此回调。

如果enabled_running_procs/3未定义，Module:enabled/3则调用。

Module:enabled_send(TraceTag, TracerState, Tracee) -> Result

类型

每当有跟踪标志的跟踪点时，都会调用此回调。send被触发了。

如果enabled_send/3是未知的，Module:enabled/3而是被称为。

Module:trace(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result

类型

当触发跟踪点时，当Module:enabled/3回调返回trace在它中，示踪剂所需的任何副作用都要做。跟踪点有效载荷位于TraceTerm.“公约”的内容TraceTerm取决于TraceTag被触发了。TraceTerm中描述的跟踪元组中的第四个元素。erlang:trace/3...

如果跟踪元组有五个元素，则第五个元素将作为extra值中的Opts地图。

Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, Opts) -> Result

类型

大TraceTagseq_trace处理方式略有不同。没有Tracee为seq_trace，而不是Label与seq_trace事件。

有关什么的更多信息Label和SeqTraceInfo可以，看seq_trace(3)...

Module:trace_call(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result

类型

当触发跟踪点时，当Module:enabled_call/3回调返回trace...

如果trace_call/5是未知的，Module:trace/5而是被称为。

Module:trace_garbage_collection(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result

类型

当触发跟踪点时，当Module:enabled_garbage_collection/3回调返回trace...

如果trace_garbage_collection/5是未知的，Module:trace/5而是被称为。

Module:trace_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result

类型

当触发跟踪点时，当Module:enabled_ports/3回调返回trace...

如果trace_ports/5是未知的，Module:trace/5而是被称为。

Module:trace_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result

类型

当触发跟踪点时，当Module:enabled_procs/3回调返回trace...

如果trace_procs/5是未知的，Module:trace/5而是被称为。

Module:trace_receive(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result

类型

当触发跟踪点时，当Module:enabled_receive/3回调返回trace...

如果trace_receive/5是未知的，Module:trace/5而是被称为。

Module:trace_running_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result

类型

当触发跟踪点时，当Module:enabled_running_ports/3回调返回trace...

如果trace_running_ports/5是未知的，Module:trace/5而是被称为。

Module:trace_running_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result

类型

当触发跟踪点时，当Module:enabled_running_procs/3回调返回trace...

如果trace_running_procs/5是未知的，Module:trace/5而是被称为。

Module:trace_send(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result

类型

当触发跟踪点时，当Module:enabled_send/3回调返回trace...

如果trace_send/5是未知的，Module:trace/5而是被称为。

ERL示踪模块示例

在本例中，带有nif后端的跟踪器模块为每个模块发送一条消息。send只包含发送方和接收方的跟踪标记。使用这个跟踪器模块，使用了一个更轻量级的消息跟踪器，它只记录谁向谁发送消息。

下面是在Linux上使用它的示例会话：

$ gcc -I erts-8.0/include/ -fPIC -shared -o erl_msg_tracer.so erl_msg_tracer.c
$ erl
Erlang/OTP 19 [DEVELOPMENT] [erts-8.0] [source-ed2b56b] [64-bit] [smp:8:8] [async-threads:10] [hipe] [kernel-poll:false]

Eshell V8.0  (abort with ^G)
1> c(erl_msg_tracer), erl_msg_tracer:load().
ok
2> Tracer = spawn(fun F() -> receive M -> io:format("~p~n",[M]), F() end end).
<0.37.0>
3> erlang:trace(new, true, [send,{tracer, erl_msg_tracer, Tracer}]).
0
{trace,<0.39.0>,<0.27.0>}
4> {ok, D} = file:open("/tmp/tmp.data",[write]).
{trace,#Port<0.486>,<0.40.0>}
{trace,<0.40.0>,<0.21.0>}
{trace,#Port<0.487>,<0.4.0>}
{trace,#Port<0.488>,<0.4.0>}
{trace,#Port<0.489>,<0.4.0>}
{trace,#Port<0.490>,<0.4.0>}
{ok,<0.40.0>}
{trace,<0.41.0>,<0.27.0>}
5>

erl_msg_tracer.erl*

-module(erl_msg_tracer).

-export([enabled/3, trace/5, load/0]).

load() ->
    erlang:load_nif("erl_msg_tracer", []).

enabled(_, _, _) ->
    error.

trace(_, _, _, _, _) ->
    error.

erl_msg_tracer.c*

#include <erl_nif.h>

/* NIF interface declarations */
static int load(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info);
static int upgrade(ErlNifEnv* env, void** priv_data, void** old_priv_data, ERL_NIF_TERM load_info);
static void unload(ErlNifEnv* env, void* priv_data);

/* The NIFs: */
static ERL_NIF_TERM enabled(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);

static ErlNifFunc nif_funcs[] = {
    {"enabled", 3, enabled},
    {"trace", 5, trace}
};

ERL_NIF_INIT(erl_msg_tracer, nif_funcs, load, NULL, upgrade, unload)

static int load(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info)
{
    *priv_data = NULL;
    return 0;
}

static void unload(ErlNifEnv* env, void* priv_data)
{

}

static int upgrade(ErlNifEnv* env, void** priv_data, void** old_priv_data,
		   ERL_NIF_TERM load_info)
{
    if (*old_priv_data != NULL || *priv_data != NULL) {
	return -1; /* Don't know how to do that */
    }
    if (load(env, priv_data, load_info)) {
	return -1;
    }
    return 0;
}

/*
 * argv[0]: TraceTag
 * argv[1]: TracerState
 * argv[2]: Tracee
 */
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], &to_pid))
        if (!enif_is_process_alive(env, &to_pid))
            if (enif_is_identical(enif_make_atom(env, "trace_status"), argv[0]))
                /* tracer is dead so we should remove this tracepoint */
                return enif_make_atom(env, "remove");
            else
                return enif_make_atom(env, "discard");

    /* Only generate trace for when tracer != tracee */
    if (enif_is_identical(argv[1], argv[2]))
        return enif_make_atom(env, "discard");

    /* Only trigger trace messages on 'send' */
    if (enif_is_identical(enif_make_atom(env, "send"), argv[0]))
        return enif_make_atom(env, "trace");

    /* Have to answer trace_status */
    if (enif_is_identical(enif_make_atom(env, "trace_status"), argv[0]))
        return enif_make_atom(env, "trace");

    return enif_make_atom(env, "discard");
}

/*
 * argv[0]: TraceTag, should only be 'send'
 * argv[1]: TracerState, process to send {Tracee, Recipient} to
 * argv[2]: Tracee
 * argv[3]: Message
 * argv[4]: Options, map containing Recipient
 */
static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
{
    ErlNifPid to_pid;
    ERL_NIF_TERM recipient, msg;

    if (enif_get_local_pid(env, argv[1], &to_pid)) {
      if (enif_get_map_value(env, argv[4], enif_make_atom(env, "extra"), &recipient)) {
        msg = enif_make_tuple3(env, enif_make_atom(env, "trace"), argv[2], recipient);
        enif_send(env, &to_pid, NULL, msg);
      }
    }

    return enif_make_atom(env, "ok");
}