The Database Insertion Test

Test objectives

Measurement of rates of insertion with various dimensions of the insertion data e.g. 1,10,100,1000 objects.
Validation of the data inserted against the input ilwd.

APIs affected by this test

managerAPI: directs processing of the insertion and query user commands to the ligolwAPI and metadataAPI and returns the user command status to the user.

ligolwAPI:
- Retrieves the data to be ingested from the specified url to ilwd object and sends the ilwd to the metadataAPI for insertion.
- Converts the query results in ilwd from the metadataAPI into xml and delivers the output to the specified url
metadataAPI:
- insert the metadata ilwd data from ligolwAPI into the specified database.
- process the queries, retrieve the result rows from database and send them as ilwd object to ligolwAPI.

Setup

Choose a directory to install the tests scripts.

The script files are:
metadata.test - main driver script


        getMetaData.tcl
        - getMetaData user cmd test driver

        putMetaData.tcl
        - putMetaData user cmd test driver

        get_refs.sql
        - extract unique Ids for generation of ilwds

        xrefs.tcl
        - generates include files (.h) based on the data inserted
     
        ilwdValidate.tcl
        - compares ilwds in ilwd and xml formats 

        createplot.tcl
        - parses metadata log to generate insertion rate files

        dbstats.tcl
        - compares current results with previous

        analyseInsert.tcl
        - extracts insertion logs and invokes post processing via createplot.tcl and dbstats.tcl. 

                        	
		
		
ilwd generating source files and Makefile are required for all tables; they can be checked out from
        ldas cvs repository under dbms
		
                
		coinc_snglilwd.cc         multi_burstilwd.cc      sngl_mimeilwd.cc
		commonilwd.cc             multi_inspiralilwd.cc   sngl_ringdownilwd.cc
		filter_paramsilwd.cc      process_paramsilwd.cc   sngl_transdatailwd.cc
		filterilwd.cc             processilwd.cc          sngl_unmodeled_vilwd.cc
		frameset_chanlistilwd.cc  runlistilwd.cc          sngl_unmodeledilwd.cc
		frameset_locilwd.cc       segment_definerilwd.cc  summ_commentilwd.cc
		frameset_writerilwd.cc    segmentilwd.cc          summ_csdilwd.cc
		framesetilwd.cc           sngl_burstilwd.cc       summ_mimeilwd.cc
		gds_triggerilwd.cc        sngl_datasourceilwd.cc  summ_spectrumilwd.cc
		sngl_dperiodicilwd.cc     summ_statisticsilwd.cc
		sngl_inspiralilwd.cc      summ_valueilwd.cc	  Makefile
		

		Note: gcc compiler environment must be present for ilwd source code to be compiled into executables.

		
		
Environment variables:
		 Environment variable SSH_AUTH_SOCK is required to allow execution of scripts on dataserver to retrieve logs.
		 To set this, on the ldas gateway, find out the name of the ldas agent by running the ldas utility ldasagent.
		 Then setenv SSH_AUTH_SOCK to the output of ldasagent if an agent exists.
		 Then login to metaserver; verify that the environment variable is set before running the test.
		 
        
        Note: At all the sites, the required script files are installed at /ldas_usr/ldas/test/database.


        Test Execution
		The test must be run from the host where db2 resides, i.e. metaserver and run in the scripts directory e.g. /ldas_usr/ldas/test/database.
		
		cd /ldas_usr/ldas/test/database

		
        Usage: metadata.test [options] >& metadatatest.log & 

        

            
                Option
                Description
            

                <dsname>
                database name for the test
            

                <dims set>
                set of ilwd dimensions, comma separated e.g. 1,10,100,1000
            

                <previous result directory>
                relative location of directory of previous result for comparision e.g. results-1107
            

                <validate [ 0 | 1 ]>
                boolean flag to indicate if validation should be done on data inserted; if so a getMetaData command
				is issued to retrieve the data and validation invoked. 
            

                no options
                shows the required arguments.
        

		
		
Test Validation:
		The test is divided into the following phases and fully automated to execute all the phases. Validation for each
        phase is described.
		

		Insertion phase
			The database is cleared out. 
			The tables are divided into 4 levels according to their dependency on previous tables. Insertions for table data
			at each level are completed before the next level. After one level is inserted, scripts are ran to extract
			inserted information to generate include files (.h) . The next level ilwds are generated by compiling the source code
			with the include files and running the executables to output ilwds that reference inserted data. If the ilwds do 
			not compile properly, most likely the include files are not being generated properly; it is best to terminate the
			test and examine why the database extraction did not result in the correct include files. 
		
		
Query and ilwd validation phase
			If validate option is 1, a query is made to extract data from each of the tables into xml. The result xml is
			compared against the original ilwd to verify that all input data in the ilwd is the same as in the database.
			Since the IBM DB2 does not support unsigned integers, there will a mismatch for ilwd types INT_2U, INT_4U and
			INT_8U.  The validation reports are directed to stdout.
There is a line per table:
			e.g. Test passed for table sngl_datasource.
and the end result:
			All tables passed. 
		
		
Insertion Rates Computation
			The logs generated during insertion phase are extracted from ldas logs and parsed to generate output files 
			correlating ilwd dims to insertion cputime, walltime and insertion rate in number of rows/sec. The rates are already
			computed by the metadataAPI and recorded in the logs. 3 files are output: 

			

			insert<start-gpstime>-<end-gpstime>.log.html, - insertion log file extracted from metadataAPI, 
			e.g. insert691959297-691962080.log.html

			
<site><dbname><ldas-version><yyyymmdd>.html - html file of table, dims vs cputime, walltime,insertion rates
			e.g. ldas-dev.ldas_tst.ldas-0.0.23.20011209.html

			
insert.<dbname><ldas-version><yyyymmdd> text format of table, dims vs cputime, walltime,insertion rates.
			e.g. insert.ldas_tst.ldas-0.0.23.20011209.txt

			
createplot.log - output log from createplot.tcl; if there are missing dims, errors are reported here.
			

		
Insertion Rate Analysis
			The current insertion file output (.txt file) is used to compare against results from 3 previous releases to see if the rates are within
			10% standard deviation; if so this implies a no change in rate and the test passes. 
			If not, the test fails. There are 3 output file from the comparision:
			

			insert<dbname><ldas-version><yyyymmdd>.stats.m.n.r - e.g. insert.dev_1.ldas-1.2.3.20040910.stats.1.2.0
            is the output statistical comparison of this result vs that of ldas 1.2.0, and insert.dev_1.ldas-1.2.3.20040910.stats.1.1.0
            is the output statistical comparison of this result vs that of ldas 1.1.0.

Option	Description
`<dsname>`	database name for the test
`<dims set>`	set of ilwd dimensions, comma separated e.g. 1,10,100,1000
`<previous result directory>`	relative location of directory of previous result for comparision e.g. results-1107
`<validate [ 0 \| 1 ]>`	boolean flag to indicate if validation should be done on data inserted; if so a getMetaData command is issued to retrieve the data and validation invoked.
`no options`	shows the required arguments.