Subject:  Oracle8i - 8.1 Log Miner Inernals 
Creation Date:  05-JUL-2000 

PURPOSE
=======

Provides internal information on the Log Miner utility in Oracle8i.
For a complete description of Log Miner please reference [NOTE:62508.1].


 
SCOPE & APPLICATION
===================

This is intended for Oracle Support Analysts.

 
TABLE OF CONTENTS
=================
   1. What does log miner do?
   2. Internals
   3. Low level Internals




1. WHAT DOES LOG MINER DO?
==========================

   Log Miner can be used against online or archived logs from either 
   the 'current' database or a 'foreign' database. The reason for this is that 
   it uses an external dictionary file to access meta-data, rather than 
   the 'current' data dictionary.

   It is important that this dictionary file is kept in step with the 
   database which is being analyzed. If the dictionary used is out 
   of step from the redo then analysis will be considerably more difficult.
   Building the external dictionary will be discussed in detail in section 3.
 
   Log Miner scans the log/logs it is interested in, and generates, using the 
   dictionary file meta-data, a set of SQL statements which would have the 
   same effect on the database as applying the corresponding redo record.

   Log miner prints out the 'Final' SQL that would have gone against 
   the database e.g.

   Insert into Table x Values ( 5 );
   Update Table x set COLUMN=newvalue WHERE ROWID='<>' 
   Delete from Table x WHERE ROWID='<>' AND COLUMN=value AND COLUMN=VALUE

   We do not actually see the SQL that was issued, rather an executable 
   SQL statement that would have the same EFFECT. Since it is also stored in 
   the same redo record, we also generate the undo column which would be 
   necessary to roll this change out.

   For SQL which rolls back, no undo SQL is generated, and the rollback 
   flag is set. An insert followed by a rollback therefore looks like: 

   REDO                              UNDO              ROLLBACK 

   insert sql                        Delete sql        0
   delete sql                        <null>            1

   Because it operates against the physical redo records, multirow operations
   are not recorded in the same manner e.g. DELETE FROM EMP WHERE DEPTNO=30
   might delete 100 rows in the SALES department in a single statement, 
   the corresponding Log Miner output would show one row of output per row 
   in the database.


2. INTERNALS 
============

   dbms_logmnr and dbms_logmnr_d call kernel C modules directly. There 
   is very little of the functionality visible to the user in dbmslogmnr.sql.

   The interface used by Log Miner is a series of X$tables and V$views.
   The V$views are slightly less informative, but share the same naming
   convention. There is also a Multi instance GV$version too. 
   From now on however, I will refer to the V$views only.
   
   An important internals point is that because Log Miner's memory allocation
   Comes from the PGA, Log Miner cannot be used in an MTS environment.
   Also the output is only visible in a single session, and only for the 
   life of that session. If further analysis is needed, either reload the 
   information , of make it permanent via CTAS.

   V$LOGMNR_LOGS
   =============

   Populated by dbms_logmnr.add_logfile. At a low level it is implemented 
   by krvrarf(). Results are stored in the PGA in extents of type Freeable 
   with a description of "KRVRARF:krvrlc" 

   This table stores the Log's sequence number as well as the high and low
   times & SCN's of all currently registered logs. If there is a gap e.g. 
   if you try to analyze a group of logs and one is missing, an entry 
   is generated in start_logmnr is run indicating a gap.   
   Currently it seems that this also removes any logs which were registered 
   with a log sequence higher than the missing log. Development have been 
   asked to clarify this, as it is probably a bug/feature. 

   V$LOGMNR_PARAMETERS
   ====================

   The values passed into dbms_lognmr.start_logmnr. Basically 
   High and Low SCNs, High and Low Times, Info, Status 

   V$LOGMNR_DICTIONARY
   ===================

   Details of the Dictionary file which is to be used to analyze the logs 
   with. Columns Include DB name, ID , and Timestamp. As discussed earlier,
   this is needed to resolve the table and column names. 
 
   The Dictionary appears to be read in to PGA Heaps of type
   KRVD:alh and held there. This dictionary is held as a table in PGA memory 
   
   A truss of the START_LOGMNR procedure will show the dictionary 
   file being read, and a PGA heapdump ( level 1 ) of the process which has 
   done the start_logmnr will show many chunks with a description of
   "KRVD:alh".

   V$LOGMNR_CONTENTS
   =================  

   An important point is that Log Miner does not necessarily scan an entire
   log file into memory at once to read it. Since it can take time to read 
   each logfile. It may often be quicker to CTAS a 'Real' table and build 
   indexes on it rather than make multiple Sequential passes through each 
   logfile. V$LOGMNR_CONTENTS is not currently indexed.
   
   It appears that rather than buffering the selects , we do a log file 
   sequential reads when you want data. This is in 1 Megabyte chunks.
   so you see Log file sequential read waiting on 2048-1 512 byte redo 
   Log blocks

3. Low level Internals 
======================
   The Log Miner source lives in its own separate subdirectory of the 
   recovery code  -> rdbms/src/server/rcv/vwr
 
   The following files contain the code 

   Headers

   krv.h	- 	General Inclusions
   krvd.h	- 	Specifically to build the Dictionary file

   Code 

   krvd.c	- Dictionary Interface
   krvf.c	- Fixed Tables/Views 
   krvr.c	- Most of the Viewer functionality
   krvt.c       - Subroutines