[SR-Dev] git:janakj/flatstore: - improved documentation system
Jan Janak
jan at iptel.org
Sun Feb 15 18:56:45 CET 2009
Module: sip-router
Branch: janakj/flatstore
Commit: 5e3087888e64fc705a64b10aff378fc580a31cf7
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=5e3087888e64fc705a64b10aff378fc580a31cf7
Author: Jan Janak <jan at iptel.org>
Committer: Jan Janak <jan at iptel.org>
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>
+ <email>jan at iptel.org</email>
+ </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>
+<table_name>_<process_name>.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>
More information about the sr-dev
mailing list