ttb

TTB

模块

TTB

模块摘要

为分布式系统构建跟踪工具的基础。

描述

跟踪工具生成器ttb是构建分布式系统跟踪工具的基础。

使用时ttb，请勿使dbg在应用程序Runtime_Tools中并行使用模块。

输出

start_trace(Nodes, Patterns, FlagSpec, Opts) -> Result

类型

这个功能是一个允许用一个命令开始追踪的快捷方式。每个元组都Patterns被转换为一个列表，然后传递给列表ttb:tpl/2,3,4。

调用：

> ttb:start_trace([Node, OtherNode], [{mod, foo, []}, {mod, bar, 2}], {all, call}, [{file, File}, {handler,{fun myhandler/4, S}}]).

相当于：

> ttb:start_trace([Node, OtherNode], [{file, File}, {handler,{fun myhandler/4, S}}]), ttb:tpl(mod, foo, []), ttb:tpl(mod, bar, 2, []), ttb:p(all, call).

tracer() -> Result

相当于tracer(node())...

tracer(Shortcut) -> Result

类型

通用跟踪设置的便捷快捷方式。

shell等于tracer(node(),[{file, {local, "ttb"}}, shell])...

dbg等于tracer(node(),[{shell, only}])...

tracer(Nodes) -> Result

相当于tracer(Nodes,[])...

tracer(Nodes,Opts) -> Result

类型

在所有指定节点上启动文件跟踪端口，并将系统跟踪程序指向同一端口。

备选方案：

Filename

指定Filename的前缀是节点名称。默认Filename是ttb。

File={wrap,Filename,Size,Count}

如果跟踪日志的大小必须受限，可以使用。默认值是Size=128*1024和Count=8。

Client

跟踪无盘节点时，ttb必须从具有磁盘访问权限的外部“跟踪控制节点”启动，并且Client必须是{local, File}。所有跟踪信息随后会发送到跟踪控制节点，并在此处写入文件。

queue_size

跟踪到shell或{local,File}内部使用ip跟踪驱动程序时。IP跟踪驱动程序有一个QueueSize等待传送的最大消息队列。如果驱动程序不能像生成邮件一样快速发送邮件，则可能会超出队列大小并丢弃邮件。该参数是可选的，并且仅{drop,N}在跟踪处理程序接收到许多跟踪消息时才有用。它没有意义，如果壳或{local,File}不使用。请参阅dbg:trace_port/2有关ip跟踪驱动程序的更多信息。

process_info

指示是否收集过程信息。如果PI = true（默认情况下），每个进程标识符Pid被替换为一个元组{Pid,ProcessInfo,Node}，其中ProcessInfo是注册进程名称，其全局注册名称或其初始功能。要关闭此功能，请设置PI = false。

{shell, ShellSpec}

表示跟踪消息将在跟踪过程中收到时在控制台上打印。这意味着跟踪客户端{local, File}。如果ShellSpec是only（而不是true），则不存储跟踪日志。

shell

捷径{shell, true}...

timer

指示跟踪将在MSec毫秒后自动停止。如果指定，StopOpts则传递给命令ttb:stop/2（默认为[]）。注意时间是近似的，因为与网络通信相关的延迟总是存在。计时器在ttb:p/2发布后开始，因此您可以在之前设置您的跟踪模式。

overload_check

允许在跟踪下的节点上启用重载检查。Module:Function(check)每个MSec毫秒。如果检查返回true，则在指定的节点上禁用跟踪。

Module:Function必须能够处理至少三个原子：init，check，和stop。init与stop允许您初始化和清理检查环境。

当一个节点超载时，不可能发布ttb:p/2或者来自ttb:tp/2,3,4家族的任何命令，因为这会导致不一致的跟踪状态（不同节点上的不同跟踪规范）。

flush

定期刷新所有文件跟踪端口客户端（请参阅dbg:flush_trace_port/1）。启用时，缓冲区每MSec毫秒释放一次。{file, {local, File}}跟踪时不允许使用此选项。

{resume, FetchTimeout}

启用自动恢复功能。启用时，远程节点尝试重新连接到控制节点（如果它们重新启动）。该功能需要启动应用程序Runtime_Tools（因此，.boot如果跟踪的节点使用嵌入式Erlang运行，它必须存在于脚本中）。如果这不可行，可以通过Runtime_Tools远程启动手动执行恢复rpc:call/4。

ttb尝试在重新初始化跟踪之前从重新连接节点获取所有日志。这必须在FetchTimeout毫秒或被中止。

默认情况下，自动启动信息存储在ttb_autostart.bin每个节点上命名的文件中。如果不需要（例如，在无盘节点上），可以通过ttb_autostart_module为应用程序Runtime_Tools 指定环境变量来提供处理自动启动信息存储和检索的自定义模块。该模块必须响应以下API：

write_config(Data) -> ok

存储所提供的数据以供进一步检索。必须认识到所使用的数据存储不受节点崩溃的影响。

read_config() -> {ok, Data} | {error, Error}

检索存储在write_config(Data)...

delete_config() -> ok

删除存储的配置write_config(Data)。请注意，在此调用之后，任何后续调用都read_config必须返回{error, Error}。

resume意味着默认值FetchTimeout，即10秒

p(Item,Flags) -> Return

类型

在指定的进程或端口上设置指定的跟踪标志。标志timestamp始终打开。

有关可能的跟踪标志，请参阅模块dbg的参考手册。参数MatchDesc与从dbg：p / 2返回的相同。

可以将进程指定为注册名称，全局注册名称或进程标识符。端口可以被指定为注册名称或端口标识符。如果指定了注册名称，则在所有活动节点上使用该名称在进程/端口上设置标志。

发出此命令将启动此跟踪if选项的定时器。timer被指定为tracer/2...

tp, tpl, tpe, ctp, ctpl, ctpg, ctpe

这些功能是使用跟踪标记一起使用call，send以及'receive'用于设置和清除迹线图案。

在call进程上设置跟踪标志时，如果为被调用函数设置了跟踪模式，则会在该进程上跟踪函数调用。

send和'receive'标志使得能够通过处理/端口发送和接收的所有消息的跟踪。跟踪模式tpe可能会根据消息内容，发件人和/或接收者限制跟踪消息。

跟踪模式通过使用匹配规范指定如何跟踪函数或消息。匹配规格描述在ERTS User's Guide。

这些功能与模块中的相应功能相同dbg，但所有调用都存储在历史记录中。历史缓冲区可以很容易地创建配置文件; 可以多次设置相同的跟踪环境，例如，比较两次测试运行。它还减少了ttb从Erlang shell 使用时的键入量。

tp

设置全局函数调用的跟踪模式。

tpl

设置本地和全局函数调用的跟踪模式。

tpe

在消息上设置跟踪模式。

ctp

清除本地和全局函数调用的跟踪模式。

ctpl

清除本地函数调用的跟踪模式。

ctpg

清除全局函数调用的跟踪模式。

ctpe

清除消息上的跟踪模式。

使用tp和tpl，可以使用匹配规范快捷键之一（例如，ttb:tp(foo_module, caller)）。

捷径如下：

return- 用于 [{'_',[],[{return_trace}]}]（报告跟踪函数的返回值）

caller- 用于[{'_',[],[{message,{caller}}]}]（报告调用功能）

{codestr, Str}-对于dbg:fun2ms/1作为字符串传递的参数（例如："fun(_) -> return_trace() end"）

list_history() -> History

类型

所有对ttb的呼叫都存储在历史记录中。该函数返回历史的当前内容。任何条目都可以使用run_history / 1重新执行，或使用write_config / 2,3存储在配置文件中。

run_history(N) -> ok | {error, Reason}

类型

从历史列表中执行指定的一个或多个条目。要列出历史记录，请使用list_history/0。

write_config(ConfigFile,Config)

相当于write_config(ConfigFile,Config,[])...

write_config(ConfigFile,Config,Opts) -> ok | {error,Reason}

类型

创建或扩展配置文件，该文件可用于稍后恢复特定配置。

配置文件的内容可以从历史记录中获取，也可以直接指定为列表{Mod,Func,Args}。

如果要将完整的历史记录存储在配置文件中，Config一定是all如果只存储历史记录中选定的条目数，Config必须是指向要存储的条目的整数列表。

如果Opts没有指定，或者如果它是[]，ConfigFile被删除，并创建一个新文件。如果Opts = [append]，ConfigFile不被删除。新信息附加在文件的末尾。

run_config(ConfigFile) -> ok | {error,Reason}

类型

执行指定配置文件中的所有条目。请注意，最后一个跟踪的历史记录始终在文件中可用ttb_last_config。

run_config(ConfigFile,NumList) -> ok | {error,Reason}

类型

从指定的配置文件中执行选定的条目。NumList是指出要执行的条目的整数列表。

要列出配置文件的内容，请使用list_config/1。

请注意，最后一个跟踪的历史记录始终在文件中可用ttb_last_config。

list_config(ConfigFile) -> Config | {error,Reason}

类型

列出指定配置文件中的所有条目。

write_trace_info(Key,Info) -> ok

类型

文件.ti包含{Key,ValueList}元组。该功能添加Data到ValueList关联的Key。使用此函数编写的所有信息都包含在对格式处理程序的调用中。

seq_trigger_ms() -> MatchSpec

相当于seq_trigger_ms(all)。

seq_trigger_ms(Flags) -> MatchSpec

类型

匹配规范可以打开或关闭顺序跟踪。该函数返回一个匹配规范，该规范将打开指定的顺序跟踪Flags。

该匹配规范可以被指定为tp或tpl的最后一个参数。激活的Item然后成为顺序跟踪的触发器。这意味着如果在跟踪标志调用集合的进程上调用该项目，则该过程会被令牌seq_trace“污染”。

如果Flags = all，设置了所有可能的标志。

可能的值在SeqTraceFlag中可用seq_trace。

有关match_spec()语法的描述，请参阅Match Specifications in ErlangERTS中的一节，其中解释了一般匹配规范“语言”。

注

顺序跟踪的系统跟踪器是ttb在跟踪端口启动时自动启动的ttb:tracer/0,1,2。

如何使用函数的示例seq_trigger_ms/0,1如下：

(tiger@durin)5> ttb:tracer().
{ok,[tiger@durin]}
(tiger@durin)6> ttb:p(all,call).
{ok,{[all],[call]}}
(tiger@durin)7> ttb:tp(mod,func,ttb:seq_trigger_ms()).
{ok,[{matched,1},{saved,1}]}
(tiger@durin)8>

无论何时mod:func(...)在此之后调用，令牌seq_trace都会在执行过程中设置。

stop()

相当于stop([])...

stop(Opts) -> stopped | {stopped, Dir}

类型

停止在所有节点上进行跟踪。日志和跟踪信息文件被发送到跟踪控制节点，并存储在一个名为ttb_upload_FileName-Timestamp的目录中，其中Filename是在跟踪设置期间由{file，File}提供的目录，Timestamp的格式为yyyymmdd-hhmmss。即使是来自跟踪控制节点所在的机器上的节点的日志也会被移至此目录。历史列表被保存到一个名为ttb_last_config的文件中作为进一步参考（因为它不再可以通过历史和配置管理功能，如ttb：list_history / 0访问）。

备选方案：

nofetch

指示停止跟踪后不收集跟踪日志。

{fetch, Dir}

允许指定目录来获取数据到。如果目录已经存在，则引发错误。

format

指示停止跟踪后要格式化的跟踪日志。提取目录中的所有日志都将合并。

return_fetch_dir

指示返回值是{stopped, Dir}，而不仅仅是stopped。这意味着fetch。

get_et_handler()

返回et可以与format/2or 一起使用的处理程序tracer/2。

例子：ttb:format(Dir, [{handler, ttb:get_et_handler()}])...

format(File)

相当于format(File,[])...

format(File,Options) -> ok | {error, Reason}

类型

这可以是二进制日志的名称、此类日志的列表，或者包含一个或多个二进制日志的目录的名称。

   File descriptor of the destination file `Out`.  The trace message. For details, see the Reference Manual for module `erlang`.  Includes the keys `flags`, `client`, and `node`. If `handler` is specified as option to the tracer function, this is also included. Also, all information written with function `write_trace_info/2` is included.

读取指定的二进制跟踪日志。只要disable_sort未指定选项，日志就会按照时间戳的顺序进行处理。

如果FormatHandler = {Function,InitialState}，Function为每个跟踪消息调用。

如果FormatHandler = get_et_handler()，et_viewer在应用ET用于图形呈现跟踪日志。ttb提供了几个不同的过滤器，可以从菜单中的过滤器和缩放中选择et_viewer。

如果FormatHandler如果不指定，则使用默认处理程序将每个跟踪消息表示为文本行。

每次调用函数返回的状态都将传递给下一个调用，即使下一次调用是从另一个日志文件格式化消息。

如果Out指定，则FormatHandler获取文件描述符Out作为第一个参数。

如果使用et格式处理程序，则忽略输出。

换行日志可以一个接一个地或一次全部格式化。要格式化其中一个换行日志，请指定确切的文件名。要格式化整套换行日志，请指定名称*而不是换行计数。例如，请参阅User's Guide。