TimesTen Auditing Using ttaudit.java

TimesTen Auditing Using ttaudit.java Installation, Operation, and Configuration As of: TimesTen 11.2.2.6 and ttaudit 1.0.0.15 March, 2014 The ttaudit.java application is free, open source project software that is provided as a convenience to the customer without a warranty of any kind and without support. Licensing terms are here: https://oss.oracle.com/licenses/cddl Unlike the Oracle database, the Oracle TimesTen in-memory database does not have built-in auditing features. However, using TimesTen s event notification API, JMS/XLA (documented in the TimesTen Java User s Guide), an application called ttaudit.java has been developed to provide very detailed auditing. Information about all transactions that modify the database or update the data can be audited and saved. Normally, audit information is stored in an Oracle database, but it can be stored in a TimesTen database or in a flat file in the file system. As TimesTen supports very high write transaction throughput, a very large amount of audit data could be generated. The following events can be audited: INSERT, UPDATE, DELETE, all DDL (e.g. DROP TABLE, CREATE TABLE, ALTER TABLE), and materialized view updates. For INSERT, all columns that are inserted into the table can be saved if the fullinsertaudit option is used on the command line. For UPDATEs, the old value and new value of the columns are saved. For DELETE, the values of the columns in the primary key or unique index of the tables of the deleted row are saved. The following events cannot be audited, as they are not logged in TimesTen s logging system: SELECT, TRUNCATE TABLE, and operations to Temporary Tables. Note that JMS/XLA is an asynchronous API. The timestamp of the transaction will be the time that JMS/XLA read the transaction on the log file, unless the updated table has a timestamp column that is updated upon every UPDATE. At this point, we recommend that you go through the tutorial in the next section.

Getting Started Tutorial The sample session assumes that you installed the Quickstart when you installed the Oracle TimesTen software. It is also assumed that you know a few of the basics of the TimesTen database.. If you do not have an Oracle database, you can output ttaudit auditing information to a flat file. If you do wish to store auditing information to an Oracle database, it is also assumed that you have access to an Oracle database, 10.2.0.4 or later, you have permissions to create users and tables on it, and that you understand TNSNAMES connections. You must have an Oracle Sun Java Development Kit (JDK) installed as well. If you are not familiar with TimesTen, see: http://download.oracle.com/otn_hosted_doc/timesten/1122/quickstart/html/admin/db_ops.html 1) This tutorial assumes that you have installed TimesTen 11.2.2.x and a 64-bit Sun Java Development Kit (JDK) 1.6 or higher on 64-bit Linux. It is also assumed that you have a basic understanding of TimesTen. 2) Set an environment variable called $TT_HOME that points to the installation directory of TimesTen, e.g. export TT_HOME=/opt/TimesTen/tt1122 Also verify that your PATH environment variable is set to the TimesTen bin directory: export PATH=$TT_HOME/bin:$PATH 3) Open terminal windows on your Linux system. If you are on a GUI Linux workstation such as KDE or Gnome, at the menu at the top of the screen, select Applications -> Accessories -> Terminal. 4) Download the most recent ttaudit.jar file at : http://java.net/projects/ttaudit/downloads You can do this with a browser like Firefox. (On the Linux GUI screen, select Applications -> Internet -> Firefox (or whatever browser is available). Go to the URL http://java.net/projects/ttaudit/downloads. Select Save File. 5) Open a Linux terminal window. Find the place where you saved the ttaudit.jar file. Copy it to a directory of your choice. Extract the jar file with: cd [directory of your choice] jar xvf ttaudit.jar

cp src/scripts/* $PWD cp src/sql/* $PWD cp src/*xml $PWD 6) For this tutorial, we will use two TimesTen data stores, one for transactions, and one for storing audit information. In a production system, however, it is recommended than an Oracle database is used for audit information, as this data will quickly grow to a size larger than available memory. The next tutorial section uses an Oracle database. 7) cd $TT_HOME/info. Edit the sys.odbc.ini file. Notice that there is already a data store DSN defined in this file called [sampledb_1122] (or, depending on the TimesTen version you have installed, it could be sampledb_version. Do NOT select ampledbcs_1122.) We will use this DSN as the data store for transactions. Make sure you have the following in your sys.odbc.ini file. Note that the directory names in Driver and DataStore should probably not be changed. [sampledb_1122] Driver=/TIMESTEN_DIRECTORY/lib/libtten.so DataStore=/a_writable_directory /sampledb_1122 PermSize=40 TempSize=32 PLSQL=1 DatabaseCharacterSet=US7ASCII 8) We will now create another data store called sampleaudit_1122, with a client connection called sampleauditcs_1122. Copy the lines of sampledb_1122 in this file, then edit the file to make the following changes (in BOLD): [sampleaudit_1122] Driver=/writable_directory/libtten.so DataStore=/writable_directory /sampleaudit_1122 PermSize=100 TempSize=32 PLSQL=1 DatabaseCharacterSet=US7ASCII [sampleauditcs_1122] TTC_SERVER=localhost TTC_SERVER_DSN=sampleaudit_1122 You should now have two data stores defined in sys.odbc.ini, sampledb_1122 and sampleaudit_1122. Save changes to the file and exit.

9) Destroy any sampledb_1122 database that exists with: ttdestroy sampledb_1122 Ignore any data store not exists error. 10) cd $TT_HOME/quickstart/sample_scripts/createdb. Edit the file build_sampledb.sh; make sure that the data store name referenced throughout is sampledb_1122 (not sampledb_1121 or something else.) 11) Run./build_sampledb.sh. When prompted for an adm password, enter adm. When prompted for appuser, enter appuser. When prompted for xlauser, enter xlauser. 12) cd to your chosen ttaudit directory. Enter: ttisql sampledb_1122. As you are logged in as the instance administrator, and you did not specify a UID on the connection string, you are now logged in as the TimesTen superuser / instance administrator. Enter this command: grant all to xlauser; 13) Enter these commands in ttisql: disconnect; connect dsn=sampledb_1122;uid=xlauser;pwd=xlauser ; 14) For this tutorial, we will be saving auditing information to another TimesTen data store. (NOTE: If you wish to store auditing information in an Oracle database, you need to change the settings in the file runauditdemo.sh. Note the section of this file Oracle database for holding ttaudit data. ) In another terminal session, cd to your chosen ttaudit directory, and edit the file runauditdemo.sh. Change the value of TTJAVA_HOME to the directory where the bin directory of your Oracle Sun JDK resides. It is important that the java command run an Oracle Sun JVM and not the open source JVM that is shipped with Linux. If you do not know where the Oracle Sun JDK is installed, this command may help: find / -name javac -print 15) Again editing runauditdemo.sh, verify that the following environment variables are set as below: export TTAUDIT_HOME=your_chosen_ttAudit_directory export TTJAVA_HOME=path_to_your_Sun_JDK_directory export TTAUDIT_XLAURL="jdbc:timesten:direct:sampledb_1122" export TTAUDIT_XLADRIVER="com.timesten.jdbc.TimesTenDriver"

export TTAUDIT_XLAUID="ttaudit" export TTAUDIT_XLAPWD="timesten" export TTAUDIT_DBURL="jdbc:timesten:client:sampleauditCS_1122" export TTAUDIT_DBDRIVER="com.timesten.jdbc.TimesTenDriver" export TTAUDIT_DBUID="ttaudit" export TTAUDIT_DBPWD="timesten" Save changes and exit. 16) Edit the file jmsxla.xml. In the ConnectionString under the audit topic, verify that the line connectionstring = DSN=sampledb_1122. Save and exit. 17) Connect to TimesTen as below and enter the below command: ttisql connstr dsn=sampledb_1122;uid=xlauser;pwd=xlauser Command> @audittablesddltimesten.sql; Command> exit; You have now created the tables necessary for auditing. 18) We will now set up the data store to hold auditing information. ttisql connstr dsn=sampleaudit_1122 Command> @audittablesddltimesten.sql; Command> exit; Note: if you are using the Oracle database to store audit data, use the script audittablesddlauditdb.sql. 19) Run this command, and leave it running. cd to your chosen ttaudit directory chmod 755 runauditdemo.sh./runauditdemo.sh If you get a bad interpreter error message, do: dos2unix *sh, then try again. Every 5 seconds, you will see a got a UPDATE message. ttaudit updates a table called auditmonitor every 5 seconds to make sure the XLA bookmark is advancing. 20) In another terminal session, enter these commands: ttisql connstr dsn=sampledb_1122;uid=ttaudit;pwd=timesten

Command> autocommit 0; Command> insert into appuser.mytable values( Test0,0); Command> commit; 21) On the other terminal session from #19 above, you should now see several messages. Try updating the row you just inserted in ttisql: Command> update appuser.mytable set i = 10; Command> commit; Notice that on your other terminal there are messages indicating that the table has been updated. Note that the messages do not appear until you COMMIT the transaction. 22) In the same ttisql session: call ttlogholds; update appuser.mytable set i = 11; commit; call ttlogholds; Did you notice how the XLA bookmark s log hold ID (the number in the second column of the result set of ttlogholds) is bigger the second time you called ttlogholds? This means that the XLA bookmark is advancing, which is what you want to see. 23) You can create a new table, and it will automatically be picked up by the auditing program. Try this in ttisql: create table newtable (uuid_pk binary(4) not null primary key, update_user varchar(20)); Note that DDL is autocommited as it is in the Oracle database. Notice that the auditing application re-starts. insert into newtable values(0x0123, AUDITOR ); commit; 24) Now in another terminal session, let s connect to the other TimesTen data store and run a report of the transactions that were audited: ttisql connstr dsn=sampleaudit_1122;uid=ttaudit;pwd=timesten Command> @auditquery01.sql; ( NOTE: If you are using an Oracle database to store audit information, do the following: sqlplus ttaudit/timesten

SQL> @auditquery01oracle.sql; ) You will note that the fact that you issued a CREATE TABLE statement is shown 4 rows from the bottom of the result set. Note the last two rows of the result set: DB TRX NUM: 192093093.332 TRX PART NUM: 19 USER: AUDITOR DATE/TIME: 22-JUL-13 10.34.09.589000 PM TRX_TYPE: INSERT TABLE: XLAUSER.NEWTABLE PRIMARYKEY? Y COLUMN: UUID_PK OLD VALUE: NEW VALUE: 01230000 DB TRX NUM: 192093093.332 TRX PART NUM: 19 USER: AUDITOR DATE/TIME: 22-JUL-13 10.34.09.589000 PM TRX_TYPE: INSERT TABLE: XLAUSER.NEWTABLE PRIMARYKEY? Y COLUMN: UPDATE_USER OLD VALUE: NEW VALUE: AUDITOR The first number is the TimesTen transaction ID. A new transaction ID is generated every time COMMIT is called. The user who executed the transaction was AUDITOR. The transaction was executed at the date and time shown. It was an INSERT (not an UPDATE or DELETE) on the table XLAUSER.NEWTABLE. The first column inserted, ID, is a primary key on the table as indicated with Y. The old column value is null, as this was an INSERT. (If it were an UPDATE, instead of NULL, you would see the old value of the column before the update.) The value inserted was 0123000 (converted from RAW to VARCHAR2) for UUID_PK, and as shown on the next row of the result set, the value inserted for UPDATE_USER was AUDITOR. (NOTE: If you are running with the Oracle database as your audit database, you can now run a query where we get specific values of UUID_PK: SQL> @auditqueryoracleuuid In another terminal session, you can edit the file auditqueryoracleuuid.sql. Look at the select statement and see how the query is performed.) 25) Now let s try to drop the table you just created. In the ttisql session, do:

Command> drop table newtable; 8068: Cannot drop a table or view that is subscribed to by an XLA bookmark. Command> update ttaudit.audittables set auditenabled = N where fulltablename = XLAUSER.NEWTABLE ; Give the ttaudit program a few seconds to re-start. Command> drop table newtable; 26) You may abort the auditing program now if you wish. Go to the terminal session where it is running and press CTRL-C. This program detects signals and shuts down properly. NOTE: if you ever wish to kill the process using the Linux kill command, please use kill or kill -3, NOT kill -9.

Installation and Configuration Notes Enabling Auditing: To enable auditing in a TimesTen database, simply run the DDL script audittablesddltimesten.sql with a tool like SQLDeveloper or ttisql, as we did in step 13 of the tutorial in this document. Edit the.sh script that runs ttaudit (see the tutorial), edit the jmsxla.xml file and change the value of Connection String to your DSN (see the tutorial), then launch ttaudit. When ttaudit first runs, it will scan the metadata in TimesTen for all of the non-system tables and automatically enable auditing for all of these tables. By default, any new table or materialized view will automatically be picked up by ttaudit and audited. (If you do not want new tables audited, specify the ignoreddl command line option for ttaudit.) Make sure the jmsxla.xml file is in the directory where you are running ttaudit, making sure that the audit topic has the correct DSN defined for the database that you wish to audit. Monitoring Auditing and Bookmarks: JMS/XLA uses a bookmark on the TimesTen logging system. Normally, XLA can read the log data of events off the in-memory log buffer. Oracle recommends setting both LogBufMB and LogFileSize in sys.odbc.ini to the same value, and that value should be 1024. If the log buffer fills up, the bookmark can also be placed on the log file(s) on disk. The bookmark must constantly be advancing. If the bookmark does not advance, log files will not be purged when a TimesTen checkpoint occurs. This will cause log files to accumulate until you run out of disk space. ttaudit constantly updates the ttaudit.auditmontor table (you will note that the timestamp column, ts, is updated every 5 seconds) and advances the bookmark when this update takes place. You can also call the call ttlogholds function in TimesTen in ttisql or SqlDeveloper. The XLA bookmark(s) are listed. The number on the left of the result set should be advancing every few seconds. You must make sure that ttaudit is running at all times, so the bookmark is constantly advancing. Customers typically have a shell script that is called through cron every few minutes to make sure that ttaudit is running. Using the Oracle Database To Store Audit Data: You need to edit the audittablesddlauditdb.sql script and run it with DBA permissions. Add your own information about tablespaces to this script as appropriate. You will notice that several tables are created, including ttaudit, ttauditdetail, and ttauditcolumns. The ttauditcolumns table could contain a very large number of rows. A row is inserted into ttaudit for every transaction COMMIT. One or more rows are inserted into ttauditdetail for each part of the transaction; for example, if the transaction consists of 3 inserts and 1 delete, there will be 4 rows in ttauditdetail for this transaction. Each of the columns that were updated, and the values of the columns that are part of the primary key (or unique index) are stored in the ttauditcolumns table. The auditquery02oracle.sql script demonstrates how the tables are joined, and how data can be queried from these tables. Once the audittablesddlauditdb.sql script has been run in the Oracle database, edit one of the rumaudit.sh scripts provided; make sure that TTAUDIT_DBURL, TTAUDIT_DBDRIVER, TT_AUDIT_DBUID, and TTAUDIT_DBPWD are set appropriately. The UID and PWD must have permission in the Oracle database to read and write to the tables in the ttaudit schema.

Disabling Auditing: To disable auditing and remove the bookmark, make sure the ttaudit application is running, then issue this SQL statement in the database you are auditing with a tool like ttisql or SqlDeveloper: call ttrepstop; update ttaudit.auditmonitor set auditenabled = N ; commit; The ttaudit application will automatically unsubscribe all of the tables, remove the bookmark, and shut down. If you wish to re-enable auditing, update the above column to Y. Storing Auditing Data As a File In The File System: Rather than storing auditing data in a database, you can save it to a flat file in the file system. (The file has comma (,) delimiters by default, but that can be changed on the command line.) Specify -outfile /fullpathto/filename on the ttaudit command line; this will write audit data to the flat file and not connect to any database for storing audit data. A script called externaltableddl.sql is provided that provides a full description of the file and instructions on how to load it into an Oracle database as an External Table. Installing ttaudit With TimesTen-to-TimesTen Replication: ttaudit works with TimesTen ACTIVE STANDBY PAIR replication. (Please refer to the TimesTen Replication Guide if you are not familiar with TimesTen replication.) If you wish to run ttaudit on a read-only subscriber, please skip to the section Running ttaudit on a TimesTen Replication STANDBY or SUBSCRIBER. If you wish to run ttaudit on the ACTIVE data store in a highly available configuration, perform these tasks in this exact order: 1) Make sure the jmsxla.xml file contains the line replicatedbookmark= yes under the audit topic; 2) Run the audittablesddltimesten.sql script on the planned ACTIVE data store that you wish to audit; 3) run your CREATE ACTIVE STANDBY PAIR command; 4) start the replication agent; 5) run the sql command call ttrepstateset( ACTIVE ); 6) Create the STANDBY server with ttrepadmin duplicate; 7) Run the audittablesddlauditdb.sql script in your Oracle database.; 8) start ttaudit by editing the supplied runaudit.sh and running it. By default, ttaudit will create a replicated bookmark. If you run the sql command call ttlogholds; on both the ACTIVE and STANDBY databases, you should see that the XLA bookmark is incrementing. If a failover or switchover occurs, ttaudit will re-start. You must start up ttaudit on the new ACTIVE server when the failover occurs. (If you are using TimesTen replication with Oracle Clusterware, Clusterware can be configured to launch ttaudit upon failover.) Since the XLA bookmark is replicated and persisted to TimesTen s log file on disk, ttaudit will pick up where it left off without transaction loss. Dropping Tables When Auditing is Running: You cannot drop tables that are being audited. If you wish to disable auditing for the entire database, see Disabling Auditing above. If you want to drop a single table, you must first disable auditing for that table by running a SQL command. For example, if your owner/schema is JOE, and your table is MYTABLE: update ttaudit.audittables set auditenabled = N where fulltablename = JOE.MYTABLE ;

commit; ttaudit.java must be running. It will detect the change to the audittables table, restart, and unsubscribe to that table. Once this happens, you can execute DROP TABLE. If you wish to reenable auditing, update the above column to Y. Running ttaudit on a TimesTen Replication STANDBY or SUBSCRIBER: If TimesTen is running with TimesTen-to-TimesTen replication, normally ttaudit is run on the ACTIVE or MASTER server. However, you may run ttaudit on a read-only STANDBY or subscriber. To do this, perform the following steps: 1) Set up the planned ACTIVE TimesTen data store for ttaudit as specified in the tutorial above. Launch ttaudit on the ACTIVE and leave it running. (you can abort it later in step 8 below) 2) Set up TimesTen replication per the TimesTen Replication Guide. If the entire data store is not replicated, then at minimum, all tables owned by ttaudit must be replicated, as well as all tables what you wish to audit. 4) Select a bookmark name that is different from the bookmark name used on ttaudit running on the ACTIVE. 5) Execute the following SQL script on the ACTIVE; in the below example, the selected bookmark name for ttaudit running on the read-only subscriber is bookmark2 : insert into ttaudit.audittables (fulltablename, bookmarkname, auditenabled, materializedview) select trim(concat(trim(tblowner), concat('.',tblname))), 'bookmark2', 'Y', 'N' from sys.tables where tblowner not in ('SYS','TTREP','TTAUDIT'); commit; 6) Edit the script you are using to launch ttaudit on the STANDBY or SUBSCRIBER. On the java command line ($TTJAVA_HOME/bin/java server ), add these command line arguments: -runonsubscriber bookmark bookmark2 7) Edit the jmsxla.xml file, and change the DSN to the DSN of the subscriber data store you are auditing. 8) Launch ttaudit on the read-only subscriber. When ttaudit is launched, it should indicate that it is subscribing to your tables with messages in the log. 9) If you wish to run ttaudit on both the ACTIVE and a STANDBY or SUBSCRIBER, you can skip the following step. If you wish to run ttaudit on a STANDBY or SUBSCRIBER only, and you do not want to run ttaudit on the ACTIVE, make sure ttaudit is running on the ACTIVE, then run this SQL script on the ACTIVE, where ttauditbookmark is the name of the bookmark you used for the ACTIVE ttaudit: update ttaudit.audittables set auditenabled = 'N where bookmarkname = 'ttauditbookmark ; commit; Now abort ttaudit on the ACTIVE system, then run this script. call ttxlabookmarkdelete('bookmark1 ); commit;

Manually Removing the XLA Bookmark: The above procedure, Dropping Tables When Auditing is Running, automatically un-subscribes a table to auditing if ttaudit is running. This allows for dropping of that table. The above procedure, Disabling Auditing, automatically removes the XLA bookmark if ttaudit is running. If ttaudit is not running, or you wish to un-subscribe a table to auditing or remove the bookmark manually, execute the following SQL commands in TimesTen: Turn off the replication agent if it is running: call ttrepstop; Find the name of the bookmark: call ttlogholds; Run this command for every table you wish to drop: ttxlaunsubscribe( OWNER.TABLE, bookmarkname ); Once all tables are un-subscribed, remove the bookmark: call ttxlabookmarkdelete( bookmarkname );

Recommended sys.odbc.ini Settings PrivateCommands=1 LogBufMB=1024 LogFileSize=1024 LogBufParallelism = 8 (if you have at least 12 CPU cores on your system) MemoryLock=4 RecoveryThreads = number of CPU cores on your system 2 DatabaseCharacterSet = the same character set as your Oracle DB

ttaudit Command Line Options -convertbinary: This option is recommended. If you are using an Oracle database to store audit data, this option will cause ttaudit to convert binary/raw data to a readable string. For example, the binary 0x0123 will be shown in the ttauditcolumns.new_column_value column as 0123. -topic: The name of the JMS topic, which defaults to audit. If this is changed, the jmsxla.xml file must be changed also to define the new topic name. -bookmark: The name of the bookmark you wish to create. The default is ttauditbookmark. You can run multiple instances of ttaudit simultaneously if you specify the bookmark, -ignoreddl, and ignoremv options on the command line of the second (and subsequent) instances of ttaudit; you would also change the bookmark column in the ttaudit.auditables table for the tables you want monitored on this other bookmark. -fullinsertaudit: This specifies that all columns in a table are audited when an INSERT occurs. This generates a massive amount of data in the ttaudit.auditcolumns table. If this option is not specified, only the columns in the primary key are audited on INSERT. For UPDATEs, all columns that are updated, and the primary keys, are audited no matter the command line option. -jdbcbatchsize: This is the batch size used for Oracle database JDBC batching. The default is 20, which in tests is typically the optimal value. Changing this value may improve the performance of the writes to Oracle. If you are using the TimesTen database to store auditing information, this option is ignored. -heartbeatinterval: The amount of time in milliseconds between updates to the ttaudit.auditmonitor table. This table is constantly updated, so the XLA bookmark is constantly advancing. (If the bookmark was not advancing, log files are not purged upon a TimesTen checkpoint, and eventually, log files would accumulate until disk space was exhausted.) The default is 5000 milliseconds, which is recommended. -dateformat: The default format is YYYY-MM-DD HH24:MI:SS. This is the way date and timestamp data is formatted in auditing. If you want something else, you can specify a different format. See the javadoc for SimpleDateFormat: http://docs.oracle.com/javase/6/docs/api/java/text/simpledateformat.html -xlaurl: The JDBC URL for the TimesTen database you are auditing. This is passed to getconnection(). It must be of the format jdbc:timesten:direct:dsn, where DSN is your DSN as defined in sys.odbc.ini. Client/server connections are not permitted. This DSN must match the DSN definition for the audit topic in the jmsxla.xml file. --xlausername, -xlapassword: The user ID and password for the TimesTen database you are auditing. The audittablesddltimesten.sql script creates a user ID called ttaudit for this purpose. The default password is ttaudit. This user must have permission to read and write to the tables listed in audittablesddltimesten.sql.

--dbusername, -dbpassword: The user ID and password for the database that is storing the auditing data. The audittablesddlauditdb.sql script creates a user ID called ttaudit for this purpose. The default password is ttaudit. This user must have permission to read and write to the tables listed in audittablesddlauditdb.sql. -dbdriver: The JDBC driver for the database that is storing the audit information. This is either com.timesten.jdbc.timestendriver or oracle.jdbc.oracledriver. No other drivers have been tested. -dburl: The JDBC url for the database that is storing the audit data. See runaudit.sh for examples with the Oracle database. -ignoreddl: By default, ttaudit automatically detects CREATE TABLE and CREATE MATERIALIZED VIEW statements and automatically audits the new tables. Use this command line option if you do not want this behavior. If you use this option and want new tables audited, you will need to re-start the ttaudit application, or you need to add a row to the ttaudit.audittables table with the owner and name of your table in the FullTableName column (all CAPS) and the name of the bookmark that ttaudit is using, along with a Y in the auditenabled column. -ignoremv: By default, ttaudit monitors changes in materialized view data. Use this flag if you do not want to audit materialized views. -ignorereplicationstatus: Ignore the fact that the replication state has changed, e.g. from STANDBY to ACTIVE. -ignoreuniqueindexes: Do not flag unique index columns with a Y in the ttaudit.auditcolumns.pk column. Only flag columns in a Primary Key with a Y. -logfile: By default, ttaudit sends all messages and errors to standard out. With this option, you can specify a filename that contains its messages and errors. -maxcolumnauditlength: Data that is audited is truncated at 1024 characters by defapkult. This option changes the maximum length. You will also need to change the length of the VARCHAR2(1024) columns in ttauditddltimesten.sql and ttauditddlauditdb.sql scripts. -tscolumnname: This is the name of the column in your audited tables that contains a timestamp of when the row was updated. The default is UPDATE_TIME. If no such column is specified or found, ttaudit will store the current system time. NOTE: Without this option, the current system time will be the time that ttaudit received the message through JMS/XLA, NOT the time of the transaction. -usercolumnname: This is the name of the column in your audited tables that contains a username of the user that updated the row. The default is UPDATE_USER. -nodatabaseuseraudit: TimesTen s XLA API does not provide information on the database user ID that executed the transaction. However, an algorithm is provided that can in most cases determine the user ID by scanning the list of prepared SQL commands in the database. This is the database login ID, not a login ID of the application. If this option is specified, it does not do this; rather, it relies on a column in your tables that is called something like USER_UPDATED to determine the user ID of the transaction.

-outfile: Rather than storing auditing information in a database, this option stores it as a file in the file system. By default, the delimiter character is a comma between fields. (this character can be changed with delimiter). The file can be loaded into Oracle using an External Table; see the externaltableddl.sql script for a full description of this file and instructions on how to access it in Oracle as an External Table. Specify the full path to the filename after outfile. -stringcharacter: By default, if outfile is used, character strings are enclosed in double quotes ( ). You can specify another character with this option. -savedatatype: By default, the ttaudit.ttauditcolumns.data_type column contains one of two values: -2 (java.sql.types.binary) for binary data or 12 for anything else. This option saves more detailed information about the data type. See externaltableddl.sql for more information. -auditdbretrywait: This is the number of milliseconds to wait between connection re-tries if the audit database connection fails. Default is 5000 (5 seconds). -verbose: If specified, detailed information about every transaction is send to standard out.

Troubleshooting 1) I get an error when I connect, cannot find ttlibjdbc.so in java.library.path. TimesTen requires a native library. You must set LD_LIBRARY_PATH in Linux or Solaris or PATH on Windows. This is done in the runaudit.sh script. 2) There are duplicates in the audit tables. This is a known problem. XLA is an asynchronous API. It is possible that if the ttaudit application is started and restarted, that duplicate transactions may appear. TimesTen produces a unique transaction ID for every time that an application issues a COMMIT; this ID is in the column trx_id. 3) The Oracle database isn t accepting the audit information as fast as TimesTen is writing it. This is a known problem. The Oracle database could lag behind if it is being used for the audit information. One alternative is to write the audit information to the file system with outfile, then bulk load it into Oracle using an External Table; see externaltableddl.sql. 4) When attempting to drop a table, I get an error, TT8068: cannot drop a table that is subscribed by an XLA bookmark. You cannot drop tables that are being audited. If you wish to drop all tables in the database, see Disabling Auditing above. If you wish to drop a single table, see Dropping Tables When Auditing is Running above. If you wish to unsubscribe a table and/or drop the XLA bookmark manually, see Manually Removing the XLA Bookmark above. 5) When I use a TimesTen database to store audit data, BINARY data is not displayed properly. Use an Oracle database to store audit data. 6) When I use an Oracle database to store audit data, BINARY data is not displayed properly, and I cannot query BINARY data. Note how UTL_RAW.CAST_TO_RAW is used in audittablesddlauditdb, creating a function called ttauditfnc.rawformat(). This is used in the sample scripts auditquery01oracle.sql and auditqueryoracleuuid.sql. 7) My applications constantly create and drop tables. The ttaudit program keeps re-starting when this happens.

Use the ignoreddl option on the command line. When you create a table that you want to audit, you will need to add a row to the ttaudit.audittables table yourself. For example: CREATE TABLE myuser.mytable(id NUMBER NOT NULL PRIMARY KEY) INSERT INTO ttaudit.audittables (fulltablename, bookmarkname, auditenables,materializedview) VALUES ( MYUSER.MYTABLE, auditbookmark, Y, N ); 8) I get the error PLSQL_MEMORY_ADDRESS already in use when starting ttaudit. This occurs when you attempt to connect directly to two separate TimesTen databases. If you are using only one TimesTen database, the cause of this error is probably that the DSN in the TTAUDIT_XLAURL of your runaudit.sh script does not match the DSN in the audit topic of your jmsxla.xml file. If you are trying to audit two TimesTen databases on the same system, check the TimesTen documentation for appropriate settings of PLSQL_MEMORY_ADDRESS. 9) TimesTen s log files are accumulating. I run call ttlogholds() in ttisql, and it says that the ttauditbookmark is holdng the log. Repeatedly execute the SQL statement call ttlogholds() several times over about a minute or so. The second number in the result set should be advancing. If it is not advancing, ttaudit is probably not running. Even if no transactions are being executed in the database, ttaudit updates a table called ttaudit.auditmonitor by default every 5 seconds; this should cause the bookmark to advance. If the bookmark is not advancing, then ttaudit is probably not running. If ttaudit it is not running, restart it. If you abort ttaudit, it will leave the bookmark on the last audited transaction in a log file. TimesTen s checkpoint will not remove any log file that has a bookmark or any log file after the bookmark. You should make sure that ttaudit is always running. If the bookmark is advancing, then it is possible that the Oracle database is not keeping up with the transaction volume in TimesTen. This is expected when the TimesTen database is under heavy workload, as TimesTen usually handles transactions faster than the Oracle database. Compare the output of the following sql statements: In TimesTen: SELECT num_trx_total FROM ttaudit.auditmonitor; In Oracle: SELECT count(*) from ttaudit; Repeatedly execute both statements. If num_trx_total is growing faster than Count(*) in Oracle, then Oracle is not able to sustain the transaction rate. If your TimesTen system has bursts of transaction activity followed by low activity, this may be not a problem. The Oracle database can catch up during the low activity periods. Keep in mind

that you can save auditing information to the file system rather than Oracle, and then you can load the file system file into Oracle for analysis. The file system is typically much faster. See Storing Auditing Data As a File In The File System above. During bulk loads or other operations involving a large number of rows in TimesTen, you may want to disable auditing at the start of the batch job and re-enable auditing afterward. See the Disabling Auditing section above. If you want to disable auditing and remove the bookmark, see the Disabling Auditing section above. Note that any transaction since the last successfully audited transaction will NOT be audited.