dyntrace

模块

动态轨迹

模块摘要

动态跟踪接口

描述

该模块实现了动态跟踪接口，如果这样编译到虚拟机中。对于标准和/或商业构建，没有动态跟踪可用，在这种情况下，该模块中的任何功能都无法使用或产生任何效果。

如果要在当前版本中启用动态跟踪，可以通过使用./configure --with-dynamic-trace=dtrace或使用./configure --with-dynamic-trace=systemtap该模块进行配置，该模块可用于两件事情：

• 通过调用触发user_trace_i4s4NIF库中的用户探测。dyntrace.sodyntrace:p/{1,2,3,4,5,6,7,8}

• 设置一个用户指定的标记，该标记将出现在两个efile_drv以及上面提到的用户探针。

动态跟踪探针的建立和使用都是实验性质的，不受Erlang/OTP的支持。它是开发人员跟踪和调试其系统中的性能问题的选项。

最初的实现主要是由ScottLystigerFritchie作为一个开源贡献来完成的，尽管主要发行版中包含了动态跟踪的源代码以及这个模块，但它应该被视为开源。但是，使用虚拟机动态跟踪的能力是OTP作为开发人员的工具进行维护的一个非常有价值的贡献。

如何编写d程序或systemtap脚本可以从书本和互联网上的许多页面中学习。本手册页不包含任何有关使用相应平台的动态跟踪工具的文档。然而examples，该runtime_tools应用程序的目录包含了全面的两个例子d和systemtap程序，可以帮助您入门。另一个信息来源是dtrace和systemtap章运行时工具用户的指南中。

出口

available() -> boolean()

此函数使用NIF库来确定动态跟踪是否可用。通常叫erlang:system_info/1是动态跟踪可用性的更好指标。

函数将引发异常，如果dyntrace无法由ON加载NIF库。[医]该模块的加载功能。

p() -> true | false | error | badarg

调用此函数将触发“用户”跟踪探测用户。[医]痕迹[医]i4s4在dyntraceNIF模块中，只发送一个跟踪消息，其中只包含用户标记和所有其他字段中的零/空字符串。

p(integer() | string()) -> true | false | error | badarg

调用此函数将触发dyntrace NIF模块中的“用户”跟踪探测器user_trace_i4s4，并在第一个整数/字符串字段中发送包含用户标记和整数或字符串参数的跟踪消息。

p(integer() | string(), integer() | string()) -> true | false | error | badarg

调用此函数将触发dyntrace NIF模块中的“用户”跟踪探测器user_trace_i4s4，并发送包含用户标记和整数（）或字符串（）参数的跟踪消息作为相应类型的第一个字段。integer（）参数应放在任何string（）参数之前。即p(1,"Hello")是确定的，因为是p(1,1)和p("Hello","Again")，但不会p("Hello",1)。

p(integer() | string(), integer() | string(), integer() | string()) -> true | false | error | badarg

调用此函数将触发dyntrace NIF模块中的“用户”跟踪探测器user_trace_i4s4，并发送包含用户标记和整数（）或字符串（）参数的跟踪消息作为相应类型的第一个字段。integer（）参数应放在任何string（）参数之前，如p/2。

p(integer() | string(), integer() | string(), integer() | string(), integer() | string()) -> true | false | error | badarg

调用此函数将触发dyntrace NIF模块中的“用户”跟踪探测器user_trace_i4s4，并发送包含用户标记和整数（）或字符串（）参数的跟踪消息作为相应类型的第一个字段。integer（）参数应放在任何string（）参数之前，如p/2。

p(integer(), integer() | string(), integer() | string(), integer() | string(), string()) -> true | false | error | badarg

调用此函数将触发dyntrace NIF模块中的“用户”跟踪探测器user_trace_i4s4，并发送包含用户标记和整数（）或字符串（）参数的跟踪消息作为相应类型的第一个字段。integer（）参数应放在任何string（）参数之前，如p/2。

任何类型（integer（）或string（））的参数不能超过四个，所以第一个参数必须是整数（），最后一个是字符串（）。

p(integer(), integer(), integer() | string(), integer() | string(), string(), string()) -> true | false | error | badarg

调用此函数将触发dyntrace NIF模块中的“用户”跟踪探测器user_trace_i4s4，并发送包含用户标记和整数（）或字符串（）参数的跟踪消息作为相应类型的第一个字段。integer（）参数应放在任何string（）参数之前，如p/2。

There can be no more than four parameters of any type (integer() or string()), so the first two parameters has to be integer()'s and the last two string()'s.

p(integer(), integer(), integer(), integer() | string(), string(), string(), string()) -> true | false | error | badarg

调用此函数将触发dyntrace NIF模块中的“用户”跟踪探测器user_trace_i4s4，并发送包含用户标记和整数（）或字符串（）参数的跟踪消息作为相应类型的第一个字段。integer（）参数应放在任何string（）参数之前，如p/2。

任何类型（integer（）或string（））的参数不能超过四个，所以前三个参数必须是integer（）和最后三个字符串（）。

p(integer(), integer(), integer(), integer(), string(), string(), string(), string()) -> true | false | error | badarg

调用此函数将触发dyntrace NIF模块中的“用户”跟踪探测器user_trace_i4s4，发送包含提供的所有整数（）和string（）以及当前进程中设置的任何用户标记的跟踪消息。

get_tag() -> binary() | undefined

该函数返回当前进程中设置的用户标签。如果未设置标签或动态跟踪不可用，则返回undefined

get_tag() -> binary() | undefined

该函数返回在当前进程中设置的用户标记，或者如果没有用户标记，则将最后一个用户标记与消息一起发送（与使用消息一起sequential trace tokens传播到其他进程一样）。有关用户标签如何与消息一起传播，请参阅spread_tag/1。如果未找到标签或动态跟踪不可用，则返回undefined

put_tag(Item) -> binary() | undefined

类型

该函数设置当前进程的用户标记。用户标记是二进制（），但可以指定为任何iodata（），该函数会自动将该函数转换为二进制文件。

用户标记被提供给由调用top触发的用户探测。dyntrace:p/{1,2,3,4,5,6,7,8}以及在飞艇中的探测[医]司机。将来，用户标记可能会添加到更多的探测中。

旧的用户标记（如果有的话）被返回，或者undefined如果没有用户标记存在或者动态跟踪未被启用。

spread_tag(boolean()) -> TagData

类型

该功能控制用户标签是否要通过下一条消息传播到其他进程。用户标签的传播工作就像传播顺序跟踪令牌一样，这样接收到的用户标签将在过程中处于活动状态，直到下一条消息到达（如果该消息不包含用户标签。

当客户进程与文件I / O服务器进行通信以将用户标记分发到I / O服务器，然后传递到efile_drv驱动程序时，会使用此功能。通过使用spread_tag/1和restore_tag/1，可以启用或禁用将用户标记传播到其他进程，然后恢复用户标记的以前状态。从此调用返回的TagData包含所有先前的信息，以便状态（包括任何先前传播的用户标记）在以后的调用中完全恢复restore_tag/1。

该file模块已经传播了标签，所以没有必要手动调用这些函数来通过该模块将用户标签传播到efile驱动程序。

此函数的最大用途是，例如，如果使用io模块与常规文件的I/O服务器进行通信，如下面的示例所示：

f() ->
   {ok, F} = file:open("test.tst",[write]),
   Saved = dyntrace:spread_tag(true),
   io:format(F,"Hello world!",[]),
   dyntrace:restore_tag(Saved),
   file:close(F).

在本例中，调用过程中设置的任何用户标记将在io：Format调用完成时传播到I/O服务器。

restore_tag(TagData) -> true

类型

恢复以前的用户标记状态及其扩展，就像调用spread_tag/1请注意，还原不限于同一进程，您可以利用此过程关闭一个进程中的spreding，并将其还原到一个新创建的进程中，即实际要发送消息的进程：

f() ->
    TagData=dyntrace:spread_tag(false),
    spawn(fun() ->
             dyntrace:restore_tag(TagData),
             do_something()
          end),
    do_something_else(),
    dyntrace:restore_tag(TagData).

正确处理用户标签及其传播可能需要一些努力，因为Erlang程序倾向于发送和接收消息，以便有时由于各种事情（例如，双重接收或与端口的通信（端口不处理用户标签，就像他们不处理常规的顺序跟踪令牌一样）。