← Back to branch summary

~ubuntu-branches/ubuntu/maverick/lire/maverick

« back to all changes in this revision

Viewing changes to doc/dev-manual/ch03.html

  • Committer: Bazaar Package Importer
  • Author(s): Joost van Baal
  • Date: 2006-11-02 15:30:00 UTC
  • mto: This revision was merged to the branch mainline in revision 4.
  • Revision ID: james.westby@ubuntu.com-20061102153000-343pa15n0rp58m1b
Tags: upstream-2.0.2
Import upstream version 2.0.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/dev-manual/ch03.html
1
 
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�3.�Writing a DLF Schema</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="pt02.html" title="Part�II.�Using the Lire Framework"><link rel="previous" href="ch02s07.html" title="DLF Converter API"><link rel="next" href="ch04.html" title="Chapter�4.�Writing a New DLF Analyser"></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">Chapter�3.�Writing a DLF Schema</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s07.html">Prev</a>�</td><th width="60%" align="center">Part�II.�Using the Lire Framework</th><td width="20%" align="right">�<a accesskey="n" href="ch04.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chap:writing-dlf-schema"></a>Chapter�3.�Writing a DLF Schema</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ch03.html#sect:ftpproto-schema">Designing the ftpproto schema</a></span></dt><dd><dl><dt><span class="section"><a href="ch03.html#id2504501">Creating The Schema File</a></span></dt><dt><span class="section"><a href="ch03.html#id2504609">Adding the Schema's Description</a></span></dt><dt><span class="section"><a href="ch03.html#id2504657">Defining the Schema's Fields</a></span></dt><dt><span class="section"><a href="ch03.html#schema-installation">Installing The Schema</a></span></dt></dl></dd></dl></div><p>If you want to develop a DLF converter for an application
 
1
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�3.�Writing a DLF Schema</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="pt02.html" title="Part�II.�Using the Lire Framework"><link rel="prev" href="ch02s07.html" title="DLF Converter API"><link rel="next" href="ch04.html" title="Chapter�4.�Writing a New DLF Analyser"></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">Chapter�3.�Writing a DLF Schema</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s07.html">Prev</a>�</td><th width="60%" align="center">Part�II.�Using the <span class="application">Lire</span> Framework</th><td width="20%" align="right">�<a accesskey="n" href="ch04.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chap:writing-dlf-schema"></a>Chapter�3.�Writing a DLF Schema</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ch03.html#sect:ftpproto-schema">Designing the <span class="type">ftpproto</span> schema</a></span></dt><dd><dl><dt><span class="section"><a href="ch03.html#id2518877">Creating The Schema File</a></span></dt><dt><span class="section"><a href="ch03.html#id2518985">Adding the Schema's Description</a></span></dt><dt><span class="section"><a href="ch03.html#id2519033">Defining the Schema's Fields</a></span></dt><dt><span class="section"><a href="ch03.html#schema-installation">Installing The Schema</a></span></dt></dl></dd></dl></div><p>If you want to develop a DLF converter for an application
2
2
        whose logging data model isn't adequately represented by 
3
3
        one of the existing DLF schema, you'll need to develop a new
4
4
        one.
7
7
        table, where each log record is represented by a table row.
8
8
        Each log record in the same DLF schema shares the same
9
9
        fields.
10
 
      </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect:ftpproto-schema"></a>Designing the <span class="type">ftpproto</span> schema</h2></div></div><div></div></div><p>In this chapter, we will create a new schema for logging
 
10
      </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect:ftpproto-schema"></a>Designing the <span class="type">ftpproto</span> schema</h2></div></div></div><p>In this chapter, we will create a new schema for logging
11
11
          of FTP session. That DLF schema could serve for an improved
12
12
          DLF converter for log files generated by  <span class="productname">Microsoft Internet Information Server</span>&#8482;. <span class="application">Lire</span>
13
13
          currently has a DLF converter for these log files but the
35
35
          standard FTP schema. It a session identifier, the command
36
36
          executed, as well as the result code of the action. Our new
37
37
          schema should be able to represent these things.
38
 
        </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2504501"></a>Creating The Schema File</h3></div></div><div></div></div><p>To create a DLF schema, you have to create a XML file
 
38
        </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2518877"></a>Creating The Schema File</h3></div></div></div><p>To create a DLF schema, you have to create a XML file
39
39
            named after your schema identifier:
40
 
            <tt class="filename">ftpproto.xml</tt>. Schema name should be
 
40
            <code class="filename">ftpproto.xml</code>. Schema name should be
41
41
            made of alphanumeric characters. This schema identifier is
42
42
            case sensitive. You schema identifer shouldn't contains
43
 
            hyphens (<tt class="literal">-</tt>) or underscore characters
44
 
            (<tt class="literal">_</tt>). (The hyphen is used for a special
 
43
            hyphens (<code class="literal">-</code>) or underscore characters
 
44
            (<code class="literal">_</code>). (The hyphen is used for a special
45
45
            purpose).
46
46
          </p><p>All DLF schemas starts and ends the same way:
47
47
            </p><pre class="programlisting">
52
52
  "http://www.logreport.org/LDSML/1.1/ldsml.dtd"&gt;
53
53
&lt;lire:dlf-schema xmlns:lire="http://www.logreport.org/LDSML/"
54
54
 
55
 
              superservice="<i class="replaceable"><tt>ftpproto</tt></i>"
56
 
              timestamp="<i class="replaceable"><tt>time</tt></i>"
 
55
              superservice="<em class="replaceable"><code>ftpproto</code></em>"
 
56
              timestamp="<em class="replaceable"><code>time</code></em>"
57
57
 
58
58
              &gt;
59
59
&lt;!-- Other elements will go here --&gt;
64
64
            The first lines contains the usual XML declaration and
65
65
            DOCTYPE declarations, you'll find in many XML documents.
66
66
            The real stuff starts at the
67
 
            <tt class="sgmltag-element">lire:dlf-schema</tt>. What is important for
68
 
            your schema are the value of the <tt class="sgmltag-attribute">superservice</tt> and <tt class="sgmltag-attribute">timestamp</tt> attributes. The
 
67
            <code class="sgmltag-element">lire:dlf-schema</code>. What is important for
 
68
            your schema are the value of the <code class="sgmltag-attribute">superservice</code> and <code class="sgmltag-attribute">timestamp</code> attributes. The
69
69
            first one contains your schema identifier. It is called
70
70
            &#8220;<span class="quote">superservice</span>&#8221; for historical reasons. The
71
71
            other one should contains the name of the field which
72
72
            order the record by their event type. (See <a href="ch03.html#sect:schema-field-type" title="The Field Types">the section called &#8220;The Field Types&#8221;</a> for more information.)
73
73
          </p><p>The last line in the above excerpt would be the last
74
74
            thing in the file and closes the
75
 
            <tt class="sgmltag-element">lire:dlf-schema</tt> element.
76
 
          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2504609"></a>Adding the Schema's Description</h3></div></div><div></div></div><p>The next things that goes into the schema file are the
 
75
            <code class="sgmltag-element">lire:dlf-schema</code> element.
 
76
          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2518985"></a>Adding the Schema's Description</h3></div></div></div><p>The next things that goes into the schema file are the
77
77
            schema's title and description. Both are intended for
78
78
            developers to read and should be informative of the scope
79
79
            of the schema:
96
96
 
97
97
 
98
98
            </pre><p>
99
 
          </p><p>The content of the <tt class="sgmltag-element">lire:description</tt>
 
99
          </p><p>The content of the <code class="sgmltag-element">lire:description</code>
100
100
            elements are DocBook elements. If you don't know DocBook,
101
101
            you just need to know that paragraphs are delimited using the
102
 
            <tt class="sgmltag-element">para</tt> elements.
103
 
          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2504657"></a>Defining the Schema's Fields</h3></div></div><div></div></div><p>The only remaining things in the schema definitions
 
102
            <code class="sgmltag-element">para</code> elements.
 
103
          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2519033"></a>Defining the Schema's Fields</h3></div></div></div><p>The only remaining things in the schema definitions
104
104
            are the field specifications. Here is the definition of
105
105
            the first one:
106
106
            </p><pre class="programlisting">
115
115
 
116
116
            </pre><p>
117
117
          </p><p>As you can see, the fields are defined using the
118
 
            <tt class="sgmltag-element">lire:field</tt> element which has three
 
118
            <code class="sgmltag-element">lire:field</code> element which has three
119
119
            attributes:
120
120
            </p><div class="variablelist"><dl><dt><span class="term">name</span></dt><dd><p>This attribute contains the name of the field.
121
121
                  This name should contains only alphanumeric
128
128
                    but descriptive.
129
129
                  </p></dd></dl></div><p>
130
130
          </p><p>The field's description is held in the
131
 
            <tt class="sgmltag-element">lire:description</tt> element which contains
 
131
            <code class="sgmltag-element">lire:description</code> element which contains
132
132
            DocBook markup. The field's description should be
133
133
            descriptive enough so that someone implementing a DLF
134
134
            converter for this schema knows what goes where.
135
 
          </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect:schema-field-type"></a>The Field Types</h4></div></div><div></div></div><p>The main types available for fields are:
 
135
          </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect:schema-field-type"></a>The Field Types</h4></div></div></div><p>The main types available for fields are:
136
136
 
137
137
              </p><div class="variablelist"><dl><dt><span class="term">timestamp</span></dt><dd><p>This should be use for field which contains
138
138
                      a value to indicate a particular point in time.
141
141
                      January 1st 1970.
142
142
                    </p><p>Each DLF schema must contains at least one
143
143
                      field of this kind and its name should be in the
144
 
                      <tt class="sgmltag-element">lire:dlf-schema</tt>'s <tt class="sgmltag-attribute">timestamp</tt>
 
144
                      <code class="sgmltag-element">lire:dlf-schema</code>'s <code class="sgmltag-attribute">timestamp</code>
145
145
                      attribute.
146
146
                    </p></dd><dt><span class="term">hostname</span></dt><dd><p>This type should be used for fields which
147
147
                      contains an hostname <span class="emphasis"><em>or</em></span> IP
225
225
  &lt;/lire:field&gt;
226
226
 
227
227
              </pre><p>
228
 
            </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="schema-installation"></a>Installing The Schema</h3></div></div><div></div></div><p>Making available the new schema to the <span class="application">Lire</span>
 
228
            </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="schema-installation"></a>Installing The Schema</h3></div></div></div><p>Making available the new schema to the <span class="application">Lire</span>
229
229
            framework is pretty easy: just copy the file to one of the
230
 
            directories set in the <tt class="varname">lr_schemas_path</tt>
 
230
            directories set in the <code class="varname">lr_schemas_path</code>
231
231
            configuration variable. By default, this variable contains
232
232
            the directories
233
 
            <tt class="filename"><i class="replaceable"><tt>datadir</tt></i>/lire/schemas</tt> 
 
233
            <code class="filename"><em class="replaceable"><code>datadir</code></em>/lire/schemas</code> 
234
234
            and
235
 
            <tt class="filename"><i class="replaceable"><tt>HOME</tt></i>/.lire/schemas</tt>. 
 
235
            <code class="filename"><em class="replaceable"><code>HOME</code></em>/.lire/schemas</code>. 
236
236
            Like all other configuration variables, its value can be
237
 
            changed using the <span><b class="command">lire</b></span> tool.
 
237
            changed using the <span><strong class="command">lire</strong></span> tool.
238
238
          </p><p>Since we want our schema to be available for other
239
239
            users as well, we will install it in the system directory:
240
240
            </p><pre class="screen">
243
243
 
244
244
            </pre><p>
245
245
 
246
 
            (In this case, <span class="application">Lire</span> was installed under <tt class="filename">/usr/local</tt>.
 
246
            (In this case, <span class="application">Lire</span> was installed under <code class="filename">/usr/local</code>.
247
247
          </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s07.html">Prev</a>�</td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right">�<a accesskey="n" href="ch04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DLF Converter API�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Chapter�4.�Writing a New DLF Analyser</td></tr></table></div></body></html>