[SR-Dev] git:janakj/flatstore: - improved documentation system

Module: sip-router Branch: janakj/flatstore Commit: 5e3087888e64fc705a64b10aff378fc580a31cf7 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=5e30878… Author: Jan Janak &lt;jan(a)iptel.org&gt; Committer: Jan Janak &lt;jan(a)iptel.org&gt; Date: Sat Jul 23 23:21:36 2005 +0000 - improved documentation system - documentation makefiles - proper documentation dependency tracking in makefiles - XML-based dialect of docbook used with xi:include inclusions --- modules/db_flatstore/doc/Makefile | 29 +++++++ modules/db_flatstore/doc/flatstore.xml | 134 ++++++++++++++++++++++++++++++++ modules/db_flatstore/doc/functions.xml | 17 ++++ modules/db_flatstore/doc/params.xml | 26 ++++++ 4 files changed, 206 insertions(+), 0 deletions(-) diff --git a/modules/db_flatstore/doc/Makefile b/modules/db_flatstore/doc/Makefile new file mode 100644 index 0000000..28b668f --- /dev/null +++ b/modules/db_flatstore/doc/Makefile @@ -0,0 +1,29 @@ +# +# The list of documents to build (without extensions) +# +DOCUMENTS = flatstore + +# +# The root directory containing Makefile.doc +# +ROOT_DIR=../../.. + +# +# Validate docbook documents before generating output +# (may be slow) +# +#VALIDATE=1 + +# +# You can override the stylesheet used to generate +# xhtml documents here +# +#XHTML_XSL=$(ROOT_DIR)/doc/stylesheets/xhtml.xsl + +# +# You can override the stylesheet used to generate +# plain text documents here +# +#TXT_XSL=$(XHTML_XSL) + +include $(ROOT_DIR)/Makefile.doc diff --git a/modules/db_flatstore/doc/flatstore.xml b/modules/db_flatstore/doc/flatstore.xml new file mode 100644 index 0000000..263f28a --- /dev/null +++ b/modules/db_flatstore/doc/flatstore.xml @@ -0,0 +1,134 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN" + "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd"> + +<section id="flatstore" xmlns:xi="http://www.w3.org/2001/XInclude"> + <sectioninfo> + <authorgroup> + <author> + <firstname>Jan</firstname> + <surname>Janak</surname> + <affiliation><orgname>FhG FOKUS</orgname></affiliation> + &lt;email&gt;jan(a)iptel.org&lt;/email&gt; + </author> + </authorgroup> + <copyright> + <year>2004</year> + <year>2005</year> + <holder>FhG FOKUS</holder> + </copyright> + <revhistory> + <revision> + <revnumber>$Revision$</revnumber> + <date>$Date$</date> + </revision> + </revhistory> + </sectioninfo> + + <title>Flatstore Module</title> + + <section id="overview"> + <title>Overview</title> + <para> + Flatstore is one of so-called SER database modules. It does not + export any functions executable from the configuration scripts, but + it exports a subset of functions from the database API and thus + other module can use it instead of, for example, mysql module. + </para> + <para> + The module does not export all functions of the database API, it + supports only one function, insert. The module is limited but very + fast. It is especially suitable for storing accounting information + on sites with extremely high traffic. If MySQL is too slow or if + you get a huge amount of accounting data then you can consider + using this module. Note that the acc module is the only module that + was tested with flastore. + </para> + <para> + The format of the files produced by this module is plain text. Each + line consists of several fields, fields are separated by | + character. New information is always appended at the end of the + file, searching, deleting and updating of existing data is not + supported by the module. + </para> + <para> + The acc module can be configured to use flatstore module as + database backend using the db_url_parameter: + </para> + <programlisting> +modparam("acc", "db_url", "flatstore:/var/log/acc") + </programlisting> + <para> + This configuration options tells acc module that it should use the + flatstore module and the flatstore module should create all files + in /var/log/acc directory. The directory must exist and SER + processes must have permissions to create files in that directory. + </para> + <para> + Name of files in that directory will follow the following pattern: + </para> + <programlisting> +&lt;table_name&gt;_&lt;process_name&gt;.log + </programlisting> + <para> + For example, entries writen by SER process 8 into acc table would + be written in file acc_8.log. For each table there will be several + files, one file for every SER process that wrote some data into + that table. The main reason why there are several files for each + table is that it is much faster to have one file per process, + because it does not require any locking and thus SER processes will + not block each other. To get the complete data for a table you can + simply concatenate the contents of files with the same table name + but different process id. + </para> + <section id="rotating"> + <title>Rotating Log Files</title> + <para> + There is a new SER FIFO interface command called flat_rotate. + When SER receives the command then it will close and reopen all + files used by flatstore module. The rotation itself has to be + done by another application (such as logrotate). Follow these + steps to rotate files generated by flatstore module: + </para> + <itemizedlist> + <listitem> + <para> + Rename the files that you want to rotate: + <screen> +cd /var/log/acc +mv acc_1.log acc_1.log.20050605 +mv acc_2.log acc_2.log.20050605 +mv acc_4.log acc_3.log.20050605 +... + </screen> + Note that at this point SER will still be writing all + data into the renamed files. + </para> + </listitem> + <listitem> + <para> + Send SER the fifo command to close and reopen the + renamed files: + <screen> +serctl fifo flat_rotate + </screen> + This will force SER to close the renamed files and open + new ones with original names, such as + <filename>acc_1.log</filename>. New files will be open + at the point when SER has some data to write. It is + normal that the files will be not created immediately + if there is no traffic on the proxy server. + </para> + </listitem> + <listitem> + <para> + Move the renamed files somewhere else and process them. + </para> + </listitem> + </itemizedlist> + </section> + </section> + + <xi:include href="params.xml"/> + +</section> diff --git a/modules/db_flatstore/doc/functions.xml b/modules/db_flatstore/doc/functions.xml new file mode 100644 index 0000000..29dea48 --- /dev/null +++ b/modules/db_flatstore/doc/functions.xml @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN" + "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd"> + +<section id="flatstore.functions" xmlns:xi="http://www.w3.org/2001/XInclude"> + <sectioninfo> + <revhistory> + <revision> + <revnumber>$Revision$</revnumber> + <date>$Date$</date> + </revision> + </revhistory> + </sectioninfo> + + <title>Functions</title> + +</section> diff --git a/modules/db_flatstore/doc/params.xml b/modules/db_flatstore/doc/params.xml new file mode 100644 index 0000000..a6d838e --- /dev/null +++ b/modules/db_flatstore/doc/params.xml @@ -0,0 +1,26 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN" + "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd"> + +<section id="flatstore.functions" xmlns:xi="http://www.w3.org/2001/XInclude"> + <sectioninfo> + <revhistory> + <revision> + <revnumber>$Revision$</revnumber> + <date>$Date$</date> + </revision> + </revhistory> + </sectioninfo> + + <title>Parameters</title> + + <section id="flush"> + <title><varname>flush</varname> (integer)</title> + <para> + Enable or disable flushing after each write. + </para> + <para> + Default value is 1. + </para> + </section> +</section>