The Ultimate Guide For DBAs To adrci Tool

What? Another tool? Yes! And this one is your friend!
Do you know why? Because it makes your job easier!
How? That is what you’ll find out today!

Last week, I wrote a refresher on the ADR, or Automatic Diagnostic Repository. If you missed it, you can review it here: 5 Things That Every Good DBA Needs To Know About The ADR.

Starting with 11g, the new concept of ADR was introduced together with the adrci tool. DBAs around the world started reading about it, learning and studying about it. But as time passed by, most of the DBAs forgot about the adrci. They knew it existed, but vaguely remembered what it was supposed to do, and how it was supposed to work.

That is why this article will refresh those long forgotten memories of adrci, and will give you a new view on it!

1. What Is adrci?
2. How To Get Started With adrci?
3. What Type of Commands Are Available In adrci?
4. How Are Trace Files Cleaned Up?
5. How To Modify Retention Policy For ADR Data?
6. What Files Are Not Purged And How To Purge Them?

1. What Is adrci?

Adrci or ADR Command Interpreter, is a command line tool that enables you to interact with the Automatic Diagnostic Repository.

With adrci you can:

• view trace files
• package incident and problem data to send it to Oracle support
• view Health Monitor reports
• manually clean up the repository
• configure repository properties

To start the tool, type in adrci at the command line.

Did you know you do not need to provide credentials in order to use this tool?
The reason behind it is ADR data is not considered secure data, so no credentials are required.

2. How To Get Started With adrci?

If you have no idea on what commands are available to you, just type in help, and a list of commands will show up.

adrci> help

 HELP [topic]
   Available Topics:
        CREATE REPORT
        ECHO
        EXIT
        HELP
        HOST
        IPS
        PURGE
        RUN
        SET BASE
        SET BROWSER
        SET CONTROL
        SET ECHO
        SET EDITOR
        SET HOMES | HOME | HOMEPATH
        SET TERMOUT
        SHOW ALERT
        SHOW BASE
        SHOW CONTROL
        SHOW HM_RUN
        SHOW HOMES | HOME | HOMEPATH
        SHOW INCDIR
        SHOW INCIDENT
        SHOW LOG
        SHOW PROBLEM
        SHOW REPORT
        SHOW TRACEFILE
        SPOOL

It is really cool that you can ask for help on a specific command, if you want a description of it:

adrci> help show tracefile
  Usage: SHOW TRACEFILE [file1 file2 ...] [-rt | -t] 
                        [-i inc1 inc2 ...] [-path path1 path2 ...] 

  Purpose: List the qualified trace filenames.
  Options: 
 ...
  Examples:  
    1. Show all the trace files under the current home
       "show tracefile"
    2. Show all the mmon trace files in time reverse order
       "show tracefile %mmon% -rt"
    3. Show all trace files under incidents 123 456, and /home/someone/temp
       "show tracefile -i 123 456 -path  /home/someone/temp" 

3. What Type of Commands Are Available In adrci?

Adrci commands can be grouped into 4 categories, based on whether or not they require to have the ADR home set or not.

• commands that do not need to have ADR home set: ECHO, HELP
• commands that work with only one ADR home, and return an error if there are multiple current homes: PURGE
  If you try issuing the PURGE command without one home set you get the error: DIA-48448: This command does not support multiple ADR homes
• commands that prompt you to select a specific ADR home: SHOW ALERT
• commands that work with one or more ADR homes: SHOW TRACEFILE

Now that you know how some of these commands work, you understand that you will need to set the homepath, or ADR home, depending on the actions you want to perform.
When you start adrci, the ADR homepath is set to null, which means that all the ADR homes that are under the same ADR base, are current.
To better understand this, lets see what homes we have available:

adrci> show homes
ADR Homes: 
diag/rdbms/cdb1/cdb1
diag/tnslsnr/localhost/listener

adrci> show base
ADR base is "/u01/app/oracle"

Did you noticed that ADR home is relative to ADR base?

In order to set the ADR home to a specific home, just issue the command:

adrci> set home diag/rdbms/cdb1/cdb1

4. How Are Trace Files Cleaned Up?

This is my favorite part of adrci. When I think back to 9i and 10g days, a good DBA had to have some sort of script in place, outside the database, that would cleanup the trace files, in the bdump, udump and other locations.

Starting with 11g, when ADR was first introduced, the responsibility of cleaning up ADR data goes to: MMON background process.

Isn’t this awesome?

Let me step back a bit, MMON will not cleanup all of the files, but it will cleanup most of them. This is great, because if you do not setup any manual purging, the probability of running out of space in the ADR is reduced many folds!
Even if you are just starting in your DBA career, and are not aware of all the ins and outs, of all the things you need to create scripts for, you will not have problems with the ADR data, as MMON is here to the rescue!

In order for MMON to purge the files, some kind of retention policy needs to be defined. And it is. In ADR, there are two types of retention for the ADR data:

• SHORTP_POLICY – used for the data that has a short life. By default is set to 720 hours (equivalent of 30 days)

These are the components that follow the shortp_policy:

• TRACE
• CDUMP
• UTSCDMP
• IPS

• LONGP_POLICY – used for data that has a long life. By default is set to 8760 hours (equivalent of 365 days)

These are the components that follow the longp_policy:

• ALERT
• INCIDENT
• SWEEP
• STAGE
• HM

5. How To Modify Retention Policy For ADR Data?

Check current settings: show control

adrci> show control

ADR Home = /u01/app/oracle/diag/rdbms/cdb1/cdb1:
*************************************************************************
ADRID                SHORTP_POLICY        LONGP_POLICY         LAST_MOD_TIME                            LAST_AUTOPRG_TIME                        LAST_MANUPRG_TIME                        ADRDIR_VERSION       ADRSCHM_VERSION      ADRSCHMV_SUMMARY     ADRALERT_VERSION     CREATE_TIME                              
-------------------- -------------------- -------------------- ---------------------------------------- ---------------------------------------- ---------------------------------------- -------------------- -------------------- -------------------- -------------------- ---------------------------------------- 
1467330218           720                  8760                 2014-01-07 16:09:18.320985 -08:00        2017-05-24 20:30:29.142386 -07:00                                                 1                    2                    80                   1                    2014-01-07 16:09:18.320985 -08:00       
1 rows fetched

Modify the policy:

adrci>set control (SHORTP_POLICY = 1440)
adrci>set control (LONGP_POLICY = 4000)

6. What Files Are Not Purged And How To Purge Them?

Some files are not purged within the ADR. I list below some of them, there might be others too.
It is the responsability of the DBA to setup a purge mechanism, or file rotation for these files, just like in the olden days.

• text based alert log will not be purged automatically or manually.
  However, the xml version of the alert log is rotated to log_XX.xml, when the log.xml reaches 10MB in size. The xml versions of the alert log are purged.
• text based listener log file will not be purged automatically or manually.
• xml base listener log file will not be purged automatically. However you can manually purge it within adrci, or with an adrci script.

If you want to manually purge some of the ADR data, use the PURGE command:

adrci>purge -age 10000 -type alert

The age in the purge command is specified in minutes. This is something to keep in mind, as the retention policy for ADR is specified in hours instead.

To remember all of this, I am sharing with you a mind map!

If you enjoyed this article, and would like to learn more about databases, please sign up below, and you will receive
The Ultimate 3 Step Guide To Find The Root Cause Of The Slow Running SQL!

–Diana