PageRenderTime 4ms CodeModel.GetById 3ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 0ms

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

https://bitbucket.org/docs/docs.bitbucket.org
Plain Text | 1034 lines | 738 code | 296 blank | 0 comment | 0 complexity | 6a8993d9db1e01c73bc919fa7d1b223d MD5 | raw file
   1======================================
   2Lib - Inviso-0.6 - Doc - Html - Inviso
   3======================================
   4
   5` <http://www.ericsson.com/technology/opensource/erlang>`__
   6
   7
   8inviso
   9======
  10
  11
  12
  13MODULE
  14~~~~~~
  15inviso
  16
  17
  18MODULE SUMMARY
  19~~~~~~~~~~~~~~
  20Main API Module to the Inviso Tracer
  21
  22
  23DESCRIPTION
  24~~~~~~~~~~~
  25
  26With the inviso API runtime components can be started and tracing
  27managed across a network of distributed Erlang nodes, using a control
  28component also started with inviso API functions.
  29
  30Inviso can be used both in a distributed environment and in a non-
  31distributed. API functions not taking a list of nodes as argument
  32works on all started runtime components. If it is the non-distributed
  33case, that is the local runtime component. The API functions taking a
  34list of nodes as argument, or as part of one of the arguments, can not
  35be used in a non-distributed environment. Return values named
  36NodeResult refers to return values from a single Erlang node, and will
  37therefore be the return in the non-distributed environment.
  38
  39
  40
  41EXPORTS
  42~~~~~~~
  43
  44start() -> {ok,pid()} | {error,Reason}
  45start(Options) -> {ok,pid()} | {error,Reason}
  46
  47
  48Types:
  49
  50Options = [Option]
  51
  52
  53Options may contain both options which will be default options to a
  54runtime component when started, and options to the control component.
  55See add_nodes/3 for details on runtime component options. The control
  56component recognizes the following options:
  57
  58:{subscribe,Pid}: Making the process Pid receive Inviso events from
  59  the control component. Starts a control component process on the local
  60  node. A control component must be started before runtime components
  61  can be started manually or otherwise accessed through the inviso API.
  62
  63
  64stop() -> shutdown
  65
  66
  67Stops the control component. Runtime components are left as is. They
  68will behave according to their dependency values.
  69
  70add_node(RTtag) -> NodeResult | {error,Reason}
  71add_node(RTtag,Options) -> NodeResult | {error,Reason}
  72
  73
  74Types:
  75
  76RTtag = PreviousRTtag = term()
  77Options = [Option]
  78�Option -- see below
  79�Option = {dependency,Dep}
  80��Dep = int() | infinity
  81
  82The timeout, in milliseconds, before the runtime component will
  83terminate if abandoned by this control component. �Option =
  84{overload,Overload} | overload
  85Controls how and how often overload checks shall be performed. Just
  86overloadspecifies that no loadcheck shall be performed. ��Overload =
  87Interval | {LoadMF,Interval,InitMFA,RemoveMFA}
  88���LoadMF = {Mod,Func} | function()/1
  89���Interval = int() | infinity
  90Interval is the time in milliseconds between overload checks.
  91���InitMFA = RemoveMFA = {Mod,Func,ArgList} | void
  92When starting up the runtime component or when changing options (see
  93change_options/2) the overload mechanism is initialized with a call to
  94the InitMFAfunction. It shall return LoadCheckData. Every time a load
  95check is performed, LoadMFis called with LoadCheckDataas its only
  96argument. LoadMFshall return okor {suspend,Reason}. When the runtime
  97component is stopped or made to change options involving changing
  98overload-check, the RemoveMFAfunction is called. Its return value is
  99discarded. NodeResult = {ok,NAns} | {error,Reason}
 100�NAns = new | {adopted,State,Status,PreviousRTtag} | already_added
 101��State = new | tracing | idle
 102��Status = running | {suspended,SReason}
 103
 104Starts or tries to connect to an existing runtime component at the
 105local node, regardless if the system is distributed or not. Options
 106will override any default options specified at start-up of the control
 107component.
 108
 109The PreviousRTtag can indicate if the incarnation of the runtime
 110component at the node in question was started by "us" and then can be
 111expected to do tracing according to "our" instructions or not.
 112
 113add_node_if_ref(RTtag) -> NodeResult |
 114{error,{wrong_reference,OtherTag}} | {error,Reason}
 115add_node_if_ref(RTtag,Options) -> NodeResult |
 116{error,{wrong_reference,OtherRef}} | {error,Reason}
 117
 118
 119Types:
 120
 121OtherRef = term()
 122
 123rttag of the running incarnation
 124As add_node/1,2 but will only adopt the runtime component if its rttag
 125is RTtag.
 126
 127add_nodes(Nodes,RTtag) -> {ok,NodeResults} | {error,Reason}
 128add_nodes(Nodes,RTtag,Options) -> {ok,NodeResults} | {error,Reason}
 129
 130
 131Types:
 132
 133Nodes = [Node]
 134NodeResults = [{Node,NodeResult}]
 135
 136
 137As add_node/1,2 but for a distributed environment.
 138
 139add_nodes_if_ref(Nodes,RTtag) -> NodeResult | {error,Reason}
 140add_nodes_if_ref(Nodes,RTtag,Options) -> NodeResult | {error,Reason}
 141
 142
 143Types:
 144
 145Nodes = [Node]
 146NodeResults = [{Node,NodeResult}]
 147
 148
 149As add_node_if_ref/1,2 but for a distributed environment.
 150
 151stop_nodes() -> {ok,NodeResults} | NodeResult
 152stop_nodes(Nodes) -> {ok,NodeResults} | {error,Reason}
 153
 154
 155Types:
 156
 157NodeResults = [{Node,NodeResult}]
 158NodeResult = ok | {error,Reason}
 159
 160
 161Stops runtime component on Nodes. stop_nodes/0 will if the control
 162component is running on a distributed node stop all runtime
 163components. And if running on a non distributed node, stop the local
 164and only runtime component.
 165
 166stop_all() = {ok,NodeResults} | NodeResult
 167
 168
 169Types:
 170
 171NodeResults = [{Node,NodeResult}]
 172NodeResult = ok | {error,Reason}
 173
 174
 175A combination of stop/0 and stop_nodes/0.
 176
 177change_options(Options) -> NodeResult | {ok,NodeResults} |
 178{error,Reason}
 179change_options(Nodes,Options) -> {ok,NodeResults} | {error,Reason}
 180
 181
 182Types:
 183
 184Nodes = [Node]
 185NodeResults = [{Node,NodeResult}]
 186NodeResult = ok | {error,Reason}
 187
 188
 189Changes the options for one or several runtime components. If for
 190instance overload is redefined, the previous overload will be stopped
 191and the new started. See add_node/1 for details on Options.
 192
 193init_tracing(TracerData) -> {ok,NodeResults} | NodeResult |
 194{error,Reason}
 195init_tracing(TracerList) -> {ok,NodeResults} | {error,Reason}
 196init_tracing(Nodes,TracerData) -> {ok,NodeResults} | {error,Reason}
 197
 198
 199Types:
 200
 201TracerData = [{trace,LogTD} [,{ti,TiTD}] }] | LogTD
 202LogTD = {HandlerFun,Data1} | collector | {relayer,CollectingNode} |
 203{ip,IPPortParameters} | {file,FilePortParameters}
 204TiTD = {file,FileName} | {file,FileName,TiSpec} | {relay,Node}
 205�TiSpec = {InitMFA,RemoveMF,CleanMF}
 206��InitMFA = {Mi,Fi,Argsi}
 207��RemoveMF = {Mr,Fr} | void
 208��CleanMF = {Mc,Fc}
 209��Mi = Fi = Mr = Fr = Mc = Fd = atom()
 210��Argsi = [term()]
 211TracerList = [{Node,TracerData}]
 212IPPortParameters = Portno | {Portno,Qsize}
 213�Portno = tcp_portno()
 214�Qsize = int()
 215FilePortParameters = {Filename,wrap,Tail,{time,WrapTime},WrapCnt} |
 216{FileName,wrap,Tail,WrapSize,WrapCnt} | {FileName,wrap,Tail,WrapSize}
 217| {FileName,wrap,Tail} | FileName
 218�FileName = string()
 219�Tail = string() =/= ""
 220�WrapTime = WrapCnt = WrapSize = int() >0
 221TracerList = [{Node,TracerData}]
 222Nodes = [Node]
 223HandlerFun = function()/2;
 224�HandlerFun(TraceMsg,Data1) -> NewData
 225CollectingNode = pid() | node()
 226NodeResults = [{Node,NodeResult}]
 227NodeResult = {ok,LogResults} | {error,NReason}
 228�LogResults = [LogResult]
 229��LogResult = {trace_log,LogRes} | {ti_log,LogRes}
 230���LogRes = ok | {error,Reason}
 231
 232
 233Starts the tracing at the specified nodes, meaning that the runtime
 234components transits from the state new or idle to tracing. For trace
 235messages to be generated, there must of course also be trace pattern
 236and/or trace flags set. Such can not be set before tracing has been
 237initiated with init_tracing/1,2.
 238
 239TracerData controls how the runtime component will handle generated
 240trace messages. The trace tag controls how regular trace messages are
 241handled. The ti tag controls if and how trace information will be
 242stored and the meta tracer will be activated. That is if ti is
 243omitted, no meta tracer will be started as part of the runtime
 244component. It is possible to have ti without trace, but most likely
 245not useful.
 246
 247The ip and file trace tracerdata instructions results in using the
 248built in trace ip-port and file-port respectively. relayer will result
 249in that all regular trace messages are forwarded to a runtime
 250component at the specified node. Using a HandlerFun will result in
 251that every incoming regular trace message is applied to the
 252HandlerFun. collector can be used to use this runtime component to
 253receive relayed trace messages and print them to the shell.
 254
 255The trace information can be configured to either write trace
 256information to a plain trace information file or to relay it to
 257another inviso meta tracer on another node. The inviso meta tracer is
 258capable of matching function calls with their function returns (only
 259if return_trace is activated in the meta trace match specification for
 260the function in question). This is necessary since it may not be
 261possible to decide what to do, if anything shall be done at all, until
 262the return value of the function call is examined.
 263
 264To be able to match calls with returns a state can be saved when
 265detecting a function call in a public loop data structure kept by the
 266inviso meta tracer. The public loop data structure is given as
 267argument to a handler-function called whenever a meta trace message
 268arrives to the inviso meta tracer (both function calls and function
 269returns). The public loop data structure is first initiated by the
 270Mi:Fi function which takes the items in Argsi as arguments. Fi shall
 271return the initial public loop data structure. When meta tracing is
 272stopped, either because tracing is stopped or because tracing is
 273suspended, the Mr:Fr(PublicLoopData) is called to offer a possibility
 274to clean-up. Note that for every function meta-tracing is activated, a
 275public loop data modification function can be speficied. That function
 276will prepare the current loop data structure for this particular
 277function.
 278
 279Further there is a risk that function call states becomes abandoned
 280inside the public loop data structure. This will happen if a function
 281call is entered into the public loop data structure, but no function
 282return occurs. To prevent the public loop data structure from growing
 283infinitely the clean function Fc will periodically be called with the
 284public loop data structure as argument. Elements entered into the
 285public loop data structure as a result of a function call must contain
 286a timestamp for the Fc to be able to conclude if it is abandoned or
 287not. Fc shall return a new public loop data structure.
 288
 289When initiating tracing involving trace information without a TiSpec,
 290a default public loop data structure will be initiated to handle
 291locally registered process aliases. The default public loop data
 292structure is a two-tuple where the first element is used by the meta
 293tracing on the BIF register/2. The second element is left for user
 294usage.
 295
 296The default public loop data structure may be extended with more
 297element positions. The first position must be left to the
 298implementation of registered-name translations. If the public loop
 299data structure is changed no longer meeting this requirement, the
 300tpm_localnames/0,1 and tpm_globalnames/0,1 can no longer be used.
 301
 302A wrap files specification is used to limit the disk space consumed by
 303the trace. The trace is written to a limited number of files each with
 304a limited size. The actual filenames are Filename ++ SeqCnt ++ Tail,
 305where SeqCnt counts as a decimal string from 0 to WrapCnt and then
 306around again from 0. When a trace message written to the current file
 307makes it longer than WrapSize, that file is closed, if the number of
 308files in this wrap trace is as many as WrapCnt the oldest file is
 309deleted then a new file is opened to become the current. Thus, when a
 310wrap trace has been stopped, there are at most WrapCnt trace files
 311saved with a size of at least WrapSize (but not much bigger), except
 312for the last file that might even be empty. The default values are
 313WrapSize == 128*1024 and WrapCnt == 8.
 314
 315The SeqCnt values in the filenames are all in the range 0 through
 316WrapCnt with a gap in the circular sequence. The gap is needed to find
 317the end of the trace.
 318
 319If the WrapSize is specified as {time,WrapTime}, the current file is
 320closed when it has been open more than WrapTime milliseconds,
 321regardless of it being empty or not.
 322
 323The ip trace driver has a queue of QSize messages waiting to be
 324delivered. If the driver cannot deliver messages as fast as they are
 325produced by the runtime system, they are dropped. The number of
 326dropped messages are indicated in the trace log as separate trace
 327message.
 328
 329stop_tracing(Nodes) -> {ok,NodeResults} | {error,Reason}
 330stop_tracing() -> {ok,NodeResults} | NodeResult
 331
 332
 333Types:
 334
 335Nodes = [Node]
 336NodeResults = [{Node,NodeResult}]
 337NodeResult = {ok,State} | {error,Reason}
 338�State = new | idle
 339
 340
 341Stops tracing on all or specified Nodes. Flushes the trace buffer if a
 342trace-port is used, closes the trace-port and removes all trace flags
 343and meta-patterns. The nodes are called in parallel.
 344
 345Stopping tracing means going to state idle<c>. If the runtime
 346component was already in state <c>new, it will of course remain in
 347state new (then there was no tracing to stop).
 348
 349clear() -> {ok,NodeResults} | NodeResult
 350clear(Nodes,Options) -> {ok,NodeResults} | {error,Reason}
 351clear(Options) -> {ok,NodeResults} | NodeResult | {error,Reason}
 352
 353
 354Types:
 355
 356Nodes = [Node]
 357Options = [Option]
 358�Option = keep_trace_patterns | keep_log_files
 359NodeResults = [{Node,NodeResult}]
 360�NodeResult = {ok,{new,Status}} | {error,Reason}
 361��Status = running | {suspended,SReason}
 362
 363
 364Stops all tracing including removing meta-trace patterns. Removes all
 365trace patterns. If the node is tracing or idle, trace-logs belonging
 366to the current tracerdata are removed. Hence the node is returned to
 367state new. Note that the node can still be suspended.
 368
 369Various options can make the node keep set trace patterns and log-
 370files. The node still enters the new state.
 371
 372tp(Nodes,Mod,Func,Arity,MatchSpec,Opts) ->
 373tp(Nodes,Mod,Func,Arity,MatchSpec) -> {ok,NodeResults} |
 374{error,Reason}
 375tp(Mod,Func,Arity,MatchSpec,Opts) ->
 376tp(Mod,Func,Arity,MatchSpec) -> {ok,NodeResults} | NodeResult |
 377{error,Reason}
 378tp(Nodes,PatternList) -> {ok,NodeResults} | {error,Reason}
 379tp(PatternList) -> {ok,NodeResults} | NodeResult | {error,Reason}
 380
 381
 382Types:
 383
 384Nodes = [Node]
 385Mod = Func = atom() | '_'
 386Arity = int() | '_'
 387MatchSpec = true | false | [] | matchspec()
 388PatternList = [Pattern],
 389�Pattern = {Mod,Func,Arity,MatchSpec,Opts}
 390Opts = [Opt]
 391�Opt = only_loaded
 392NodeResults = [NodeResult]
 393�NodeResult = {ok,[Ans]} | {error,Reason}
 394��Ans = int() | {error,Reason}
 395
 396
 397Set trace pattern (global) on specified or all nodes. The integer
 398replied if the call was successfully describes the number of matched
 399functions. The functions without a Nodes argument means all nodes, in
 400a non-distributed environment it means the local node. Using wildcards
 401follows the rules for wildcards of erlang:trace_pattern/3. It is for
 402instance illegal to specify M == '_' while F is not '_'.
 403
 404When calling several nodes, the nodes are called in parallel.
 405
 406The option only_loaded will prevent modules not loaded (yet) into the
 407runtime system to become loaded just as a result of that a trace
 408pattern is requested to be set on it. Otherwise modules are
 409automatically loaded if not already loaded (since the module must be
 410present for a trace pattern to be set on it). The latter does not
 411apply if the wildcard '_' is used as module specification.
 412
 413tpl(Nodes,Mod,Func,Arity,MatchSpec) ->
 414tpl(Nodes,Mod,Func,Arity,MatchSpec,Opts) -> {ok,NodeResults} |
 415{error,Reason}
 416tpl(Mod,Func,Arity,MatchSpec) ->
 417tpl(Mod,Func,Arity,MatchSpec,Opts) -> {ok,NodeResults} | NodeResult|
 418{error,Reason}
 419tpl(Nodes,PatternList) -> {ok,NodeResults} | {error,Reason}
 420tpl(PatternList) -> {ok,NodeResults} | NodeResult | {error,Reason}
 421
 422
 423See tp/N function above for details on arguments and return values.
 424
 425Set local trace pattern on specified functions. When calling several
 426nodes, the nodes are called in parallel.
 427
 428ctp(Nodes,Mod,Func,Arity) -> {ok,NodeResults} | {error,Reason}
 429ctp(Mod,Func,Arity) -> {ok,NodeResults} | NodeResult | {error,Reason}
 430
 431
 432See tp/N for argument descriptions.
 433
 434Clear global trace patterns. When calling several nodes, the nodes are
 435called in parallel.
 436
 437ctpl(Nodes,Mod,Func,Arity) -> {ok,NodeResults} | {error,Reason}
 438ctpl(Mod,Funct,Arity) -> {ok,NodeResults} | NodeResult |
 439{error,Reason}
 440
 441
 442See tp/N for argument description.
 443
 444Clear local trace patterns. When calling several nodes, the nodes are
 445called in parallel.
 446
 447tf(Nodes,PidSpec,FlagList) -> {ok,NodeResults} | {error,Reason}
 448tf(PidSpec,FlagList) -> {ok,NodeResults} | NodeResult | {error,Reason}
 449tf(Nodes,TraceConfList) -> {ok,NodeResults} | {error,Reason}
 450tf(NodeTraceConfList) -> {ok,NodeResults} | {error,Reason}
 451tf(TraceConfList) -> {ok,NodeResults} | NodeResult | {error,Reason}
 452
 453
 454Types:
 455
 456Nodes = [Node]
 457NodeTraceConfList = [{Node,TraceConfList}]
 458TraceConfList = [{PidSpec,FlagList}]
 459FlagList = [Flag]
 460PidSpec = all | new| existing | pid() | locally_registered_name()
 461Flag -- see erlang:trace/3
 462NodeResult = {ok,[Ans]} | {error,Reason}
 463Ans = int() | {error,Reason}
 464
 465
 466Set process trace flags on processes on all or specified nodes. The
 467integer returned if the call was successful describes the matched
 468number of processes. The functions without a Nodes argument means all
 469nodes, in a non-distributed environment it means the local node.
 470
 471There are many combinations which does not make much sense. For
 472instance specifying a certain process identifier at all nodes. Or an
 473empty TraceConfList for all nodes.
 474
 475When calling several nodes, the nodes are called in parallel.
 476
 477ctf(Nodes,PidSpec,FlagList) -> {ok,NodeResults} | {error,Reason}
 478ctf(PidSpec,FlagList) -> {ok,NodeResults} | NodeResult |
 479{error,Reason}
 480ctf(Nodes,TraceConfList) -> {ok,NodeResults} | {error,Reason}
 481ctf(TraceConfList) -> {ok,NodeResults} | NodeResult | {error,Reason}
 482
 483
 484See tf/N for arguments and return value description.
 485
 486Clear process trace flags on all or specified nodes. When calling
 487several nodes, the nodes are called in parallel.
 488
 489ctf_all(Nodes) -> {ok,NodeResults} | {error,Reason}
 490ctf_all() -> {ok,NodeResults} | NodeResult | {error,Reason}
 491
 492
 493Types:
 494
 495Nodes = [Node]
 496NodeResults = [{Node,NodeResult}]
 497NodeResult = ok | {error,Reason}
 498
 499
 500Clears all trace flags on all or specified nodes. Just for
 501convenience.
 502
 503init_tpm(Mod,Func,Arity,CallFunc) -> {ok,NodeResults} | NodeResult |
 504{error,Reason}
 505init_tpm(Nodes,Mod,Func,Arity,CallFunc) -> {ok,NodeResults} |
 506{error,Reason}
 507init_tpm(Mod,Func,Arity,InitFunc,CallFunc,ReturnFunc,RemoveFunc) ->
 508{ok,NodeResults} | NodeResult | {error,Reason}
 509init_tpm(Nodes,Mod,Func,Arity,
 510InitFunc,CallFunc,ReturnFunc,RemoveFunc) -> {ok,NodeResults} |
 511{error,Reason}
 512
 513
 514Types:
 515
 516Mod = Func = atom()
 517Arity = int()
 518NodeResults = [{Node,NodeResult}]
 519NodeResult = ok | {error,Reason}
 520InitFunc,RemoveFunc = {Module,Function} | function()/4 | void
 521CallFunc = ReturnFunc = {Module,Function} | function()/3 | void
 522
 523
 524Initializes Mod:Func/Arity for meta tracing without setting any meta
 525trace patterns. This is necessary if the named match specs will be
 526used (see tpm_ms/5,6). Otherwise initialization of public loop data
 527can be done at the same time as setting meta trace patterns using
 528tpm/8,9.
 529
 530Note that we can not use wildcards here (even if it is perfectly legal
 531in Erlang). It also sets the CallFunc and ReturnFunc for the meta
 532traced function. That is the functions which will be called when a
 533function call and a return_trace meta trace message respectively
 534arrives to the inviso meta tracer for Mod:Func/Arity.
 535
 536This function is also available without InitFunc and RemoveFunc. That
 537means that no initialization of the public loop data structure will be
 538done and that CallFunc and ReturnFunc must either use already existing
 539parts of public loop data structure or not use it at all.
 540
 541The InitFunc initializes the already existing public loop data
 542structure for use with Mod:Func/Arity. InitFunc(Mod,Func,Arity,PublLD)
 543-> {ok,NewPublLD,Output} where OutPut can be a binary which will then
 544be written to the trace information file. If it is not a binary, no
 545output will be done. RemoveFunc will be called when the meta tracing
 546is cleared with ctpm/3,4. RemoveFunc(Mod,Func,Arity,PublLD) ->
 547{ok,NewPublLD}.
 548
 549See tpm/N for details on CallFunc and ReturnFunc.
 550
 551tpm(Mod,Func,Arity,MS) -> {ok,NodeResults} | NodeResult |
 552{error,Reason}
 553tpm(Nodes,Mod,Func,Arity,MS) -> {ok,NodeResults} | {error,Reason}
 554tpm(Mod,Func,Arity,MS,CallFunc) -> {ok,NodeResults} | NodeResults |
 555{error,Reason}
 556tpm(Nodes,Mod,Func,Arity,MS,CallFunc) -> {ok,NodeResults} |
 557{error,Reason}
 558tpm(Mod,Func,Arity,MS,InitFunc,CallFunc,ReturnFunc,RemoveFunc) ->
 559{ok,NodeResults} | NodeResults | {error,Reason}
 560tpm(Nodes,Mod,Func,Arity,MS, InitFunc,CallFunc,ReturnFunc,RemoveFunc)
 561-> {ok,NodeResults} | {error,Reason}
 562
 563
 564Types:
 565
 566Mod = Func = atom()
 567Arity = int()
 568MS = [match_spec()]
 569Nodes = [Node]
 570InitFunc = RemoveFunc = {Module,Function} | function()/4 | void
 571CallFunc = ReturnFunc = {Module,Function} | function()/3 | void
 572NodeResults = [{Node,NodeResult}]
 573NodeResult = {ok,1} | {ok,0} | {error,Reason}1
 574
 575
 576Activates meta-tracing in the inviso_rt_meta tracer. Except when using
 577tpm/6, tpm/8 and tpm/9 the Mod:Func/Arity must first have been
 578initiated using init_tpm/N. When calling several nodes, the nodes are
 579called in parallel.
 580
 581CallFunc will be called every time a meta trace message arrives to the
 582inviso meta tracer because of a call to Func.
 583CallFunc(CallingPid,ActualArgList,PublLD) -> {ok,NewPrivLD,Output}
 584where Output can be a binary or void. If it is a binary it will be
 585written to the trace information file.
 586
 587ReturnFunc will be called every time a meta return_trace message
 588arrives to the inviso meta tracer because of a return_trace of a call
 589to Func. ReturnFunc(CallingPid,ReturnValue,PublLD) ->
 590{ok,NewPrivLD,Output}. Further the ReturnFunc must handle the fact
 591that a return_trace message arrives for a call which was never
 592noticed. This because the message queue of the meta tracer may have
 593been emptied.
 594
 595tpm_tracer(Mod,Func,Arity,MS) -> {ok,NodeResults} | NodeResult |
 596{error,Reason}
 597tpm_tracer(Nodes,Mod,Func,Arity,MS) -> {ok,NodeResults} |
 598{error,Reason}
 599tpm_tracer(Mod,Func,Arity,MS,CallFunc) -> {ok,NodeResults} |
 600NodeResults | {error,Reason}
 601tpm_tracer(Nodes,Mod,Func,Arity,MS,CallFunc) -> {ok,NodeResults} |
 602{error,Reason}
 603tpm_tracer(Mod,Func,Arity,MS,InitFunc,CallFunc,ReturnFunc,RemoveFunc)
 604-> {ok,NodeResults} | NodeResults | {error,Reason}
 605tpm_tracer(Nodes,Mod,Func,Arity,MS,
 606InitFunc,CallFunc,ReturnFunc,RemoveFunc) -> {ok,NodeResults} |
 607{error,Reason}
 608
 609
 610See tpm/X for details on arguments and return values.
 611
 612Same as tpm/X but all match specs in MS containing a trace action term
 613will have a {tracer,Tracer} appended to its enable-list. Tracer will
 614be the current output for regular trace messages as specified when
 615tracing was initiated. This function is useful when setting a meta
 616trace pattern on a function with the intent that its execution shall
 617turn tracing on for the process executing the match-spec in the meta
 618trace pattern. The reason the tracer process trace flag can not be
 619explicitly written in the action term by the user is that it may be
 620difficult to learn its exact value for a remote node. Further more
 621inviso functions are made to work on several nodes at the same time,
 622requiering different match specs to be set for different nodes.
 623
 624Simple example: We want any process executing the function
 625mymod:init(1234) (with the argument, exactly the integer 1234) to
 626begin function-call tracing. In the example, if the process is found
 627to be one that shall start call tracing, we also first disable all
 628process trace flags to ensure that we have full control over what the
 629process traces. void in the example specifies that the meta-tracer
 630(inviso_rt_meta) will not call any function when meta trace messages
 631for mymod:init/1 arrives. There is no need for a CallFunc since the
 632side-effect (start call-tracing) is achieved immediately with the
 633match-spec.
 634
 635
 636.. sourcecode:: erlang
 637
 638    
 639        inviso:tpm_tracer(mymod,init,1,[{[1234],[],[{trace,[all],[call]}]}],void).        
 640
 641
 642This will internally, by the meta tracer on each Erlang node, be
 643translated to:
 644
 645
 646.. sourcecode:: erlang
 647
 648    
 649        erlang:trace_pattern({mymod,init,1},[{[1234],[],[{trace,[all],[call,{{tracer,T}}]}]}],[{meta,P}]).
 650            
 651
 652
 653Where T is the tracer for regular trace messages (most often a trace-
 654port, but can be the runtime component inviso_rt process), and P is
 655the meta tracer (the inviso_rt_meta process).
 656
 657tpm_ms(Mod,Func,Arity,MSname,MS) -> {ok,NodeResults} | NodeResult |
 658{error,Reason}
 659tpm_ms(Nodes,Mod,Func,Arity,MSname,MS) -> {ok,NodeResults} |
 660{error,Reason}
 661
 662
 663Types:
 664
 665Nodes = [Node]<v> <v>Mod = Func = atom()<v> <v>Arity = int()<v>
 666<v>MSname = term()<v> <v>MS = [match_spec()]<v> <v>NodeResults =
 667[{Node,NodeResult}]<v> <v>NodeResult = {ok,1} | {ok,0} |
 668{error,Reason}<v>
 669
 670
 671This function adds a list of match-specs to the already existing ones.
 672It uses an internal database to keep track of existing match-specs.
 673This set of match specs can hereafter be referred to with the name
 674MSname. If the match-spec does not result in any meta traced functions
 675(for whatever reason), the MS is not saved in the database. The
 676previously known match-specs are not removed. If MSname is already in
 677use as a name refering to a set of match-specs for this particular
 678meta-traced function, the previous set of match-specs are replaced
 679with MS.
 680
 681Mod:Func/Arity must previously have been initiated in order for this
 682function to add a match-spec.
 683
 684When calling several nodes, the nodes are called in parallel. {ok,1}
 685indicates success.
 686
 687tpm_ms_tracer(Mod,Func,Arity,MSname,MS) -> {ok,NodeResults} |
 688NodeResult | {error,Reason}
 689tpm_ms_tracer(Nodes,Mod,Func,Arity,MSname,MS) -> {ok,NodeResults} |
 690{error,Reason}
 691
 692
 693See tpm_ms/X for details on arguments and return values, and
 694tpm_tracer/X for explanations about the appending of {tracer,Tracer}
 695process trace flag.
 696
 697ctpm_ms(Mod,Func,Arity,MSname) -> {ok,NodeResults} | NodeResult |
 698{error,Reason}
 699ctpm_ms(Nodes,Mod,Func,Arity,MSname) -> {ok,NodeResults} |
 700{error,Reason}
 701
 702
 703Types:
 704
 705NodeResults = [{Node,NodeResult}]
 706NodeResult = ok | {error,Reason}
 707
 708
 709Removes a named match-spec from the meta traced function. Note that it
 710never is a fault to remove a match spec. Not even from a function
 711which is non existent.
 712
 713When calling several nodes, the nodes are called in parallel.
 714
 715ctpm(Mod,Func,Arity) -> {ok,NodeResults} | NodeResult | {error,Reason}
 716ctpm(Nodes,Mod,Func,Arity) -> {ok,NodeResults} | {error,Reason}
 717
 718
 719Types:
 720
 721NodeResults = [{Node,NodeResult}]
 722NodeResult = ok | {error,Reason}
 723
 724
 725Removes the meta trace pattern for the function, means stops
 726generating output for this function. The public loop data structure
 727may be cleared by the previously entered RemoveFunc.
 728
 729When calling several nodes, the nodes are called in parallel.
 730
 731tpm_localnames() -> {ok,NodeResults} | NodeResult | {error,Reason}
 732tpm_localnames(Nodes) -> {ok,NodeResults} | {error,Reason}
 733
 734
 735Types:
 736
 737NodeResults = [{Node,NodeResult}]
 738NodeResult = {R1,R2}
 739R1 = R2 = {ok,0} | {ok,1} | {error,Reason}
 740
 741
 742Quick version for setting meta-trace patterns on erlang:register/2. It
 743uses a default CallFunc and ReturnFunc in the meta-tracer server. The
 744main purpose of this function is to create ti-log entries for
 745associations between pids and registered name aliases. The
 746implementation uses return_trace to see if the registration was
 747successful or not, before actually making the ti-log alias entry.
 748Further the implementation also meta traces the BIF unregister/1.
 749
 750If both N1 and N2 is 1, function call was successful. N1 and N2
 751represent setting meta trace pattern on register/2 and unregister/1.
 752
 753ctpm_localnames() -> {ok,NodeResults} | NodeResult | {error,Reason}
 754ctpm_localnames(Nodes) -> {ok,NodeResults} | {error,Reason}
 755
 756
 757Types:
 758
 759NodeResults = [{Node,NodeResult}]
 760NodeResult = {R1,R2}
 761R1 = R2 = ok | {error,Reason}
 762
 763
 764Function for removing previously set patters by tpm_localnames/0. The
 765two results R1 and R2 represents that meta pattern is removed from
 766both register/2 and unregister/1.
 767
 768tpm_globalnames() -> {ok,NodeResults} | NodeResult | {error,Reason}
 769tpm_globalnames(Nodes) -> {ok,NodeResults} | {error,Reason}
 770
 771
 772Types:
 773
 774NodeResults = [{Node,NodeResult}]
 775NodeResult = {R1,R2}
 776R1 = R2 = {ok,0} | {ok,1} | {error,Reason}
 777
 778
 779Quick version for setting meta-trace patterns capable of learning the
 780association of a pid with a globally registered name (registered using
 781global:register_name). The implementation meta-traces on
 782global:handle_call({register,'_','_','_'},'_','_') and
 783global:delete_global_name/2. The N1 and N2 represents the success of
 784the two sub-tmp calls.
 785
 786ctpm_globalnames() -> {ok,NodeResults} | NodeResult | {error,Reason}
 787ctpm_globalnames(Nodes) -> {ok,NodeResults} | {error,Reason}
 788
 789
 790Types:
 791
 792NodeResults = [{Node,NodeResult}]
 793NodeResult = {R1,R2} | {error,Reason}
 794R1 = R2 = ok | {error,Reason}
 795
 796
 797Function for removing previously set meta patters by
 798tpm_globalnames/0,1. The two results R1 and R2 represents that meta
 799pattern are removed from both global:handle_call/3 and
 800global:delete_global_name/1.
 801
 802ctp_all() -> {ok,NodeResults} | NodeResult | {error,Reason}
 803ctp_all(Nodes) -> {ok,NodeResults} | {error,Reason}
 804
 805
 806Types:
 807
 808NodeResults = [{Node,NodeResult}]
 809NodeResult = ok | {error,Reason}
 810
 811
 812Clears all, both global and local trace patterns. Does not clear meta
 813trace patterns. Equivalent to a call to ctp/3,4 and to ctpl/3,4 with
 814wildcards '_' for all modules, functions and arities.
 815
 816suspend(SReason) -> {ok,NodeResults} | NodeResult | {error,Reason}
 817suspend(Nodes,SReason) -> {ok,NodeResults} | {error,Reason}
 818
 819
 820Types:
 821
 822SReason = term()
 823NodeResults = [{Node,NodeResult}]
 824NodeResult = ok | {error,Reason}
 825
 826
 827Suspends the runtime components. SReason will become the suspend-
 828reason replied in for instance a get_status/0,1 call. A runtime
 829component that becomes suspended removes all trace flags and all meta
 830trace patterns. In that way trace output is no longer generated. The
 831task of reactivating a suspended runtime component is outside the
 832scoop of inviso. It can for instance be implemented by a higher layer
 833trace-tool "remembering" all trace flags and meta patterns set.
 834
 835cancel_suspension() -> {ok,NodeResults} | NodeResult | {error,Reason}
 836cancel_suspend(Nodes) -> {ok,NodeResults} | {error,Reason}
 837
 838
 839Types:
 840
 841NodeResults = [{Node,NodeResult}]
 842NodeResult = ok | {error,Reason}
 843
 844
 845Makes the runtime components running again (as opposite to suspended).
 846Since reactivating previous trace flags and meta trace patterns is
 847outside the scoop of inviso, cancelling suspension is simply making it
 848possible to set trace flags and meta trace patterns again.
 849
 850get_status() -> {ok,NodeResults} | NodeResult | {error,Reason}
 851get_status(Nodes) -> {ok,NodeResults} | {error,Reason}
 852
 853
 854Types:
 855
 856NodeResults = [{Node,NodeResult}]
 857NodeResult = {ok,{State,Status}} | {error,Reason}
 858State = new | idle | tracing
 859Status = running | {suspended,SReason}
 860SReason = term()
 861
 862
 863Finds out the state and status of a runtime component. A runtime
 864component is in state new before it has been initiated to do any
 865tracing the first time. There are clear-functions which can make a
 866runtime component become new again without having to restart. A
 867runtime component becomes idle after tracing is stopped.
 868
 869get_tracerdata() -> {ok,NodeResults} | NodeResult | {error,Reason}
 870get_tracerdata(Nodes) -> {ok,NodeResults} | {error,Reason}
 871
 872
 873Types:
 874
 875NodeResults = [{Node,NodeResult}]
 876NodeResult = {ok,NResult} | {error,Reason}
 877NResult = TracerData | no_tracerdata
 878
 879
 880Returns the current tracerdata of a runtime component. A runtime
 881component in state new can not have tracerdata. An idle runtime
 882component does have tracerdata, the last active tracerdata. TracerData
 883will be a term as specified to init_tracing when tracing was initiated
 884for the runtime component.
 885
 886list_logs() -> {ok,NodeResults} | NodeResult | {error,Reason}
 887list_logs(Nodes) -> {ok,NodeResults} | {error,Reason}
 888list_logs(NodeTracerData) -> {ok,NodeResults} | {error,Reason}
 889list_logs(TracerData) -> {ok,NodeResults} | NodeResult |
 890{error,Reason}
 891
 892
 893Types:
 894
 895TracerData -- see init_tracing/1,2
 896NodeResults = [{Node,NodeResult}]
 897NodeResult = {ok,FileList} | {ok,no_log} | {error,Reason}
 898�FileList = [FileType]
 899��FileType = {trace_log,Dir,Files} | {ti_log,Dir,Files}
 900��Files = [FileNameWithOutPath]
 901
 902
 903Returns the actually existing log files associated with TracerData. If
 904a tracerdata is not specified, current tracerdata is used for that
 905particular runtime component. Files will be a list of one or more
 906files should it be a wrap-set. Otherwise the it is a list of only one
 907filename.
 908
 909This function is useful to learn the name and path of all files
 910belonging to a trace. This information can later be used to move those
 911files for merging. Note that since it is possible to ask on other
 912tracerdata than the current, it is possible to learn filenames of
 913previously done traces, under the circumstances that they have not
 914been removed.
 915
 916fetch_log(LogSpecList,DestDir,Prefix) -> {ok,NodeResults} |
 917{error,not_distributed} | {error,Reason}
 918fetch_log(DestDir,Prefix) -> {ok,NodeResults} |
 919{error,not_distributed} | {error,Reason}
 920
 921
 922Types:
 923
 924DestDir = string()
 925Prefix = string()
 926LogSpecList = [LogSpec]
 927�LogSpec = {Node,FileSpecList} | Node | {Node,TracerData}
 928TracerData = see init_tracing/1,/2
 929FileSpecList = [{trace_log,Dir,FileList},{ti_log,Dir,FileList}] |
 930[{trace_log,Dir,FileList}]
 931�FileList = [RemoteFileName]
 932NodeResult = {Conclusion,ResultFileSpec} | no_log | {error,NReason}
 933�NReason = own_node | Reason
 934�Conclusion = complete | incomplete
 935�ResultFileSpec = [{trace_log,FileResults},{ti_log,FileResults}]
 936��FileResults = [FileResult]
 937��� FileResult = {ok,FileName} | {error,FReason}
 938����FReason = {file_open,{posix(),FileName}} |
 939{file_open,{posix(),RemoteFileName}} |
 940{file_open,{posix(),[DestDir,Prefix,RemoteFileName]}} |
 941{file_write,{posix(),FileName}} | {truncated,FileName} |
 942{truncated,{Reason,FileName}}
 943�����posix() = atom()
 944
 945
 946Copies log files over distributed erlang to the control component
 947node. This function can only be used in a distributed system.
 948
 949The resulting transferred files will have the prefix Prefix and will
 950be located in DestDir. The source files can either be pointed out
 951using a FileListSpec or tracerdata. If no files are explicitly
 952specified, current tracerdata for that node will be used. Note that if
 953source files have the same name (on several nodes) they will overwrite
 954each other at DestDir.
 955
 956delete_log(Nodes,TracerData) -> {ok,NodeResults} | {error,Reason}
 957delete_log(NodeSpecList) -> {ok,NodeResults} | {error,Reason}
 958delete_log(Spec) -> {ok,NodeResults} | NodeResult | {error,Reason}
 959delete_log(TracerData) -> {ok,NodeResults} | NodeResult |
 960{error,Reason}
 961delete_log() -> {ok,NodeResults} | NodeResult | {error,Reason}
 962
 963
 964Types:
 965
 966Nodes = [Node]
 967NodeSpecList = [{Node,Spec}]
 968�Spec = [AbsPathFileName] | LogSpecs
 969��LogSpecs = [LogSpec]
 970���LogSpec = {trace_log,Dir,[FileNameWithoutPath]} |
 971{ti_log,Dir,[FileNameWithoutPath]}
 972TracerData -- see init_tracing/1,/2
 973NodeResults = [{Node,NodeResult}]
 974NodeResult = {ok,no_log} | {ok,LogInfos} | {ok,FileInfos}
 975�LogInfos = [LogInfo]
 976��LogInfo = {trace_log,FileInfos} | {ti_log,FileInfos}
 977�FileInfos = [FileInfo]
 978��FileInfo = {ok,FileName} | {error,Reason}
 979
 980
 981Deletes listed files or files corresponding to tracerdata. If no
 982tracerdata or list of files are specified in the call, current
 983tracerdata at the runtime components will be used to identify files to
 984delete. All filenames shall be strings.
 985
 986FileName can either be an absolute path or just a filename depending
 987on if AbsPathFileName or a LogSpec was used to identify the file.
 988
 989subscribe() -> ok | {error,Reason}
 990subscribe(Pid) -> ok | {error,Reason}
 991
 992
 993Types:
 994
 995Pid = pid()
 996
 997
 998Adds Pid or self() if using subscribe/0 to the inviso-event sending
 999list. Note that it is possible to add a pid several times and that the
1000Pid then will receive multiple copies of inviso-event messages.
1001
1002All events will be sent to all subscribers in the event sending list.
1003
1004
1005.. sourcecode:: erlang
1006
1007    
1008    Event = {inviso_event,ControllerPid,erlang:localtime(),Msg}
1009      Msg = {connected, Node, {RTtag, {State,Status}}}
1010          | {disconnected, Node, NA}
1011          | {state_change,Node,{State,Status}}
1012          | {port_down,Node,Reason}
1013        Node = node() | local_runtime
1014            
1015
1016
1017Subscribing to inviso-event may be necessary for a higher layer trace-
1018tool using inviso to follow the runtime components. local_runtime will
1019be used for a runtime component running in a non-distributed
1020environment.
1021
1022unsubscribe() -> ok
1023unsubscribe(Pid) -> ok
1024
1025
1026Removes Pid (once) from the subscription list.
1027
1028
1029
1030inviso 0.6
1031Copyright � 1991-2009 `Ericsson AB
1032<http://www.ericsson.com/technology/opensource/erlang>`__
1033
1034