1 Using the Logdump Utility

This chapter contains instructions for using the Logdump utility of Oracle GoldenGate. Logdump enables you to search for, filter, view, and save data that is stored in a trail or extract file.

Note:

To avoid any adverse effects on the data or checkpoints in your trails, use Logdump only with guidance from an Oracle support analyst or an experienced Oracle GoldenGate user.

This chapter includes the following sections:

1.1 Getting Started with Logdump

This section introduces you to basic Logdump commands that enable you to open files, control the display, navigate through a file, and filter for specific information, among other basic tasks. It also illustrates and explains the components of a record.

1.2 Viewing the First Record

The steps in this section explain how to set up the Logdump environment and start viewing records.

1.2.1 Running Logdump

Run the logdump program from the Oracle GoldenGate installation location. Logdump command lines are numbered so that you can use edit and history commands.

1.2.2 Setting Up the View

The following commands set up a Logdump environment that shows the information most commonly used when analyzing Oracle GoldenGate trail records.

  1. To view the record header with the data:

    Logdump 1> GHDR ON
    

    The record header contains information about the transaction.

  2. To add column information:

    Logdump 2> DETAIL ON
    

    Column information includes the number and length in hex and ASCII.

  3. To add hex and ASCII data values to the column information:

    Logdump 3> DETAIL DATA
    
  4. To view user tokens:

    Logdump 4> USERTOKEN ON
    

    User tokens are custom user-defined information that is specified in a TABLE or FILE mapping statement and stored in the trail file for specific purposes.

  5. To view automatically generated tokens:

    Logdump 4> GGSTOKEN ON
    

    Oracle GoldenGate automatically generated tokes include the transaction ID (XID), the row id for DML operations, the fetching status (if applicable), and tag value.

  6. To control how much record data is displayed:

    Logdump 5> RECLEN length
    

1.2.3 Opening a Trail File

To open a trail file, complete the following steps:

  1. Open a file with the following command:

    Logdump 6> OPEN file_name
    

    Where:

    file_name is either the relative name or fully qualified name of the file, including the file sequence number. For example:

    open /home/ggs/dirdat/jd000000
    open $data01.glogggl.aa000000
    
  2. To go to the first record and then move through records in sequence:

    Logdump 7> NEXT
    

    Alternatively, you can simply enter N.

Figure 1-1 Logdump Record as Seen on a Windows System

Description of Figure 1-1 follows
Description of "Figure 1-1 Logdump Record as Seen on a Windows System"

Figure 1-2 Trail Record as Seen on NonStop

Description of Figure 1-2 follows
Description of "Figure 1-2 Trail Record as Seen on NonStop"

1.3 Executing Basic Logdump Tasks

The following are some basic tasks that can be performed with Logdump. For detailed information about the commands shown and other available options, see the alphabetical reference in Chapter 2, "Logdump Commands."

1.3.1 Finding the Next Good Record Header

To find the next good record header, enter the following command:

Logdump 8> SCANFORHEADER

Alternatively, you can simply enter SFH.

1.3.2 Finding the Beginning, Middle, and End of a Transaction

To find the beginning, middle, and end of a transaction, complete the following steps:

  1. Show headers and detail.

    Logdump 9> GHDR ON
    Logdump 10> DETAIL ON
    
  2. Go to the next record.

    Logdump 11> N
    
  3. View the TransInd field in the record header. The following table explains where the record is in relation to the transaction.

    Transaction Indicator Description
    TransInd   : .  (x00)
    
    First statement in transaction
    TransInd   : .  (x01)
    
    Statement in middle of transaction
    TransInd   : .  (x02)
    
    Last statement in transaction
    TransInd   : .  (x03)
    
    Sole statement in transaction

  4. Move through subsequent records by pressing N, and refer to the TransInd field to determine where each one is within the transaction. When TransInd is either x02 or x03, the TransInd of the next record should be x00, starting a new transaction.

1.3.3 Scanning for the End of a Transaction

To scan for the end of a transaction, enter the following command:

Logdump 20> SCANFORENDTRANS

Alternatively, you can simply enter SFET.

The record shown will be the first one in the next transaction. To confirm, the TransInd field should be x00.

1.3.4 Going to a Specific RBA in the File

To go to a specific RBA in the file, you can do either of the following:

  • To go to an RBA anywhere in the file:

    Logdump 35> POS rba
    Logdump 36> N
    

    This displays the record located at that RBA.

  • To go to the first record in the file:

    Logdump 37> POS FIRST
    

    Alternatively, you can enter the following command:

    Logdump 37> POS 0
    

1.3.5 Filtering Based on a Table or Data File Name

To filter out everything except records containing a specific NonStop data file name, enter the following command:

Logdump 60> FILTER INCLUDE FILENAME $volume.subvolume.file

To filter out everything except records containing a specific table name:

  • On a NonStop system:

    Logdump 60> FILTER INCLUDE ANSINAME catalog.schema.table
    
  • On a Windows or UNIX system:

    Logdump 60> FILTER INCLUDE FILENAME [container | catalog] schema.table
    

Now, when you use the N command, you will only see records that satisfy this filter. Conversely, to filter out records containing a specific table or file name, but show everything else, use the EXCLUDE option instead of INCLUDE.

1.3.6 Removing the Current Filter Criteria

To remove the current filter criteria, enter the following command:

Logdump 62> FILTER CLEAR

1.3.7 Filtering on Multiple Conditions

To filter on multiple conditions, enter one of the following commands:

  • Logdump 60> FILTER INCLUDE FILENAME $volume.subvolume...file..; FILTER RECTYPE record_type; FILTER MATCH ALL

  • Logdump 60> FILTER INCLUDE ANSINAME catalog.schema.table; FILTER RECTYPE record_type; FILTER MATCH ALL

  • Logdump 65> FILTER INCLUDE FILENAME schema.table; FILTER RECTYPE record_type; FILTER MATCH ALL

Use MATCH ANY or MATCH ALL depending on whether you want the search to match any or all of the filter conditions, respectively, when multiple conditions are specified. The preceding example filters on a name and record type, typically an operation type such as INSERT.

1.3.8 Count the Records in a Trail File

The following command shows a count summary followed by counts for each table or data file:

Logdump 67> COUNT

1.3.9 Saving Records to a New Trail File

To save the whole file, enter the following command, where file is the name of the new file:

Logdump 68> SAVE file

To save a subset of records, enter the following command:

Logdump 69> SAVE file n RECORDS

1.3.10 Closing the Current File and Opening the Next One in the Trail

To close the current file and open the next one in the trail, enter the following command:

Logdump 70> NEXTTRAIL

1.3.11 Keeping a Log of Your Session

To start logging, enter the following command:

Logdump 71> LOG TO filename.txt

To write text to the log:

Logdump 72> WRITELOG "text"

To stop logging:

Logdump 73> LOG STOP

1.3.12 Seeing the Current Logdump Environment

To see the current Logdump environment, enter the following command:

Logdump 74> ENV

This shows which features are enabled, such as filtering and header views, and it shows environment information such as the current trail and position.

1.3.13 Getting Online Command Help

To get online command help, enter the following command:

Logdump 75> HELP

1.3.14 To Exit Logdump

To exit Logdump, enter either of the following commands:

  • Logdump 100> EXIT

  • Logdump 100> QUIT

1.4 Evaluating Transaction Size

Use Logdump's TRANSHIST command in conjunction with other Logdump commands to determine whether or not your applications generate large transactions and to identify their relative size. TRANSHIST causes Logdump to track the size of transactions contained in a trail file or extract file in an internal history table. The transactions are ranked in descending order of size, in bytes. When the history table is full, the smallest transaction is removed to allow a larger transaction to be added to the list.

To use statistics generated by TRANSHIST, issue the following series of commands in Logdump:

  1. Use TRANSHIST to set the size of the history table that tracks transaction size. The maximum size is 200 bytes. A value of 0 turns off the tracking.

    TRANSHIST n
    
  2. Use either the TRANSRECLIMIT or TRANSBYTELIMIT command to set a lower boundary for what is considered a normal sized transaction. These commands prevent normal-sized transactions from being tracked. Eliminating normal-sized transactions reduces the amount of data that must be reviewed.

    {TRANSBYTELIMIT n bytes | TRANSRECLIMIT n records}
    
  3. Use Logdump's COUNT command to display the statistics on transaction size, which appear at the end of the output and look like the following excerpt:

    Transactions with at least 100 records or 100000 bytes
    2011/02/01 09:31:24.000.000    00:00:00.000, Seq 0, RBA 13101
       Bytes/Trans .....    1168167
       Records/Trans ...       1001
       Files/Trans .....          1
    2011/02/01 09:31:35.000.000    00:00:11.000, Seq 0, RBA 1205292
       Bytes/Trans .....    1168167
       Records/Trans ...       1001
       Files/Trans .....          1
    

    Logdump scans the file(s) and reports the information.

  4. Use Logdump's POSITION RBA command to go to each RBA listed in the COUNT output to find out the name of the table that generated the transaction. You can group these tables into their own processing group so that they do not affect processing of other tables that generate normal sized transactions.

1.5 Maintaining Command History

On Windows and UNIX systems, command history is stored in a file named logdump.hst. On NonStop systems, command history is stored in a file named logduhst. The file is created in the home location of the user who first started Logdump.

When Logdump starts up, it looks for the history file in one of the following locations, depending on the platform:

  • The USERPROFILE environment variable.

  • The $HOME environment variable.

  • The default $vol.subvol.

If the file exists, Logdump loads the command history into a buffer. The command history buffer holds 400 commands. Upon termination of the Logdump session, the session's history is appended to the file.

1.6 Viewing Logdump Command Information and Syntax

To learn more about Logdump commands, see the alphabetical reference documentation in Chapter 2, "Logdump Commands".