Flatstore Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview

              1.1.1. Rotating Log Files

        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. flush (integer)
              1.3.2. delimiter (char)
              1.3.3. suffix (string)
              1.3.4. prefix (string)
              1.3.5. single_file (integer)

        1.4. Exported Functions
        1.5. Exported MI Functions

              1.5.1. flat_rotate

   2. Developer Guide
   3. Contributors

        3.1. By Commit Statistics
        3.2. By Commit Activity

   4. Documentation

        4.1. Contributors

   List of Tables

   3.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   3.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set “flush” parameter
   1.2. Set “delimiter” parameter
   1.3. Set “suffix” parameter
   1.4. Set “prefix” parameter
   1.5. Set “single_file” parameter

Chapter 1. Admin Guide

1.1. Overview

   Flatstore is one of so-called OpenSIPS 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.

   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.

   The format of the files produced by this module is plain text.
   Each line consists of several fields, fields are separated by
   default by the | 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.

   The acc module can be configured to use flatstore module as
   database backend using the db_url_parameter:
modparam("acc", "db_url", "flatstore:/var/log/acc")

   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
   OpenSIPS processes must have permissions to create files in
   that directory.

   Name of files in that directory will follow the following
   pattern:
<prefix><table_name>[_<process_name>]<suffix>

   For example, without setting any module parameter, the entries
   writen by OpenSIPS 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 OpenSIPS 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 OpenSIPS
   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.
   Alternatively, you can use the single_file parameter, and all
   processes will dump the data into the same file. Note that this
   will induce some latency.

1.1.1. Rotating Log Files

   There is a new OpenSIPS MI (management interface) command
   called flat_rotate. When OpenSIPS 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:
     * Rename the files that you want to rotate:
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
...

       Note that at this point OpenSIPS will still be writing all
       data into the renamed files.
     * Send OpenSIPS the MI command to close and reopen the
       renamed files. For example, using FIFO:
opensips-cli -x mi flat_rotate

       This will force OpenSIPS to close the renamed files and
       open new ones with original names, such as acc_1.log. New
       files will be open at the point when OpenSIPS 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.
       Note that the suffix and prefix parameters are re-evaluated
       each time the flat_rotate command is issued. Therefore,
       after a rotate command, it is possible to open a different
       file than previous one.
     * Move the renamed files somewhere else and process them.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * No dependencies on other OpenSIPS modules.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * None.

1.3. Exported Parameters

1.3.1. flush (integer)

   Enable or disable flushing after each write.

   Default value is 1.

   Example 1.1. Set “flush” parameter
...
modparam("db_flatstore", "flush", 0)
...

1.3.2. delimiter (char)

   Delimiter used to separate the values.

   Default value is '|'.

   Example 1.2. Set “delimiter” parameter
...
modparam("db_flatstore", "delimiter", ";")
...

1.3.3. suffix (string)

   The suffix appended to the table name. Can be a pseudo
   variable.

   Default value is ".log".

   Example 1.3. Set “suffix” parameter
...
modparam("db_flatstore", "suffix", "$time(%H)")
...

1.3.4. prefix (string)

   The table name prefix. Can be a pseudo variable.

   Defaul value is none.

   Example 1.4. Set “prefix” parameter
...
modparam("db_flatstore", "prefix", "$time(%H)")
...

1.3.5. single_file (integer)

   Specifies if all the processes should dump the data into a
   single file.

   Default value is 0.

   Example 1.5. Set “single_file” parameter
...
modparam("db_flatstore", "single_file", 1)
...

1.4. Exported Functions

   There are no function exported to routing script.

1.5. Exported MI Functions

1.5.1.  flat_rotate

   It changes the name of the files where it is written.

   Name: flat_rotate

   Parameters: none

   MI FIFO Command Format:
                opensips-cli -x mi flat_rotate

Chapter 2. Developer Guide

   The module implements the DB API.

Chapter 3. Contributors

3.1. By Commit Statistics

   Table 3.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Bogdan-Andrei Iancu (@bogdan-iancu) 35 26 557 230
   2. Razvan Crainea (@razvancrainea) 17 10 481 99
   3. Jan Janak (@janakj) 16 4 1232 20
   4. Liviu Chircu (@liviuchircu) 15 12 84 94
   5. Daniel-Constantin Mierla (@miconda) 12 10 60 40
   6. Vlad Patrascu (@rvlad-patrascu) 6 4 34 41
   7. Henning Westerholt (@henningw) 6 4 24 35
   8. Elena-Ramona Modroiu 4 2 23 1
   9. Maksym Sobolyev (@sobomax) 4 2 4 3
   10. Andrei Pelinescu-Onciul 3 1 29 3

   All remaining contributors: Konstantin Bokarius, Razvan
   Pistolea, Peter Lemenkov (@lemenkov), Edson Gellert Schubert.

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

3.2. By Commit Activity

   Table 3.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Liviu Chircu (@liviuchircu)         Mar 2014 - May 2024
   2.  Maksym Sobolyev (@sobomax)          Feb 2017 - Feb 2023
   3.  Razvan Crainea (@razvancrainea)     Sep 2011 - Sep 2019
   4.  Bogdan-Andrei Iancu (@bogdan-iancu) Oct 2005 - Apr 2019
   5.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   6.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   7.  Razvan Pistolea                     Jul 2009 - Jul 2009
   8.  Daniel-Constantin Mierla (@miconda) Nov 2006 - Mar 2008
   9.  Konstantin Bokarius                 Mar 2008 - Mar 2008
   10. Edson Gellert Schubert              Feb 2008 - Feb 2008

   All remaining contributors: Henning Westerholt (@henningw),
   Elena-Ramona Modroiu, Andrei Pelinescu-Onciul, Jan Janak
   (@janakj).

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 4. Documentation

4.1. Contributors

   Last edited by: Razvan Crainea (@razvancrainea), Peter Lemenkov
   (@lemenkov), Liviu Chircu (@liviuchircu), Vlad Patrascu
   (@rvlad-patrascu), Bogdan-Andrei Iancu (@bogdan-iancu),
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert, Henning Westerholt (@henningw), Elena-Ramona
   Modroiu.

   Documentation Copyrights:

   Copyright © 2004-2005 FhG FOKUS
