====== Datastore auditing ======

BPS2 has a comprehensive audit log for all relevant tables. This allows to track down issues of data consistency. 

Auditing is enabled by default after datastore creation with the [[createdb|Datastore creation wizard]]. Same is true for new tables that get created during a version update.

Since auditing adds substantial amounts of data and slows down database server performance in high traffic environments, it is wise to regulary purge auditing records that are outdated, or even disable auditing completely while auditing is not needed. The [[#Audit control script]] described below can be used for such tasks.


===== Audit tables and views =====

The master table of all audited operations is [[dbtables#t_audits]].

The table lists all operation in strictly chronological order. Besides real data changes such as insert, update and delete, this table also logs when auditing of tables gets enabled and disabled.

For insert, update and delete opertations in data tables, corresponding slave audit tables [[dbtables#ta_*]] exist where every change in the table is traced in details. For more cenvenience you may however want to use the views prefixed with [[dbviews#va_*]] where the master and slave audit tables are joined.

===== Audit control script =====

The audit control script can be started from the command line in the BPS installation directory. Use this command to show usage:

    bps audit -h

This will show the usage of the script, for example as:

    C:\Programme\BPS2>bps audit -h
    SYNOPSYS
    
        bps audit CONNECTSTRING [AUDITNAME]... [OPTION]...
    
    DESCRIPTION
    
        This script allows to control the audit feature in the BPS datastore.
    
    NOTES
    
        - Enter the CONNECTSTRING for the bps owner as userid/pincode@connection.
    
        - Enter audit names as AUDITNAME arguments.
          The audit name is the tablename without the 't_' prefix.
    
        EXAMPLES
    
          Show status of actors and users:
    
            bps audit 0/1234@pgprod actors users -s
    
          Disable all auditing:
    
            audit 0/1234@pgprod -d -a
    
    
    OPTIONS
    
        -a, --all
            Execute operation for all audit names.
    
        -d, --disable
            Disable auditing.
    
        -e, --enable
            Enable auditing.
    
        -h, --help
            Show help (this).
    
        -s, --status
            Show current status.
    
        -p DAYS, --purge=DAYS
            Purge audit records older than the number of DAYS.
    
    C:\Programme\BPS2>

Note that the audit control script needs to be run by the application owner, otherwise there might be insufficient database privileges to complete some operations.

Here are samples of some common tasks:


==== Purge audit records older that 60 days ====

    C:\Programme\BPS2>bps audit 0/1234@oraprod -a -p 60
    actors                  2327 records purged
    artattributes             45 records purged
    articleattributes        123 records purged
    articlebarcodes           16 records purged
    .....
    
    C:\Programme\BPS2>

==== Disable all auditing ====

    C:\Programme\BPS2>bps audit 0/1234@oraprod -a -d
    actors            disabled
    artattributes     disabled
    articleattributes disabled
    articlebarcodes   disabled
    articleclasses    disabled
    .....
    
    C:\Programme\BPS2>

==== Enable all auditing ====

    C:\Programme\BPS2>bps audit 0/1234@oraprod -a -e
    actors            enabled
    artattributes     enabled
    articleattributes enabled
    articlebarcodes   enabled
    articleclasses    enabled
    .....
    
    C:\Programme\BPS2>