1
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The Meta-Data Methods</title><meta name="generator" content="DocBook XSL Stylesheets V1.64.1"><link rel="home" href="index.html" title="Lire Developer's Manual"><link rel="up" href="ch02.html" title="Chapter�2.�Writing a New DLF Converter"><link rel="previous" href="ch02s04.html" title="Adding a Constructor"><link rel="next" href="ch02s06.html" title="Registering Your DLF Converter with the Lire Framework"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">The Meta-Data Methods</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s04.html">Prev</a>�</td><th width="60%" align="center">Chapter�2.�Writing a New DLF Converter</th><td width="20%" align="right">�<a accesskey="n" href="ch02s06.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2503508"></a>The Meta-Data Methods</h2></div></div><div></div></div><p>The <span class="interface">Lire::DlfConverter</span> interface
1
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The Meta-Data Methods</title><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"><link rel="start" href="index.html" title="Lire Developer's Manual"><link rel="up" href="ch02.html" title="Chapter�2.�Writing a New DLF Converter"><link rel="prev" href="ch02s04.html" title="Adding a Constructor"><link rel="next" href="ch02s06.html" title="Registering Your DLF Converter with the Lire Framework"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">The Meta-Data Methods</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s04.html">Prev</a>�</td><th width="60%" align="center">Chapter�2.�Writing a New DLF Converter</th><td width="20%" align="right">�<a accesskey="n" href="ch02s06.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2517888"></a>The Meta-Data Methods</h2></div></div></div><p>The <span class="interface">Lire::DlfConverter</span> interface
2
2
requires two kinds of methods. First, it requires methods
3
3
which provide information to the framework on your
4
4
converter. Second, it requires methods which will actually
5
5
implement the conversion process. It this the format that
6
6
this section documents.
7
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2503528"></a>The DLF Converter Name</h3></div></div><div></div></div><p>The method <tt class="methodname">name()</tt> should
7
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2517909"></a>The DLF Converter Name</h3></div></div></div><p>The method <code class="methodname">name()</code> should
8
8
returns the name of our DLF converter. It is this name
9
that is passed to the <span><b class="command">lr_log2report</b></span>
9
that is passed to the <span><strong class="command">lr_log2report</strong></span>
10
10
command. This name must be unique among all the converters
11
11
registered and it should be restricted to alphanumerical
12
12
characters (hyphens, period and underscores can also be
14
14
</p><p>We will name our converter
15
<tt class="literal">common_syslog</tt>:
15
<code class="literal">common_syslog</code>:
16
16
</p><pre class="programlisting">
24
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2503573"></a>Providing Information To Users</h3></div></div><div></div></div><p>The next two required methods are used to give more
24
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2517953"></a>Providing Information To Users</h3></div></div></div><p>The next two required methods are used to give more
25
25
verbose information on your converter to the users. The
26
converter's <tt class="methodname">title()</tt> and
27
<tt class="methodname">description()</tt> can be use to
26
converter's <code class="methodname">title()</code> and
27
<code class="methodname">description()</code> can be use to
28
28
display information about your converter from the user
29
29
interface or to generate documentation.
30
</p><p>The <tt class="methodname">title()</tt> should simply
30
</p><p>The <code class="methodname">title()</code> should simply
32
32
</p><pre class="programlisting">
104
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2503738"></a>The Conversion Methods</h3></div></div><div></div></div><p>The actual conversion process is handled through three
105
methods: <tt class="methodname">init_dlf_converter</tt>,
106
<tt class="methodname">finish_conversion()</tt> and either
107
<tt class="methodname">process_log_file()</tt> or
108
<tt class="methodname">process_log_line()</tt> depending on
104
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2518118"></a>The Conversion Methods</h3></div></div></div><p>The actual conversion process is handled through three
105
methods: <code class="methodname">init_dlf_converter</code>,
106
<code class="methodname">finish_conversion()</code> and either
107
<code class="methodname">process_log_file()</code> or
108
<code class="methodname">process_log_line()</code> depending on
109
109
the conversion mode (as determined by
110
<tt class="methodname">handle_log_lines()</tt>'s return value.
111
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2503769"></a>Conversion Initialization</h4></div></div><div></div></div><p>The method
112
<tt class="methodname">init_dlf_converter()</tt> will be
110
<code class="methodname">handle_log_lines()</code>'s return value.
111
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2518149"></a>Conversion Initialization</h4></div></div></div><p>The method
112
<code class="methodname">init_dlf_converter()</code> will be
113
113
called once before the log file is processed. It should
114
114
be use to initialize the state of your converter. Since
115
115
our DLF Converter doesn't need any initialization and doesn't
127
</p><p>The <tt class="varname">$process</tt> parameter which is
127
</p><p>The <code class="varname">$process</code> parameter which is
128
128
passed to all the processing methods is an instance of
129
<tt class="classname">Lire::DlfConverterProcess</tt>. This
129
<code class="classname">Lire::DlfConverterProcess</code>. This
130
130
is the object which is driving the conversion process
131
131
and it defines several methods which you will use in the
132
132
actual conversion process.
133
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2503814"></a>Conversion Finalization</h4></div></div><div></div></div><p>The method
134
<tt class="methodname">finish_conversion()</tt> will be
133
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2518194"></a>Conversion Finalization</h4></div></div></div><p>The method
134
<code class="methodname">finish_conversion()</code> will be
135
135
called once after the log file has been completely
136
136
processed. This method will be mostly of use to stateful
137
137
converter, that is DLF converters which generates DLF
150
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2503843"></a>The DLF Conversion Process</h4></div></div><div></div></div><p>Whether you are using the file-oriented or
150
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2518223"></a>The DLF Conversion Process</h4></div></div></div><p>Whether you are using the file-oriented or
151
151
line-oriented conversion mode, the principles are the
152
152
same. You extract information from the log file and
153
153
creates DLF records from it. Your DLF converter
154
154
communicates with the framework by calling methods on
155
the <tt class="classname">Lire::DlfConverterProcess</tt>
155
the <code class="classname">Lire::DlfConverterProcess</code>
156
156
object which is passed as parameter to your methods.
157
157
</p><p>Here is the complete code of our conversion method:
158
158
</p><pre class="programlisting">
187
187
</p><p>The first thing that should be noted is that in the
188
188
line-oriented conversion mode, the method
189
<tt class="methodname">process_log_line()</tt> will be
189
<code class="methodname">process_log_line()</code> will be
190
190
called once for each line in the log file.
191
191
</p><p>Secondly, the actual parsing of the line is done
192
using two functions: <tt class="function">parse_common</tt>
193
and <tt class="classname">Lire::Syslog</tt>'s
194
<tt class="methodname">parse</tt>. These methods simply
192
using two functions: <code class="function">parse_common</code>
193
and <code class="classname">Lire::Syslog</code>'s
194
<code class="methodname">parse</code>. These methods simply
195
195
uses regular expressions to extract the appropriate
196
196
information from the line and put it in an hash
197
197
reference. What is important is that these methods
198
198
already uses as key names the schema's field names.
199
199
</p><p>Finally, you can see that there are four different
200
methods used on the <tt class="varname">$process</tt> object to
200
methods used on the <code class="varname">$process</code> object to
201
201
report different kind of information:
203
203
</p><div class="variablelist"><dl><dt><span class="term">Reporting Error</span></dt><dd><p>The example uses the
204
<tt class="function">eval</tt> statement to trap
204
<code class="function">eval</code> statement to trap
205
205
errors during the syslog record parsing. If the
206
206
line cannot be parsed as a valid syslog record,
207
207
it is an error and it is reported through the
208
<tt class="methodname">error()</tt> method. The
208
<code class="methodname">error()</code> method. The
209
209
first parameter is the error message and the
210
210
second one is the line to which the error is
211
211
associated. This last parameter is optional.
212
212
</p></dd><dt><span class="term">Ignoring Information</span></dt><dd><p>When the syslog event doesn't come from the
213
<span><b class="command">httpd</b></span> process, we ignore the
213
<span><strong class="command">httpd</strong></span> process, we ignore the
214
214
line. Ignored line are reported to the framework
216
<tt class="methodname">ignore_log_line()</tt>
216
<code class="methodname">ignore_log_line()</code>
217
217
method. The first parameter is the line which is
218
218
ignored. The second optional parameter gives the
219
219
reason why the line was ignored.
220
220
</p></dd><dt><span class="term">Creating DLF Records</span></dt><dd><p>Finally, DLF records are created by using
221
the <tt class="methodname">write_dlf()</tt> method.
221
the <code class="methodname">write_dlf()</code> method.
222
222
Its first parameter is the schema to which the
223
223
DLF record complies. This schema must be one
224
224
that is listed by your converter's
225
<tt class="methodname">schemas()</tt> method. The
225
<code class="methodname">schemas()</code> method. The
226
226
second parameter is the DLF data contained in an
227
227
hash reference. The DLF record will be created
228
228
by taking for each field in the schema the value
229
229
under the same name in the hash. (Since in the
230
230
<span class="type">syslog</span> schema, the field which
231
231
contains the actual log message is called
232
<i class="structfield"><tt>message</tt></i>, this is the
232
<em class="structfield"><code>message</code></em>, this is the
234
234
are assigning the <span class="property">content</span>
235
235
value to the <span class="property">message</span> key.)
237
237
or fields whose value is
238
<tt class="literal">undef</tt> will contains the
239
special <tt class="literal">LR_NA</tt> missing value
238
<code class="literal">undef</code> will contains the
239
special <code class="literal">LR_NA</code> missing value
240
240
marker. Keys in the hash that don't map to a
241
241
schema's field are simply ignored.
242
242
</p><p>In our example, we distinguish between the
added
removed
doc/dev-manual/ch02s05.html
