1
<!doctype erlref PUBLIC "-//Stork//DTD erlref//EN">
4
<title>inviso_lfm</title>
10
<module>inviso_lfm</module>
11
<modulesummary>An Inviso Off-Line Logfile Merger</modulesummary>
13
<p>Implements an off-line logfile merger, merging binary trace-log files from several nodes together in chronological order. The logfile merger can also do pid-to-alias translations.</p>
15
<p>The logfile merger is supposed to be called from the Erlang shell or a higher layer trace tool. For it to work, all logfiles and trace information files (containing the pid-alias associations) must be located in the file system accessible from this node and organized according to the API description.</p>
17
<p>The logfile merger starts a process, the output process, which in its turn starts one reader process for every node it shall merge logfiles from. Note that the reason for a process for each node is not remote communication, the logfile merger is an off-line utility, it is to sort the logfile entries in chronological order.</p>
19
<p>The logfile merger can be customized both when it comes to the implementation of the reader processes and the output the output process shall generate for every logfile entry.</p>
24
<name>merge(Files, OutFile) -></name>
25
<name>merge(Files, WorkHFun, InitHandlerData) -></name>
26
<name>merge(Files, BeginHFun, WorkHFun, EndHFun, InitHandlerData)
27
-> {ok, Count} | {error, Reason}</name>
28
<fsummary>Merge logfiles into one file in chronological order
31
<v>Files = [FileDescription]</v>
32
<v> FileDescription = FileSet | {reader,RMod,RFunc,FileSet}
34
<v> FileSet = {Node, LogFiles}</v>
35
<v> Node = atom()</v>
36
<v> LogFiles =
37
[{trace_log, [FileName]} | {ti_log, [FileName]}]</v>
38
<v> FileName = string()</v>
39
<v> RMod = RFunc = atom()</v>
40
<v>OutFile = string()</v>
41
<v>BeginHFun = fun(InitHandlerData) ->
42
{ok, NewHandlerData} | {error, Reason}</v>
43
<v>WorkHFun = fun(Node, LogEntry, PidMappings, HandlerData) ->
44
{ok, NewHandlerData}</v>
45
<v> LogEntry = tuple()</v>
46
<v> PidMappings = term()</v>
47
<v>EndHFun = fun(HandlerData) -> ok | {error, Reason}</v>
49
<v>Reason = term()</v>
52
<p>Merges the logfiles in <c>Files</c> together into one file in chronological order. The logfile merger consists of an output process and one or several reader processes.</p>
54
<p>Returns <c>{ok, Count}</c> where <c>Count</c> is the total number of log entries process, if successful.</p>
56
<p>When specifying <c>LogFiles</c>, currently the standard reader-process only supports:</p>
58
<item>one single file</item>
59
<item>a list of wraplog files, following the naming convention <c><Prefix><Nr><Suffix></c>.</item>
62
<p><c>FileDescription == {reader,RMod,RFunc,FileSet}</c> indicates that <c>spawn(RMod, RFunc, [OutputPid,LogFiles])</c> shall create a reader process.</p>
64
<p>The output process is customized with <c>BeginHFun</c>, <c>WorkHFun</c> and <c>EndHFun</c>. If using <c>merge/2</c> a default output process configuration is used, basically creating a text file and writing the output line by line. <c>BeginHFun</c> is called once before requesting log entries from the reader processes. <c>WorkHFun</c> is called for every log entry (trace message) <c>LogEntry</c>. Here the log entry typically gets written to the output. <c>PidMappings</c> is the translations produced by the reader process. <c>EndHFun</c> is called when all reader processes have terminated.</p>
66
<p>The standard reader process is implemented in the module <c>inviso_lfm_tpreader</c> (trace port reader). It understands Erlang linked in trace-port driver generated trace-logs and <c>inviso_rt_meta</c> generated trace information files.</p>
72
<title>Writing Your Own Reader Process</title>
74
<p>Writing a reader process is not that difficult. It must:</p>
76
<item>Export an init-like function accepting two arguments, pid of the output process and the <c>LogFiles</c> component. <c>LogFiles</c> is actually only used by the reader processes, making it possible to redefine <c>LogFiles</c> if implementing an own reader process.</item>
78
<item>Respond to <c>{get_next_entry, OutputPid}</c> messages with <c>{next_entry, self(), PidMappings, NowTimeStamp, Term}</c> or <c>{next_entry, self(), {error,Reason}}</c>.</item>
80
<item>Terminate normally when no more log entries are available.</item>
82
<item>Terminate on an incoming EXIT-signal from <c>OutputPid</c>.</item>
85
<p>The reader process must of course understand the format of a logfile written by the runtime component.</p>
89
<aname>Lennart Öhman</aname>
90
<email>support@erlang.ericsson.se</email>
b'\\ No newline at end of file'