PageRenderTime 55ms CodeModel.GetById 13ms RepoModel.GetById 1ms app.codeStats 0ms

/erlang_otp/lib/inviso-0.6/doc/html/inviso.html

https://bitbucket.org/docs/docs.bitbucket.org
HTML | 850 lines | 843 code | 7 blank | 0 comment | 0 complexity | 95f10ef37bb460071121ccc623f9c152 MD5 | raw file
    

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    2. 

  2.   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    3. 

  3. 

  4. <html xmlns="http://www.w3.org/1999/xhtml">
    5. 

  5.   <head>
    6. 

  6.     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    7. 

  7.     
    8. 

  8.     <title>Lib - Inviso-0.6 - Doc - Html - Inviso &mdash; Erlang/OTP vR13B02 documentation</title>
    9. 

  9.     <link rel="stylesheet" href="../../../../_static/default.css" type="text/css" />
    10. 

  10.     <link rel="stylesheet" href="../../../../_static/pygments.css" type="text/css" />
    11. 

  11.     <script type="text/javascript">
    12. 

  12.       var DOCUMENTATION_OPTIONS = {
    13. 

  13.         URL_ROOT:    '../../../../',
    14. 

  14.         VERSION:     'R13B02',
    15. 

  15.         COLLAPSE_MODINDEX: false,
    16. 

  16.         FILE_SUFFIX: '.html',
    17. 

  17.         HAS_SOURCE:  true
    18. 

  18.       };
    19. 

  19.     </script>
    20. 

  20.     <script type="text/javascript" src="../../../../_static/jquery.js"></script>
    21. 

  21.     <script type="text/javascript" src="../../../../_static/doctools.js"></script>
    22. 

  22.     <link rel="top" title="Erlang/OTP vR13B02 documentation" href="../../../../index.html" /> 
    23. 

  23.   </head>
    24. 

  24.   <body>
    25. 

  25.     <div class="related">
    26. 

  26.       <h3>Navigation</h3>
    27. 

  27.       <ul>
    28. 

  28.         <li class="right" style="margin-right: 10px">
    29. 

  29.           <a href="../../../../genindex.html" title="General Index"
    30. 

  30.              accesskey="I">index</a></li>
    31. 

  31.         <li><a href="../../../../index.html">Erlang/OTP vR13B02 documentation</a> &raquo;</li> 
    32. 

  32.       </ul>
    33. 

  33.     </div>  
    34. 

  34. 

  35.     <div class="document">
    36. 

  36.       <div class="documentwrapper">
    37. 

  37.         <div class="bodywrapper">
    38. 

  38.           <div class="body">
    39. 

  39.             
    40. 

  40.   <div class="section" id="lib-inviso-0-6-doc-html-inviso">
    41. 

  41. <h1>Lib - Inviso-0.6 - Doc - Html - Inviso<a class="headerlink" href="#lib-inviso-0-6-doc-html-inviso" title="Permalink to this headline"></a></h1>
    42. 

  42. <p>` &lt;<a class="reference external" href="http://www.ericsson.com/technology/opensource/erlang">http://www.ericsson.com/technology/opensource/erlang</a>&gt;`__</p>
    43. 

  43. <div class="section" id="inviso">
    44. 

  44. <h2>inviso<a class="headerlink" href="#inviso" title="Permalink to this headline"></a></h2>
    45. 

  45. <div class="section" id="module">
    46. 

  46. <h3>MODULE<a class="headerlink" href="#module" title="Permalink to this headline"></a></h3>
    47. 

  47. <p>inviso</p>
    48. 

  48. </div>
    49. 

  49. <div class="section" id="module-summary">
    50. 

  50. <h3>MODULE SUMMARY<a class="headerlink" href="#module-summary" title="Permalink to this headline"></a></h3>
    51. 

  51. <p>Main API Module to the Inviso Tracer</p>
    52. 

  52. </div>
    53. 

  53. <div class="section" id="description">
    54. 

  54. <h3>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline"></a></h3>
    55. 

  55. <p>With the inviso API runtime components can be started and tracing
    56. 

  56. managed across a network of distributed Erlang nodes, using a control
    57. 

  57. component also started with inviso API functions.</p>
    58. 

  58. <p>Inviso can be used both in a distributed environment and in a non-
    59. 

  59. distributed. API functions not taking a list of nodes as argument
    60. 

  60. works on all started runtime components. If it is the non-distributed
    61. 

  61. case, that is the local runtime component. The API functions taking a
    62. 

  62. list of nodes as argument, or as part of one of the arguments, can not
    63. 

  63. be used in a non-distributed environment. Return values named
    64. 

  64. NodeResult refers to return values from a single Erlang node, and will
    65. 

  65. therefore be the return in the non-distributed environment.</p>
    66. 

  66. </div>
    67. 

  67. <div class="section" id="exports">
    68. 

  68. <h3>EXPORTS<a class="headerlink" href="#exports" title="Permalink to this headline"></a></h3>
    69. 

  69. <p>start() -&gt; {ok,pid()} | {error,Reason}
    70. 

  70. start(Options) -&gt; {ok,pid()} | {error,Reason}</p>
    71. 

  71. <p>Types:</p>
    72. 

  72. <p>Options = [Option]</p>
    73. 

  73. <p>Options may contain both options which will be default options to a
    74. 

  74. runtime component when started, and options to the control component.
    75. 

  75. See add_nodes/3 for details on runtime component options. The control
    76. 

  76. component recognizes the following options:</p>
    77. 

  77. <table class="docutils field-list" frame="void" rules="none">
    78. 

  78. <col class="field-name" />
    79. 

  79. <col class="field-body" />
    80. 

  80. <tbody valign="top">
    81. 

  81. <tr class="field"><th class="field-name" colspan="2">{subscribe,Pid}:</th></tr>
    82. 

  82. <tr><td>&nbsp;</td><td class="field-body">Making the process Pid receive Inviso events from
    83. 

  83. the control component. Starts a control component process on the local
    84. 

  84. node. A control component must be started before runtime components
    85. 

  85. can be started manually or otherwise accessed through the inviso API.</td>
    86. 

  86. </tr>
    87. 

  87. </tbody>
    88. 

  88. </table>
    89. 

  89. <p>stop() -&gt; shutdown</p>
    90. 

  90. <p>Stops the control component. Runtime components are left as is. They
    91. 

  91. will behave according to their dependency values.</p>
    92. 

  92. <p>add_node(RTtag) -&gt; NodeResult | {error,Reason}
    93. 

  93. add_node(RTtag,Options) -&gt; NodeResult | {error,Reason}</p>
    94. 

  94. <p>Types:</p>
    95. 

  95. <p>RTtag = PreviousRTtag = term()
    96. 

  96. Options = [Option]
    97. 

  97. ?Option &#8211; see below
    98. 

  98. ?Option = {dependency,Dep}
    99. 

  99. ??Dep = int() | infinity</p>
    100. 

  100. <p>The timeout, in milliseconds, before the runtime component will
    101. 

  101. terminate if abandoned by this control component. ?Option =
    102. 

  102. {overload,Overload} | overload
    103. 

  103. Controls how and how often overload checks shall be performed. Just
    104. 

  104. overloadspecifies that no loadcheck shall be performed. ??Overload =
    105. 

  105. Interval | {LoadMF,Interval,InitMFA,RemoveMFA}
    106. 

  106. ???LoadMF = {Mod,Func} | function()/1
    107. 

  107. ???Interval = int() | infinity
    108. 

  108. Interval is the time in milliseconds between overload checks.
    109. 

  109. ???InitMFA = RemoveMFA = {Mod,Func,ArgList} | void
    110. 

  110. When starting up the runtime component or when changing options (see
    111. 

  111. change_options/2) the overload mechanism is initialized with a call to
    112. 

  112. the InitMFAfunction. It shall return LoadCheckData. Every time a load
    113. 

  113. check is performed, LoadMFis called with LoadCheckDataas its only
    114. 

  114. argument. LoadMFshall return okor {suspend,Reason}. When the runtime
    115. 

  115. component is stopped or made to change options involving changing
    116. 

  116. overload-check, the RemoveMFAfunction is called. Its return value is
    117. 

  117. discarded. NodeResult = {ok,NAns} | {error,Reason}
    118. 

  118. ?NAns = new | {adopted,State,Status,PreviousRTtag} | already_added
    119. 

  119. ??State = new | tracing | idle
    120. 

  120. ??Status = running | {suspended,SReason}</p>
    121. 

  121. <p>Starts or tries to connect to an existing runtime component at the
    122. 

  122. local node, regardless if the system is distributed or not. Options
    123. 

  123. will override any default options specified at start-up of the control
    124. 

  124. component.</p>
    125. 

  125. <p>The PreviousRTtag can indicate if the incarnation of the runtime
    126. 

  126. component at the node in question was started by &#8220;us&#8221; and then can be
    127. 

  127. expected to do tracing according to &#8220;our&#8221; instructions or not.</p>
    128. 

  128. <p>add_node_if_ref(RTtag) -&gt; NodeResult |
    129. 

  129. {error,{wrong_reference,OtherTag}} | {error,Reason}
    130. 

  130. add_node_if_ref(RTtag,Options) -&gt; NodeResult |
    131. 

  131. {error,{wrong_reference,OtherRef}} | {error,Reason}</p>
    132. 

  132. <p>Types:</p>
    133. 

  133. <p>OtherRef = term()</p>
    134. 

  134. <p>rttag of the running incarnation
    135. 

  135. As add_node/1,2 but will only adopt the runtime component if its rttag
    136. 

  136. is RTtag.</p>
    137. 

  137. <p>add_nodes(Nodes,RTtag) -&gt; {ok,NodeResults} | {error,Reason}
    138. 

  138. add_nodes(Nodes,RTtag,Options) -&gt; {ok,NodeResults} | {error,Reason}</p>
    139. 

  139. <p>Types:</p>
    140. 

  140. <p>Nodes = [Node]
    141. 

  141. NodeResults = [{Node,NodeResult}]</p>
    142. 

  142. <p>As add_node/1,2 but for a distributed environment.</p>
    143. 

  143. <p>add_nodes_if_ref(Nodes,RTtag) -&gt; NodeResult | {error,Reason}
    144. 

  144. add_nodes_if_ref(Nodes,RTtag,Options) -&gt; NodeResult | {error,Reason}</p>
    145. 

  145. <p>Types:</p>
    146. 

  146. <p>Nodes = [Node]
    147. 

  147. NodeResults = [{Node,NodeResult}]</p>
    148. 

  148. <p>As add_node_if_ref/1,2 but for a distributed environment.</p>
    149. 

  149. <p>stop_nodes() -&gt; {ok,NodeResults} | NodeResult
    150. 

  150. stop_nodes(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
    151. 

  151. <p>Types:</p>
    152. 

  152. <p>NodeResults = [{Node,NodeResult}]
    153. 

  153. NodeResult = ok | {error,Reason}</p>
    154. 

  154. <p>Stops runtime component on Nodes. stop_nodes/0 will if the control
    155. 

  155. component is running on a distributed node stop all runtime
    156. 

  156. components. And if running on a non distributed node, stop the local
    157. 

  157. and only runtime component.</p>
    158. 

  158. <p>stop_all() = {ok,NodeResults} | NodeResult</p>
    159. 

  159. <p>Types:</p>
    160. 

  160. <p>NodeResults = [{Node,NodeResult}]
    161. 

  161. NodeResult = ok | {error,Reason}</p>
    162. 

  162. <p>A combination of stop/0 and stop_nodes/0.</p>
    163. 

  163. <p>change_options(Options) -&gt; NodeResult | {ok,NodeResults} |
    164. 

  164. {error,Reason}
    165. 

  165. change_options(Nodes,Options) -&gt; {ok,NodeResults} | {error,Reason}</p>
    166. 

  166. <p>Types:</p>
    167. 

  167. <p>Nodes = [Node]
    168. 

  168. NodeResults = [{Node,NodeResult}]
    169. 

  169. NodeResult = ok | {error,Reason}</p>
    170. 

  170. <p>Changes the options for one or several runtime components. If for
    171. 

  171. instance overload is redefined, the previous overload will be stopped
    172. 

  172. and the new started. See add_node/1 for details on Options.</p>
    173. 

  173. <p>init_tracing(TracerData) -&gt; {ok,NodeResults} | NodeResult |
    174. 

  174. {error,Reason}
    175. 

  175. init_tracing(TracerList) -&gt; {ok,NodeResults} | {error,Reason}
    176. 

  176. init_tracing(Nodes,TracerData) -&gt; {ok,NodeResults} | {error,Reason}</p>
    177. 

  177. <p>Types:</p>
    178. 

  178. <p>TracerData = [{trace,LogTD} [,{ti,TiTD}] }] | LogTD
    179. 

  179. LogTD = {HandlerFun,Data1} | collector | {relayer,CollectingNode} |
    180. 

  180. {ip,IPPortParameters} | {file,FilePortParameters}
    181. 

  181. TiTD = {file,FileName} | {file,FileName,TiSpec} | {relay,Node}
    182. 

  182. ?TiSpec = {InitMFA,RemoveMF,CleanMF}
    183. 

  183. ??InitMFA = {Mi,Fi,Argsi}
    184. 

  184. ??RemoveMF = {Mr,Fr} | void
    185. 

  185. ??CleanMF = {Mc,Fc}
    186. 

  186. ??Mi = Fi = Mr = Fr = Mc = Fd = atom()
    187. 

  187. ??Argsi = [term()]
    188. 

  188. TracerList = [{Node,TracerData}]
    189. 

  189. IPPortParameters = Portno | {Portno,Qsize}
    190. 

  190. ?Portno = tcp_portno()
    191. 

  191. ?Qsize = int()
    192. 

  192. FilePortParameters = {Filename,wrap,Tail,{time,WrapTime},WrapCnt} |
    193. 

  193. {FileName,wrap,Tail,WrapSize,WrapCnt} | {FileName,wrap,Tail,WrapSize}
    194. 

  194. | {FileName,wrap,Tail} | FileName
    195. 

  195. ?FileName = string()
    196. 

  196. ?Tail = string() =/= &#8220;&#8221;
    197. 

  197. ?WrapTime = WrapCnt = WrapSize = int() &gt;0
    198. 

  198. TracerList = [{Node,TracerData}]
    199. 

  199. Nodes = [Node]
    200. 

  200. HandlerFun = function()/2;
    201. 

  201. ?HandlerFun(TraceMsg,Data1) -&gt; NewData
    202. 

  202. CollectingNode = pid() | node()
    203. 

  203. NodeResults = [{Node,NodeResult}]
    204. 

  204. NodeResult = {ok,LogResults} | {error,NReason}
    205. 

  205. ?LogResults = [LogResult]
    206. 

  206. ??LogResult = {trace_log,LogRes} | {ti_log,LogRes}
    207. 

  207. ???LogRes = ok | {error,Reason}</p>
    208. 

  208. <p>Starts the tracing at the specified nodes, meaning that the runtime
    209. 

  209. components transits from the state new or idle to tracing. For trace
    210. 

  210. messages to be generated, there must of course also be trace pattern
    211. 

  211. and/or trace flags set. Such can not be set before tracing has been
    212. 

  212. initiated with init_tracing/1,2.</p>
    213. 

  213. <p>TracerData controls how the runtime component will handle generated
    214. 

  214. trace messages. The trace tag controls how regular trace messages are
    215. 

  215. handled. The ti tag controls if and how trace information will be
    216. 

  216. stored and the meta tracer will be activated. That is if ti is
    217. 

  217. omitted, no meta tracer will be started as part of the runtime
    218. 

  218. component. It is possible to have ti without trace, but most likely
    219. 

  219. not useful.</p>
    220. 

  220. <p>The ip and file trace tracerdata instructions results in using the
    221. 

  221. built in trace ip-port and file-port respectively. relayer will result
    222. 

  222. in that all regular trace messages are forwarded to a runtime
    223. 

  223. component at the specified node. Using a HandlerFun will result in
    224. 

  224. that every incoming regular trace message is applied to the
    225. 

  225. HandlerFun. collector can be used to use this runtime component to
    226. 

  226. receive relayed trace messages and print them to the shell.</p>
    227. 

  227. <p>The trace information can be configured to either write trace
    228. 

  228. information to a plain trace information file or to relay it to
    229. 

  229. another inviso meta tracer on another node. The inviso meta tracer is
    230. 

  230. capable of matching function calls with their function returns (only
    231. 

  231. if return_trace is activated in the meta trace match specification for
    232. 

  232. the function in question). This is necessary since it may not be
    233. 

  233. possible to decide what to do, if anything shall be done at all, until
    234. 

  234. the return value of the function call is examined.</p>
    235. 

  235. <p>To be able to match calls with returns a state can be saved when
    236. 

  236. detecting a function call in a public loop data structure kept by the
    237. 

  237. inviso meta tracer. The public loop data structure is given as
    238. 

  238. argument to a handler-function called whenever a meta trace message
    239. 

  239. arrives to the inviso meta tracer (both function calls and function
    240. 

  240. returns). The public loop data structure is first initiated by the
    241. 

  241. Mi:Fi function which takes the items in Argsi as arguments. Fi shall
    242. 

  242. return the initial public loop data structure. When meta tracing is
    243. 

  243. stopped, either because tracing is stopped or because tracing is
    244. 

  244. suspended, the Mr:Fr(PublicLoopData) is called to offer a possibility
    245. 

  245. to clean-up. Note that for every function meta-tracing is activated, a
    246. 

  246. public loop data modification function can be speficied. That function
    247. 

  247. will prepare the current loop data structure for this particular
    248. 

  248. function.</p>
    249. 

  249. <p>Further there is a risk that function call states becomes abandoned
    250. 

  250. inside the public loop data structure. This will happen if a function
    251. 

  251. call is entered into the public loop data structure, but no function
    252. 

  252. return occurs. To prevent the public loop data structure from growing
    253. 

  253. infinitely the clean function Fc will periodically be called with the
    254. 

  254. public loop data structure as argument. Elements entered into the
    255. 

  255. public loop data structure as a result of a function call must contain
    256. 

  256. a timestamp for the Fc to be able to conclude if it is abandoned or
    257. 

  257. not. Fc shall return a new public loop data structure.</p>
    258. 

  258. <p>When initiating tracing involving trace information without a TiSpec,
    259. 

  259. a default public loop data structure will be initiated to handle
    260. 

  260. locally registered process aliases. The default public loop data
    261. 

  261. structure is a two-tuple where the first element is used by the meta
    262. 

  262. tracing on the BIF register/2. The second element is left for user
    263. 

  263. usage.</p>
    264. 

  264. <p>The default public loop data structure may be extended with more
    265. 

  265. element positions. The first position must be left to the
    266. 

  266. implementation of registered-name translations. If the public loop
    267. 

  267. data structure is changed no longer meeting this requirement, the
    268. 

  268. tpm_localnames/0,1 and tpm_globalnames/0,1 can no longer be used.</p>
    269. 

  269. <p>A wrap files specification is used to limit the disk space consumed by
    270. 

  270. the trace. The trace is written to a limited number of files each with
    271. 

  271. a limited size. The actual filenames are Filename ++ SeqCnt ++ Tail,
    272. 

  272. where SeqCnt counts as a decimal string from 0 to WrapCnt and then
    273. 

  273. around again from 0. When a trace message written to the current file
    274. 

  274. makes it longer than WrapSize, that file is closed, if the number of
    275. 

  275. files in this wrap trace is as many as WrapCnt the oldest file is
    276. 

  276. deleted then a new file is opened to become the current. Thus, when a
    277. 

  277. wrap trace has been stopped, there are at most WrapCnt trace files
    278. 

  278. saved with a size of at least WrapSize (but not much bigger), except
    279. 

  279. for the last file that might even be empty. The default values are
    280. 

  280. WrapSize == 128*1024 and WrapCnt == 8.</p>
    281. 

  281. <p>The SeqCnt values in the filenames are all in the range 0 through
    282. 

  282. WrapCnt with a gap in the circular sequence. The gap is needed to find
    283. 

  283. the end of the trace.</p>
    284. 

  284. <p>If the WrapSize is specified as {time,WrapTime}, the current file is
    285. 

  285. closed when it has been open more than WrapTime milliseconds,
    286. 

  286. regardless of it being empty or not.</p>
    287. 

  287. <p>The ip trace driver has a queue of QSize messages waiting to be
    288. 

  288. delivered. If the driver cannot deliver messages as fast as they are
    289. 

  289. produced by the runtime system, they are dropped. The number of
    290. 

  290. dropped messages are indicated in the trace log as separate trace
    291. 

  291. message.</p>
    292. 

  292. <p>stop_tracing(Nodes) -&gt; {ok,NodeResults} | {error,Reason}
    293. 

  293. stop_tracing() -&gt; {ok,NodeResults} | NodeResult</p>
    294. 

  294. <p>Types:</p>
    295. 

  295. <p>Nodes = [Node]
    296. 

  296. NodeResults = [{Node,NodeResult}]
    297. 

  297. NodeResult = {ok,State} | {error,Reason}
    298. 

  298. ?State = new | idle</p>
    299. 

  299. <p>Stops tracing on all or specified Nodes. Flushes the trace buffer if a
    300. 

  300. trace-port is used, closes the trace-port and removes all trace flags
    301. 

  301. and meta-patterns. The nodes are called in parallel.</p>
    302. 

  302. <p>Stopping tracing means going to state idle&lt;c&gt;. If the runtime
    303. 

  303. component was already in state &lt;c&gt;new, it will of course remain in
    304. 

  304. state new (then there was no tracing to stop).</p>
    305. 

  305. <p>clear() -&gt; {ok,NodeResults} | NodeResult
    306. 

  306. clear(Nodes,Options) -&gt; {ok,NodeResults} | {error,Reason}
    307. 

  307. clear(Options) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
    308. 

  308. <p>Types:</p>
    309. 

  309. <p>Nodes = [Node]
    310. 

  310. Options = [Option]
    311. 

  311. ?Option = keep_trace_patterns | keep_log_files
    312. 

  312. NodeResults = [{Node,NodeResult}]
    313. 

  313. ?NodeResult = {ok,{new,Status}} | {error,Reason}
    314. 

  314. ??Status = running | {suspended,SReason}</p>
    315. 

  315. <p>Stops all tracing including removing meta-trace patterns. Removes all
    316. 

  316. trace patterns. If the node is tracing or idle, trace-logs belonging
    317. 

  317. to the current tracerdata are removed. Hence the node is returned to
    318. 

  318. state new. Note that the node can still be suspended.</p>
    319. 

  319. <p>Various options can make the node keep set trace patterns and log-
    320. 

  320. files. The node still enters the new state.</p>
    321. 

  321. <p>tp(Nodes,Mod,Func,Arity,MatchSpec,Opts) -&gt;
    322. 

  322. tp(Nodes,Mod,Func,Arity,MatchSpec) -&gt; {ok,NodeResults} |
    323. 

  323. {error,Reason}
    324. 

  324. tp(Mod,Func,Arity,MatchSpec,Opts) -&gt;
    325. 

  325. tp(Mod,Func,Arity,MatchSpec) -&gt; {ok,NodeResults} | NodeResult |
    326. 

  326. {error,Reason}
    327. 

  327. tp(Nodes,PatternList) -&gt; {ok,NodeResults} | {error,Reason}
    328. 

  328. tp(PatternList) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
    329. 

  329. <p>Types:</p>
    330. 

  330. <p>Nodes = [Node]
    331. 

  331. Mod = Func = atom() | &#8216;_&#8217;
    332. 

  332. Arity = int() | &#8216;_&#8217;
    333. 

  333. MatchSpec = true | false | [] | matchspec()
    334. 

  334. PatternList = [Pattern],
    335. 

  335. ?Pattern = {Mod,Func,Arity,MatchSpec,Opts}
    336. 

  336. Opts = [Opt]
    337. 

  337. ?Opt = only_loaded
    338. 

  338. NodeResults = [NodeResult]
    339. 

  339. ?NodeResult = {ok,[Ans]} | {error,Reason}
    340. 

  340. ??Ans = int() | {error,Reason}</p>
    341. 

  341. <p>Set trace pattern (global) on specified or all nodes. The integer
    342. 

  342. replied if the call was successfully describes the number of matched
    343. 

  343. functions. The functions without a Nodes argument means all nodes, in
    344. 

  344. a non-distributed environment it means the local node. Using wildcards
    345. 

  345. follows the rules for wildcards of erlang:trace_pattern/3. It is for
    346. 

  346. instance illegal to specify M == &#8216;_&#8217; while F is not &#8216;_&#8217;.</p>
    347. 

  347. <p>When calling several nodes, the nodes are called in parallel.</p>
    348. 

  348. <p>The option only_loaded will prevent modules not loaded (yet) into the
    349. 

  349. runtime system to become loaded just as a result of that a trace
    350. 

  350. pattern is requested to be set on it. Otherwise modules are
    351. 

  351. automatically loaded if not already loaded (since the module must be
    352. 

  352. present for a trace pattern to be set on it). The latter does not
    353. 

  353. apply if the wildcard &#8216;_&#8217; is used as module specification.</p>
    354. 

  354. <p>tpl(Nodes,Mod,Func,Arity,MatchSpec) -&gt;
    355. 

  355. tpl(Nodes,Mod,Func,Arity,MatchSpec,Opts) -&gt; {ok,NodeResults} |
    356. 

  356. {error,Reason}
    357. 

  357. tpl(Mod,Func,Arity,MatchSpec) -&gt;
    358. 

  358. tpl(Mod,Func,Arity,MatchSpec,Opts) -&gt; {ok,NodeResults} | NodeResult|
    359. 

  359. {error,Reason}
    360. 

  360. tpl(Nodes,PatternList) -&gt; {ok,NodeResults} | {error,Reason}
    361. 

  361. tpl(PatternList) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
    362. 

  362. <p>See tp/N function above for details on arguments and return values.</p>
    363. 

  363. <p>Set local trace pattern on specified functions. When calling several
    364. 

  364. nodes, the nodes are called in parallel.</p>
    365. 

  365. <p>ctp(Nodes,Mod,Func,Arity) -&gt; {ok,NodeResults} | {error,Reason}
    366. 

  366. ctp(Mod,Func,Arity) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
    367. 

  367. <p>See tp/N for argument descriptions.</p>
    368. 

  368. <p>Clear global trace patterns. When calling several nodes, the nodes are
    369. 

  369. called in parallel.</p>
    370. 

  370. <p>ctpl(Nodes,Mod,Func,Arity) -&gt; {ok,NodeResults} | {error,Reason}
    371. 

  371. ctpl(Mod,Funct,Arity) -&gt; {ok,NodeResults} | NodeResult |
    372. 

  372. {error,Reason}</p>
    373. 

  373. <p>See tp/N for argument description.</p>
    374. 

  374. <p>Clear local trace patterns. When calling several nodes, the nodes are
    375. 

  375. called in parallel.</p>
    376. 

  376. <p>tf(Nodes,PidSpec,FlagList) -&gt; {ok,NodeResults} | {error,Reason}
    377. 

  377. tf(PidSpec,FlagList) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    378. 

  378. tf(Nodes,TraceConfList) -&gt; {ok,NodeResults} | {error,Reason}
    379. 

  379. tf(NodeTraceConfList) -&gt; {ok,NodeResults} | {error,Reason}
    380. 

  380. tf(TraceConfList) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
    381. 

  381. <p>Types:</p>
    382. 

  382. <p>Nodes = [Node]
    383. 

  383. NodeTraceConfList = [{Node,TraceConfList}]
    384. 

  384. TraceConfList = [{PidSpec,FlagList}]
    385. 

  385. FlagList = [Flag]
    386. 

  386. PidSpec = all | new| existing | pid() | locally_registered_name()
    387. 

  387. Flag &#8211; see erlang:trace/3
    388. 

  388. NodeResult = {ok,[Ans]} | {error,Reason}
    389. 

  389. Ans = int() | {error,Reason}</p>
    390. 

  390. <p>Set process trace flags on processes on all or specified nodes. The
    391. 

  391. integer returned if the call was successful describes the matched
    392. 

  392. number of processes. The functions without a Nodes argument means all
    393. 

  393. nodes, in a non-distributed environment it means the local node.</p>
    394. 

  394. <p>There are many combinations which does not make much sense. For
    395. 

  395. instance specifying a certain process identifier at all nodes. Or an
    396. 

  396. empty TraceConfList for all nodes.</p>
    397. 

  397. <p>When calling several nodes, the nodes are called in parallel.</p>
    398. 

  398. <p>ctf(Nodes,PidSpec,FlagList) -&gt; {ok,NodeResults} | {error,Reason}
    399. 

  399. ctf(PidSpec,FlagList) -&gt; {ok,NodeResults} | NodeResult |
    400. 

  400. {error,Reason}
    401. 

  401. ctf(Nodes,TraceConfList) -&gt; {ok,NodeResults} | {error,Reason}
    402. 

  402. ctf(TraceConfList) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
    403. 

  403. <p>See tf/N for arguments and return value description.</p>
    404. 

  404. <p>Clear process trace flags on all or specified nodes. When calling
    405. 

  405. several nodes, the nodes are called in parallel.</p>
    406. 

  406. <p>ctf_all(Nodes) -&gt; {ok,NodeResults} | {error,Reason}
    407. 

  407. ctf_all() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
    408. 

  408. <p>Types:</p>
    409. 

  409. <p>Nodes = [Node]
    410. 

  410. NodeResults = [{Node,NodeResult}]
    411. 

  411. NodeResult = ok | {error,Reason}</p>
    412. 

  412. <p>Clears all trace flags on all or specified nodes. Just for
    413. 

  413. convenience.</p>
    414. 

  414. <p>init_tpm(Mod,Func,Arity,CallFunc) -&gt; {ok,NodeResults} | NodeResult |
    415. 

  415. {error,Reason}
    416. 

  416. init_tpm(Nodes,Mod,Func,Arity,CallFunc) -&gt; {ok,NodeResults} |
    417. 

  417. {error,Reason}
    418. 

  418. init_tpm(Mod,Func,Arity,InitFunc,CallFunc,ReturnFunc,RemoveFunc) -&gt;
    419. 

  419. {ok,NodeResults} | NodeResult | {error,Reason}
    420. 

  420. init_tpm(Nodes,Mod,Func,Arity,
    421. 

  421. InitFunc,CallFunc,ReturnFunc,RemoveFunc) -&gt; {ok,NodeResults} |
    422. 

  422. {error,Reason}</p>
    423. 

  423. <p>Types:</p>
    424. 

  424. <p>Mod = Func = atom()
    425. 

  425. Arity = int()
    426. 

  426. NodeResults = [{Node,NodeResult}]
    427. 

  427. NodeResult = ok | {error,Reason}
    428. 

  428. InitFunc,RemoveFunc = {Module,Function} | function()/4 | void
    429. 

  429. CallFunc = ReturnFunc = {Module,Function} | function()/3 | void</p>
    430. 

  430. <p>Initializes Mod:Func/Arity for meta tracing without setting any meta
    431. 

  431. trace patterns. This is necessary if the named match specs will be
    432. 

  432. used (see tpm_ms/5,6). Otherwise initialization of public loop data
    433. 

  433. can be done at the same time as setting meta trace patterns using
    434. 

  434. tpm/8,9.</p>
    435. 

  435. <p>Note that we can not use wildcards here (even if it is perfectly legal
    436. 

  436. in Erlang). It also sets the CallFunc and ReturnFunc for the meta
    437. 

  437. traced function. That is the functions which will be called when a
    438. 

  438. function call and a return_trace meta trace message respectively
    439. 

  439. arrives to the inviso meta tracer for Mod:Func/Arity.</p>
    440. 

  440. <p>This function is also available without InitFunc and RemoveFunc. That
    441. 

  441. means that no initialization of the public loop data structure will be
    442. 

  442. done and that CallFunc and ReturnFunc must either use already existing
    443. 

  443. parts of public loop data structure or not use it at all.</p>
    444. 

  444. <p>The InitFunc initializes the already existing public loop data
    445. 

  445. structure for use with Mod:Func/Arity. InitFunc(Mod,Func,Arity,PublLD)
    446. 

  446. -&gt; {ok,NewPublLD,Output} where OutPut can be a binary which will then
    447. 

  447. be written to the trace information file. If it is not a binary, no
    448. 

  448. output will be done. RemoveFunc will be called when the meta tracing
    449. 

  449. is cleared with ctpm/3,4. RemoveFunc(Mod,Func,Arity,PublLD) -&gt;
    450. 

  450. {ok,NewPublLD}.</p>
    451. 

  451. <p>See tpm/N for details on CallFunc and ReturnFunc.</p>
    452. 

  452. <p>tpm(Mod,Func,Arity,MS) -&gt; {ok,NodeResults} | NodeResult |
    453. 

  453. {error,Reason}
    454. 

  454. tpm(Nodes,Mod,Func,Arity,MS) -&gt; {ok,NodeResults} | {error,Reason}
    455. 

  455. tpm(Mod,Func,Arity,MS,CallFunc) -&gt; {ok,NodeResults} | NodeResults |
    456. 

  456. {error,Reason}
    457. 

  457. tpm(Nodes,Mod,Func,Arity,MS,CallFunc) -&gt; {ok,NodeResults} |
    458. 

  458. {error,Reason}
    459. 

  459. tpm(Mod,Func,Arity,MS,InitFunc,CallFunc,ReturnFunc,RemoveFunc) -&gt;
    460. 

  460. {ok,NodeResults} | NodeResults | {error,Reason}
    461. 

  461. tpm(Nodes,Mod,Func,Arity,MS, InitFunc,CallFunc,ReturnFunc,RemoveFunc)
    462. 

  462. -&gt; {ok,NodeResults} | {error,Reason}</p>
    463. 

  463. <p>Types:</p>
    464. 

  464. <p>Mod = Func = atom()
    465. 

  465. Arity = int()
    466. 

  466. MS = [match_spec()]
    467. 

  467. Nodes = [Node]
    468. 

  468. InitFunc = RemoveFunc = {Module,Function} | function()/4 | void
    469. 

  469. CallFunc = ReturnFunc = {Module,Function} | function()/3 | void
    470. 

  470. NodeResults = [{Node,NodeResult}]
    471. 

  471. NodeResult = {ok,1} | {ok,0} | {error,Reason}1</p>
    472. 

  472. <p>Activates meta-tracing in the inviso_rt_meta tracer. Except when using
    473. 

  473. tpm/6, tpm/8 and tpm/9 the Mod:Func/Arity must first have been
    474. 

  474. initiated using init_tpm/N. When calling several nodes, the nodes are
    475. 

  475. called in parallel.</p>
    476. 

  476. <p>CallFunc will be called every time a meta trace message arrives to the
    477. 

  477. inviso meta tracer because of a call to Func.
    478. 

  478. CallFunc(CallingPid,ActualArgList,PublLD) -&gt; {ok,NewPrivLD,Output}
    479. 

  479. where Output can be a binary or void. If it is a binary it will be
    480. 

  480. written to the trace information file.</p>
    481. 

  481. <p>ReturnFunc will be called every time a meta return_trace message
    482. 

  482. arrives to the inviso meta tracer because of a return_trace of a call
    483. 

  483. to Func. ReturnFunc(CallingPid,ReturnValue,PublLD) -&gt;
    484. 

  484. {ok,NewPrivLD,Output}. Further the ReturnFunc must handle the fact
    485. 

  485. that a return_trace message arrives for a call which was never
    486. 

  486. noticed. This because the message queue of the meta tracer may have
    487. 

  487. been emptied.</p>
    488. 

  488. <p>tpm_tracer(Mod,Func,Arity,MS) -&gt; {ok,NodeResults} | NodeResult |
    489. 

  489. {error,Reason}
    490. 

  490. tpm_tracer(Nodes,Mod,Func,Arity,MS) -&gt; {ok,NodeResults} |
    491. 

  491. {error,Reason}
    492. 

  492. tpm_tracer(Mod,Func,Arity,MS,CallFunc) -&gt; {ok,NodeResults} |
    493. 

  493. NodeResults | {error,Reason}
    494. 

  494. tpm_tracer(Nodes,Mod,Func,Arity,MS,CallFunc) -&gt; {ok,NodeResults} |
    495. 

  495. {error,Reason}
    496. 

  496. tpm_tracer(Mod,Func,Arity,MS,InitFunc,CallFunc,ReturnFunc,RemoveFunc)
    497. 

  497. -&gt; {ok,NodeResults} | NodeResults | {error,Reason}
    498. 

  498. tpm_tracer(Nodes,Mod,Func,Arity,MS,
    499. 

  499. InitFunc,CallFunc,ReturnFunc,RemoveFunc) -&gt; {ok,NodeResults} |
    500. 

  500. {error,Reason}</p>
    501. 

  501. <p>See tpm/X for details on arguments and return values.</p>
    502. 

  502. <p>Same as tpm/X but all match specs in MS containing a trace action term
    503. 

  503. will have a {tracer,Tracer} appended to its enable-list. Tracer will
    504. 

  504. be the current output for regular trace messages as specified when
    505. 

  505. tracing was initiated. This function is useful when setting a meta
    506. 

  506. trace pattern on a function with the intent that its execution shall
    507. 

  507. turn tracing on for the process executing the match-spec in the meta
    508. 

  508. trace pattern. The reason the tracer process trace flag can not be
    509. 

  509. explicitly written in the action term by the user is that it may be
    510. 

  510. difficult to learn its exact value for a remote node. Further more
    511. 

  511. inviso functions are made to work on several nodes at the same time,
    512. 

  512. requiering different match specs to be set for different nodes.</p>
    513. 

  513. <p>Simple example: We want any process executing the function
    514. 

  514. mymod:init(1234) (with the argument, exactly the integer 1234) to
    515. 

  515. begin function-call tracing. In the example, if the process is found
    516. 

  516. to be one that shall start call tracing, we also first disable all
    517. 

  517. process trace flags to ensure that we have full control over what the
    518. 

  518. process traces. void in the example specifies that the meta-tracer
    519. 

  519. (inviso_rt_meta) will not call any function when meta trace messages
    520. 

  520. for mymod:init/1 arrives. There is no need for a CallFunc since the
    521. 

  521. side-effect (start call-tracing) is achieved immediately with the
    522. 

  522. match-spec.</p>
    523. 

  523. <div class="highlight-erlang"><div class="highlight"><pre><span class="nn">inviso</span><span class="p">:</span><span class="n">tpm_tracer</span><span class="p">(</span><span class="n">mymod</span><span class="p">,</span><span class="n">init</span><span class="p">,</span><span class="mi">1</span><span class="p">,[{[</span><span class="mi">1234</span><span class="p">],[],[{</span><span class="nb">trace</span><span class="p">,[</span><span class="n">all</span><span class="p">],[</span><span class="n">call</span><span class="p">]}]}],</span><span class="n">void</span><span class="p">).</span>
    524. 

  524. </pre></div>
    525. 

  525. </div>
    526. 

  526. <p>This will internally, by the meta tracer on each Erlang node, be
    527. 

  527. translated to:</p>
    528. 

  528. <div class="highlight-erlang"><div class="highlight"><pre><span class="nn">erlang</span><span class="p">:</span><span class="nb">trace_pattern</span><span class="p">({</span><span class="n">mymod</span><span class="p">,</span><span class="n">init</span><span class="p">,</span><span class="mi">1</span><span class="p">},[{[</span><span class="mi">1234</span><span class="p">],[],[{</span><span class="nb">trace</span><span class="p">,[</span><span class="n">all</span><span class="p">],[</span><span class="n">call</span><span class="p">,{{</span><span class="n">tracer</span><span class="p">,</span><span class="nv">T</span><span class="p">}}]}]}],[{</span><span class="n">meta</span><span class="p">,</span><span class="nv">P</span><span class="p">}]).</span>
    529. 

  529. </pre></div>
    530. 

  530. </div>
    531. 

  531. <p>Where T is the tracer for regular trace messages (most often a trace-
    532. 

  532. port, but can be the runtime component inviso_rt process), and P is
    533. 

  533. the meta tracer (the inviso_rt_meta process).</p>
    534. 

  534. <p>tpm_ms(Mod,Func,Arity,MSname,MS) -&gt; {ok,NodeResults} | NodeResult |
    535. 

  535. {error,Reason}
    536. 

  536. tpm_ms(Nodes,Mod,Func,Arity,MSname,MS) -&gt; {ok,NodeResults} |
    537. 

  537. {error,Reason}</p>
    538. 

  538. <p>Types:</p>
    539. 

  539. <p>Nodes = [Node]&lt;v&gt; &lt;v&gt;Mod = Func = atom()&lt;v&gt; &lt;v&gt;Arity = int()&lt;v&gt;
    540. 

  540. &lt;v&gt;MSname = term()&lt;v&gt; &lt;v&gt;MS = [match_spec()]&lt;v&gt; &lt;v&gt;NodeResults =
    541. 

  541. [{Node,NodeResult}]&lt;v&gt; &lt;v&gt;NodeResult = {ok,1} | {ok,0} |
    542. 

  542. {error,Reason}&lt;v&gt;</p>
    543. 

  543. <p>This function adds a list of match-specs to the already existing ones.
    544. 

  544. It uses an internal database to keep track of existing match-specs.
    545. 

  545. This set of match specs can hereafter be referred to with the name
    546. 

  546. MSname. If the match-spec does not result in any meta traced functions
    547. 

  547. (for whatever reason), the MS is not saved in the database. The
    548. 

  548. previously known match-specs are not removed. If MSname is already in
    549. 

  549. use as a name refering to a set of match-specs for this particular
    550. 

  550. meta-traced function, the previous set of match-specs are replaced
    551. 

  551. with MS.</p>
    552. 

  552. <p>Mod:Func/Arity must previously have been initiated in order for this
    553. 

  553. function to add a match-spec.</p>
    554. 

  554. <p>When calling several nodes, the nodes are called in parallel. {ok,1}
    555. 

  555. indicates success.</p>
    556. 

  556. <p>tpm_ms_tracer(Mod,Func,Arity,MSname,MS) -&gt; {ok,NodeResults} |
    557. 

  557. NodeResult | {error,Reason}
    558. 

  558. tpm_ms_tracer(Nodes,Mod,Func,Arity,MSname,MS) -&gt; {ok,NodeResults} |
    559. 

  559. {error,Reason}</p>
    560. 

  560. <p>See tpm_ms/X for details on arguments and return values, and
    561. 

  561. tpm_tracer/X for explanations about the appending of {tracer,Tracer}
    562. 

  562. process trace flag.</p>
    563. 

  563. <p>ctpm_ms(Mod,Func,Arity,MSname) -&gt; {ok,NodeResults} | NodeResult |
    564. 

  564. {error,Reason}
    565. 

  565. ctpm_ms(Nodes,Mod,Func,Arity,MSname) -&gt; {ok,NodeResults} |
    566. 

  566. {error,Reason}</p>
    567. 

  567. <p>Types:</p>
    568. 

  568. <p>NodeResults = [{Node,NodeResult}]
    569. 

  569. NodeResult = ok | {error,Reason}</p>
    570. 

  570. <p>Removes a named match-spec from the meta traced function. Note that it
    571. 

  571. never is a fault to remove a match spec. Not even from a function
    572. 

  572. which is non existent.</p>
    573. 

  573. <p>When calling several nodes, the nodes are called in parallel.</p>
    574. 

  574. <p>ctpm(Mod,Func,Arity) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    575. 

  575. ctpm(Nodes,Mod,Func,Arity) -&gt; {ok,NodeResults} | {error,Reason}</p>
    576. 

  576. <p>Types:</p>
    577. 

  577. <p>NodeResults = [{Node,NodeResult}]
    578. 

  578. NodeResult = ok | {error,Reason}</p>
    579. 

  579. <p>Removes the meta trace pattern for the function, means stops
    580. 

  580. generating output for this function. The public loop data structure
    581. 

  581. may be cleared by the previously entered RemoveFunc.</p>
    582. 

  582. <p>When calling several nodes, the nodes are called in parallel.</p>
    583. 

  583. <p>tpm_localnames() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    584. 

  584. tpm_localnames(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
    585. 

  585. <p>Types:</p>
    586. 

  586. <p>NodeResults = [{Node,NodeResult}]
    587. 

  587. NodeResult = {R1,R2}
    588. 

  588. R1 = R2 = {ok,0} | {ok,1} | {error,Reason}</p>
    589. 

  589. <p>Quick version for setting meta-trace patterns on erlang:register/2. It
    590. 

  590. uses a default CallFunc and ReturnFunc in the meta-tracer server. The
    591. 

  591. main purpose of this function is to create ti-log entries for
    592. 

  592. associations between pids and registered name aliases. The
    593. 

  593. implementation uses return_trace to see if the registration was
    594. 

  594. successful or not, before actually making the ti-log alias entry.
    595. 

  595. Further the implementation also meta traces the BIF unregister/1.</p>
    596. 

  596. <p>If both N1 and N2 is 1, function call was successful. N1 and N2
    597. 

  597. represent setting meta trace pattern on register/2 and unregister/1.</p>
    598. 

  598. <p>ctpm_localnames() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    599. 

  599. ctpm_localnames(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
    600. 

  600. <p>Types:</p>
    601. 

  601. <p>NodeResults = [{Node,NodeResult}]
    602. 

  602. NodeResult = {R1,R2}
    603. 

  603. R1 = R2 = ok | {error,Reason}</p>
    604. 

  604. <p>Function for removing previously set patters by tpm_localnames/0. The
    605. 

  605. two results R1 and R2 represents that meta pattern is removed from
    606. 

  606. both register/2 and unregister/1.</p>
    607. 

  607. <p>tpm_globalnames() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    608. 

  608. tpm_globalnames(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
    609. 

  609. <p>Types:</p>
    610. 

  610. <p>NodeResults = [{Node,NodeResult}]
    611. 

  611. NodeResult = {R1,R2}
    612. 

  612. R1 = R2 = {ok,0} | {ok,1} | {error,Reason}</p>
    613. 

  613. <p>Quick version for setting meta-trace patterns capable of learning the
    614. 

  614. association of a pid with a globally registered name (registered using
    615. 

  615. global:register_name). The implementation meta-traces on
    616. 

  616. global:handle_call({register,&#8217;_&#8217;,&#8217;_&#8217;,&#8217;_&#8217;},&#8217;_&#8217;,&#8217;_&#8217;) and
    617. 

  617. global:delete_global_name/2. The N1 and N2 represents the success of
    618. 

  618. the two sub-tmp calls.</p>
    619. 

  619. <p>ctpm_globalnames() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    620. 

  620. ctpm_globalnames(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
    621. 

  621. <p>Types:</p>
    622. 

  622. <p>NodeResults = [{Node,NodeResult}]
    623. 

  623. NodeResult = {R1,R2} | {error,Reason}
    624. 

  624. R1 = R2 = ok | {error,Reason}</p>
    625. 

  625. <p>Function for removing previously set meta patters by
    626. 

  626. tpm_globalnames/0,1. The two results R1 and R2 represents that meta
    627. 

  627. pattern are removed from both global:handle_call/3 and
    628. 

  628. global:delete_global_name/1.</p>
    629. 

  629. <p>ctp_all() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    630. 

  630. ctp_all(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
    631. 

  631. <p>Types:</p>
    632. 

  632. <p>NodeResults = [{Node,NodeResult}]
    633. 

  633. NodeResult = ok | {error,Reason}</p>
    634. 

  634. <p>Clears all, both global and local trace patterns. Does not clear meta
    635. 

  635. trace patterns. Equivalent to a call to ctp/3,4 and to ctpl/3,4 with
    636. 

  636. wildcards &#8216;_&#8217; for all modules, functions and arities.</p>
    637. 

  637. <p>suspend(SReason) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    638. 

  638. suspend(Nodes,SReason) -&gt; {ok,NodeResults} | {error,Reason}</p>
    639. 

  639. <p>Types:</p>
    640. 

  640. <p>SReason = term()
    641. 

  641. NodeResults = [{Node,NodeResult}]
    642. 

  642. NodeResult = ok | {error,Reason}</p>
    643. 

  643. <p>Suspends the runtime components. SReason will become the suspend-
    644. 

  644. reason replied in for instance a get_status/0,1 call. A runtime
    645. 

  645. component that becomes suspended removes all trace flags and all meta
    646. 

  646. trace patterns. In that way trace output is no longer generated. The
    647. 

  647. task of reactivating a suspended runtime component is outside the
    648. 

  648. scoop of inviso. It can for instance be implemented by a higher layer
    649. 

  649. trace-tool &#8220;remembering&#8221; all trace flags and meta patterns set.</p>
    650. 

  650. <p>cancel_suspension() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    651. 

  651. cancel_suspend(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
    652. 

  652. <p>Types:</p>
    653. 

  653. <p>NodeResults = [{Node,NodeResult}]
    654. 

  654. NodeResult = ok | {error,Reason}</p>
    655. 

  655. <p>Makes the runtime components running again (as opposite to suspended).
    656. 

  656. Since reactivating previous trace flags and meta trace patterns is
    657. 

  657. outside the scoop of inviso, cancelling suspension is simply making it
    658. 

  658. possible to set trace flags and meta trace patterns again.</p>
    659. 

  659. <p>get_status() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    660. 

  660. get_status(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
    661. 

  661. <p>Types:</p>
    662. 

  662. <p>NodeResults = [{Node,NodeResult}]
    663. 

  663. NodeResult = {ok,{State,Status}} | {error,Reason}
    664. 

  664. State = new | idle | tracing
    665. 

  665. Status = running | {suspended,SReason}
    666. 

  666. SReason = term()</p>
    667. 

  667. <p>Finds out the state and status of a runtime component. A runtime
    668. 

  668. component is in state new before it has been initiated to do any
    669. 

  669. tracing the first time. There are clear-functions which can make a
    670. 

  670. runtime component become new again without having to restart. A
    671. 

  671. runtime component becomes idle after tracing is stopped.</p>
    672. 

  672. <p>get_tracerdata() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    673. 

  673. get_tracerdata(Nodes) -&gt; {ok,NodeResults} | {error,Reason}</p>
    674. 

  674. <p>Types:</p>
    675. 

  675. <p>NodeResults = [{Node,NodeResult}]
    676. 

  676. NodeResult = {ok,NResult} | {error,Reason}
    677. 

  677. NResult = TracerData | no_tracerdata</p>
    678. 

  678. <p>Returns the current tracerdata of a runtime component. A runtime
    679. 

  679. component in state new can not have tracerdata. An idle runtime
    680. 

  680. component does have tracerdata, the last active tracerdata. TracerData
    681. 

  681. will be a term as specified to init_tracing when tracing was initiated
    682. 

  682. for the runtime component.</p>
    683. 

  683. <p>list_logs() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    684. 

  684. list_logs(Nodes) -&gt; {ok,NodeResults} | {error,Reason}
    685. 

  685. list_logs(NodeTracerData) -&gt; {ok,NodeResults} | {error,Reason}
    686. 

  686. list_logs(TracerData) -&gt; {ok,NodeResults} | NodeResult |
    687. 

  687. {error,Reason}</p>
    688. 

  688. <p>Types:</p>
    689. 

  689. <p>TracerData &#8211; see init_tracing/1,2
    690. 

  690. NodeResults = [{Node,NodeResult}]
    691. 

  691. NodeResult = {ok,FileList} | {ok,no_log} | {error,Reason}
    692. 

  692. ?FileList = [FileType]
    693. 

  693. ??FileType = {trace_log,Dir,Files} | {ti_log,Dir,Files}
    694. 

  694. ??Files = [FileNameWithOutPath]</p>
    695. 

  695. <p>Returns the actually existing log files associated with TracerData. If
    696. 

  696. a tracerdata is not specified, current tracerdata is used for that
    697. 

  697. particular runtime component. Files will be a list of one or more
    698. 

  698. files should it be a wrap-set. Otherwise the it is a list of only one
    699. 

  699. filename.</p>
    700. 

  700. <p>This function is useful to learn the name and path of all files
    701. 

  701. belonging to a trace. This information can later be used to move those
    702. 

  702. files for merging. Note that since it is possible to ask on other
    703. 

  703. tracerdata than the current, it is possible to learn filenames of
    704. 

  704. previously done traces, under the circumstances that they have not
    705. 

  705. been removed.</p>
    706. 

  706. <p>fetch_log(LogSpecList,DestDir,Prefix) -&gt; {ok,NodeResults} |
    707. 

  707. {error,not_distributed} | {error,Reason}
    708. 

  708. fetch_log(DestDir,Prefix) -&gt; {ok,NodeResults} |
    709. 

  709. {error,not_distributed} | {error,Reason}</p>
    710. 

  710. <p>Types:</p>
    711. 

  711. <p>DestDir = string()
    712. 

  712. Prefix = string()
    713. 

  713. LogSpecList = [LogSpec]
    714. 

  714. ?LogSpec = {Node,FileSpecList} | Node | {Node,TracerData}
    715. 

  715. TracerData = see init_tracing/1,/2
    716. 

  716. FileSpecList = [{trace_log,Dir,FileList},{ti_log,Dir,FileList}] |
    717. 

  717. [{trace_log,Dir,FileList}]
    718. 

  718. ?FileList = [RemoteFileName]
    719. 

  719. NodeResult = {Conclusion,ResultFileSpec} | no_log | {error,NReason}
    720. 

  720. ?NReason = own_node | Reason
    721. 

  721. ?Conclusion = complete | incomplete
    722. 

  722. ?ResultFileSpec = [{trace_log,FileResults},{ti_log,FileResults}]
    723. 

  723. ??FileResults = [FileResult]
    724. 

  724. ??? FileResult = {ok,FileName} | {error,FReason}
    725. 

  725. ????FReason = {file_open,{posix(),FileName}} |
    726. 

  726. {file_open,{posix(),RemoteFileName}} |
    727. 

  727. {file_open,{posix(),[DestDir,Prefix,RemoteFileName]}} |
    728. 

  728. {file_write,{posix(),FileName}} | {truncated,FileName} |
    729. 

  729. {truncated,{Reason,FileName}}
    730. 

  730. ?????posix() = atom()</p>
    731. 

  731. <p>Copies log files over distributed erlang to the control component
    732. 

  732. node. This function can only be used in a distributed system.</p>
    733. 

  733. <p>The resulting transferred files will have the prefix Prefix and will
    734. 

  734. be located in DestDir. The source files can either be pointed out
    735. 

  735. using a FileListSpec or tracerdata. If no files are explicitly
    736. 

  736. specified, current tracerdata for that node will be used. Note that if
    737. 

  737. source files have the same name (on several nodes) they will overwrite
    738. 

  738. each other at DestDir.</p>
    739. 

  739. <p>delete_log(Nodes,TracerData) -&gt; {ok,NodeResults} | {error,Reason}
    740. 

  740. delete_log(NodeSpecList) -&gt; {ok,NodeResults} | {error,Reason}
    741. 

  741. delete_log(Spec) -&gt; {ok,NodeResults} | NodeResult | {error,Reason}
    742. 

  742. delete_log(TracerData) -&gt; {ok,NodeResults} | NodeResult |
    743. 

  743. {error,Reason}
    744. 

  744. delete_log() -&gt; {ok,NodeResults} | NodeResult | {error,Reason}</p>
    745. 

  745. <p>Types:</p>
    746. 

  746. <p>Nodes = [Node]
    747. 

  747. NodeSpecList = [{Node,Spec}]
    748. 

  748. ?Spec = [AbsPathFileName] | LogSpecs
    749. 

  749. ??LogSpecs = [LogSpec]
    750. 

  750. ???LogSpec = {trace_log,Dir,[FileNameWithoutPath]} |
    751. 

  751. {ti_log,Dir,[FileNameWithoutPath]}
    752. 

  752. TracerData &#8211; see init_tracing/1,/2
    753. 

  753. NodeResults = [{Node,NodeResult}]
    754. 

  754. NodeResult = {ok,no_log} | {ok,LogInfos} | {ok,FileInfos}
    755. 

  755. ?LogInfos = [LogInfo]
    756. 

  756. ??LogInfo = {trace_log,FileInfos} | {ti_log,FileInfos}
    757. 

  757. ?FileInfos = [FileInfo]
    758. 

  758. ??FileInfo = {ok,FileName} | {error,Reason}</p>
    759. 

  759. <p>Deletes listed files or files corresponding to tracerdata. If no
    760. 

  760. tracerdata or list of files are specified in the call, current
    761. 

  761. tracerdata at the runtime components will be used to identify files to
    762. 

  762. delete. All filenames shall be strings.</p>
    763. 

  763. <p>FileName can either be an absolute path or just a filename depending
    764. 

  764. on if AbsPathFileName or a LogSpec was used to identify the file.</p>
    765. 

  765. <p>subscribe() -&gt; ok | {error,Reason}
    766. 

  766. subscribe(Pid) -&gt; ok | {error,Reason}</p>
    767. 

  767. <p>Types:</p>
    768. 

  768. <p>Pid = pid()</p>
    769. 

  769. <p>Adds Pid or self() if using subscribe/0 to the inviso-event sending
    770. 

  770. list. Note that it is possible to add a pid several times and that the
    771. 

  771. Pid then will receive multiple copies of inviso-event messages.</p>
    772. 

  772. <p>All events will be sent to all subscribers in the event sending list.</p>
    773. 

  773. <div class="highlight-erlang"><div class="highlight"><pre><span class="nv">Event</span> <span class="o">=</span> <span class="p">{</span><span class="n">inviso_event</span><span class="p">,</span><span class="nv">ControllerPid</span><span class="p">,</span><span class="nn">erlang</span><span class="p">:</span><span class="n">localtime</span><span class="p">(),</span><span class="nv">Msg</span><span class="p">}</span>
    774. 

  774.   <span class="nv">Msg</span> <span class="o">=</span> <span class="p">{</span><span class="n">connected</span><span class="p">,</span> <span class="nv">Node</span><span class="p">,</span> <span class="p">{</span><span class="nv">RTtag</span><span class="p">,</span> <span class="p">{</span><span class="nv">State</span><span class="p">,</span><span class="nv">Status</span><span class="p">}}}</span>
    775. 

  775.       <span class="p">|</span> <span class="p">{</span><span class="n">disconnected</span><span class="p">,</span> <span class="nv">Node</span><span class="p">,</span> <span class="nv">NA</span><span class="p">}</span>
    776. 

  776.       <span class="p">|</span> <span class="p">{</span><span class="n">state_change</span><span class="p">,</span><span class="nv">Node</span><span class="p">,{</span><span class="nv">State</span><span class="p">,</span><span class="nv">Status</span><span class="p">}}</span>
    777. 

  777.       <span class="p">|</span> <span class="p">{</span><span class="n">port_down</span><span class="p">,</span><span class="nv">Node</span><span class="p">,</span><span class="nv">Reason</span><span class="p">}</span>
    778. 

  778.     <span class="nv">Node</span> <span class="o">=</span> <span class="nb">node</span><span class="p">()</span> <span class="p">|</span> <span class="n">local_runtime</span>
    779. 

  779. </pre></div>
    780. 

  780. </div>
    781. 

  781. <p>Subscribing to inviso-event may be necessary for a higher layer trace-
    782. 

  782. tool using inviso to follow the runtime components. local_runtime will
    783. 

  783. be used for a runtime component running in a non-distributed
    784. 

  784. environment.</p>
    785. 

  785. <p>unsubscribe() -&gt; ok
    786. 

  786. unsubscribe(Pid) -&gt; ok</p>
    787. 

  787. <p>Removes Pid (once) from the subscription list.</p>
    788. 

  788. <p>inviso 0.6
    789. 

  789. Copyright ? 1991-2009 <a class="reference external" href="http://www.ericsson.com/technology/opensource/erlang">Ericsson AB</a></p>
    790. 

  790. </div>
    791. 

  791. </div>
    792. 

  792. </div>
    793. 

  793. 

  794. 

  795.           </div>
    796. 

  796.         </div>
    797. 

  797.       </div>
    798. 

  798.       <div class="sphinxsidebar">
    799. 

  799.         <div class="sphinxsidebarwrapper">
    800. 

  800.             <h3><a href="../../../../index.html">Table Of Contents</a></h3>
    801. 

  801.             <ul>
    802. 

  802. <li><a class="reference external" href="">Lib - Inviso-0.6 - Doc - Html - Inviso</a><ul>
    803. 

  803. <li><a class="reference external" href="#inviso">inviso</a><ul>
    804. 

  804. <li><a class="reference external" href="#module">MODULE</a></li>
    805. 

  805. <li><a class="reference external" href="#module-summary">MODULE SUMMARY</a></li>
    806. 

  806. <li><a class="reference external" href="#description">DESCRIPTION</a></li>
    807. 

  807. <li><a class="reference external" href="#exports">EXPORTS</a></li>
    808. 

  808. </ul>
    809. 

  809. </li>
    810. 

  810. </ul>
    811. 

  811. </li>
    812. 

  812. </ul>
    813. 

  813. 

  814.             <h3>This Page</h3>
    815. 

  815.             <ul class="this-page-menu">
    816. 

  816.               <li><a href="../../../../_sources/lib/inviso-0.6/doc/html/inviso.txt"
    817. 

  817.                      rel="nofollow">Show Source</a></li>
    818. 

  818.             </ul>
    819. 

  819.           <div id="searchbox" style="display: none">
    820. 

  820.             <h3>Quick search</h3>
    821. 

  821.               <form class="search" action="../../../../search.html" method="get">
    822. 

  822.                 <input type="text" name="q" size="18" />
    823. 

  823.                 <input type="submit" value="Go" />
    824. 

  824.                 <input type="hidden" name="check_keywords" value="yes" />
    825. 

  825.                 <input type="hidden" name="area" value="default" />
    826. 

  826.               </form>
    827. 

  827.               <p class="searchtip" style="font-size: 90%">
    828. 

  828.               Enter search terms or a module, class or function name.
    829. 

  829.               </p>
    830. 

  830.           </div>
    831. 

  831.           <script type="text/javascript">$('#searchbox').show(0);</script>
    832. 

  832.         </div>
    833. 

  833.       </div>
    834. 

  834.       <div class="clearer"></div>
    835. 

  835.     </div>
    836. 

  836.     <div class="related">
    837. 

  837.       <h3>Navigation</h3>
    838. 

  838.       <ul>
    839. 

  839.         <li class="right" style="margin-right: 10px">
    840. 

  840.           <a href="../../../../genindex.html" title="General Index"
    841. 

  841.              >index</a></li>
    842. 

  842.         <li><a href="../../../../index.html">Erlang/OTP vR13B02 documentation</a> &raquo;</li> 
    843. 

  843.       </ul>
    844. 

  844.     </div>
    845. 

  845.     <div class="footer">
    846. 

  846.         &copy; Copyright 1999-2009 Ericsson AB.
    847. 

  847.       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.
    848. 

  848.     </div>
    849. 

  849.   </body>
    850. 

  850. </html>
    851.