Start Using Oracle Autonomous Health Framework

Understanding the Directory Structure

Review the key directories used by Oracle Autonomous Health Framework (AHF).

Directory	Description
<AHF_LOC>	Directory where Oracle Autonomous Health Framework is installed.
<AHF_LOC>/python	Python home directory.
<AHF_LOC>/orachk	Oracle Orachk home directory.
<AHF_LOC>/jre	Java Runtime Environment (JRE) home directory.
<AHF_LOC>/common	AHF common directory that contains shared libraries and components such as ACR and ORDS.
<AHF_LOC>/bin	Directory that contains AHF binaries and command-line utilities, including tfactl and orachk.
<AHF_LOC>/analyzer	AHF Analyzer directory.
<AHF_LOC>/data	AHF data directory that contains data generated by AHF components, such as configuration files, Berkeley DB (BDB) data, and index data.
<AHF_LOC>/tfa	Oracle Trace File Analyzer (TFA) home directory.
<DATA_DIR>	Directory where AHF stores diagnostic collections and metadata.
<DATA_DIR>/repository	Directory where AHF stores diagnostic collections.
<DATA_DIR>/<HOST>/diag	Directory that contains logs generated by AHF components for the specified host.

Where:

• <AHF_LOC> is the Oracle Autonomous Health Framework installation directory.
• <DATA_DIR> is the configured AHF data directory.
• <HOST> is the host name associated with the AHF data and diagnostic files.

Configuring Oracle Trace File Analyzer and Oracle Orachk/Oracle Exachk to Use the Same Notification Addresses

Configure common notification email addresses for Oracle Trace File Analyzer (TFA), Oracle Orachk, and Oracle Exachk.

The configured recipients can receive notifications about:

• Oracle Orachk and Oracle Exachk compliance check results.
• Significant faults detected by Oracle Trace File Analyzer.

Use the ahfnotificationaddress property to configure the same notification addresses for these AHF components.

Setting Notification Email Addresses

1. Specify the notification email addresses as a space-separated list:

   tfactl set ahfnotificationaddress="<email_address1> <email_address2> ..."

   For example:

   tfactl set ahfnotificationaddress="[e-mail] [e-mail]"

   Example output:

   Successfully set the AHF Notification Address

   Use tfactl set ahfnotificationaddress to set the notification addresses or update the existing list.

   If you specify email addresses during AHF installation, AHF stores them in the install.properties file. Oracle Orachk and Oracle Exachk use these addresses to update the NOTIFICATION_EMAIL property for scheduled jobs.

   If you explicitly specify notification addresses when creating an Oracle Orachk or Oracle Exachk scheduled job, the addresses specified for that job override the addresses stored in install.properties.

   By default, Oracle Trace File Analyzer does not automatically use the notification addresses stored in install.properties. Use tfactl set ahfnotificationaddress to explicitly configure the notification addresses for TFA.

   To view the notification addresses configured for Oracle Orachk or Oracle Exachk scheduled jobs, run:

   orachk -get NOTIFICATION_EMAIL

   or:

   exachk -get NOTIFICATION_EMAIL

Viewing Notification Email Addresses

2. To display the configured AHF notification addresses, run:

   tfactl get ahfnotificationaddress

   The command retrieves the notification email addresses from the install.properties file.

   Example:

   # tfactl get ahfnotificationaddress
   
   AHF Notification Address : [e-mail] [e-mail]

Removing Notification Email Addresses

3. To remove the configured notification email addresses, run:

   tfactl unset ahfnotificationaddress

   Example output:

   Successfully unset the AHF Notification Address

   The command removes the notification email addresses from the install.properties file.

Configuring Oracle Trace File Analyzer and Oracle Orachk/Oracle Exachk to Use Different Notification Addresses

Configure separate notification email addresses when Oracle Trace File Analyzer (TFA) and Oracle Orachk or Oracle Exachk notifications must be sent to different recipients.

Configuring Notification Addresses for Oracle Orachk or Oracle Exachk

Specify the notification email addresses as a comma-separated list using the NOTIFICATION_EMAIL property.

For Oracle Orachk:

orachk -set "NOTIFICATION_EMAIL=[e-mail],[e-mail]"

For Oracle Exachk:

exachk -set "NOTIFICATION_EMAIL=[e-mail],[e-mail]"

Optionally, use the -id option to configure notification addresses for a specific scheduled profile. If you do not specify an ID, DEFAULT is used.

For example, to configure notification addresses for an Oracle Orachk profile with the ID dba:

orachk -id dba -set "NOTIFICATION_EMAIL=[e-mail],[e-mail]"

For Oracle Exachk:

exachk -id dba -set "NOTIFICATION_EMAIL=[e-mail],[e-mail]"

Configuring Notification Addresses for Oracle Trace File Analyzer

To configure a notification email address for a specific ORACLE_HOME, specify the operating system owner and email address:

tfactl set notificationAddress=<os_user>:<email_address>

For example:

tfactl set notificationAddress=oracle:[e-mail]

To configure a notification email address that applies to any ORACLE_HOME, specify only the email address:

tfactl set notificationAddress=<email_address>

For example:

tfactl set notificationAddress=[e-mail]

Oracle Trace File Analyzer Command-Line and Shell Options

Use tfactl as a command-line, shell, or menu interface to administer Oracle Trace File Analyzer (TFA), collect diagnostic data, and analyze diagnostic collections.

Interface	Command	Description
Command-line	tfactl <command>	Specify the command and its options directly on the command line.
Shell interface	tfactl	Start the interactive TFA shell, set or change the context, and run commands from within the shell.
Menu interface	tfactl menu	Use menu navigation to select and run commands.

Using tfactl, you can:

• Run administration commands.
• Collect diagnostic data.
• Analyze diagnostic collections.

The commands that you can run depend on your level of access to tfactl.

Run administrative commands as root or with sudo. A subset of commands is also available to:

• Oracle Database home owners.
• Oracle Grid Infrastructure home owners.
• Members of the OSDBA or OSASM groups.

To grant other users access to tfactl, use:

tfactl access

Using the Command-Line Interface

To run tfactl as a command-line tool, use:

tfactl <command> [options]

For example:

tfactl status

Using the Shell Interface

To start the interactive tfactl shell, run:

tfactl

The command displays the tfactl prompt:

$ tfactl
tfactl>

Run the required TFA commands from the tfactl> prompt.

Getting Command Help

Append the -help option to a tfactl command to display command-specific help:

tfactl <command> -help

Managing Oracle Trace File Analyzer and Oracle Orachk Daemons Using systemctl Commands

On Oracle Linux systems, use systemctl commands to manage the Oracle Trace File Analyzer (TFA) service. Run these commands as the root user.

You can also start and stop the Oracle Trace File Analyzer daemon using the tfactl start and tfactl shutdown commands.

Managing TFA Using systemctl

To check the status of the TFA service:

systemctl status oracle-tfa.service

To start the TFA service:

systemctl start oracle-tfa.service

To stop the TFA service:

systemctl stop oracle-tfa.service

For example:

# systemctl status oracle-tfa.service

oracle-tfa.service - Oracle Trace File Analyzer
Loaded: loaded (/etc/systemd/system/oracle-tfa.service; enabled; vendor preset: disabled)
Active: inactive (dead) since Fri 2021-01-29 18:50:51 PST; 24s ago
Process: 79935 ExecStart=/etc/init.d/init.tfa run >/dev/null 2>&1 </dev/null
         (code=killed, signal=TERM)
Main PID: 79935 (code=killed, signal=TERM)

Jan 29 15:47:46 den02mwa systemd[1]: Started Oracle Trace File Analyzer.
Jan 29 15:47:47 den02mwa init.tfa[79935]: Starting TFA..
Jan 29 15:47:48 den02mwa init.tfa[79935]:
    Starting TFA out of init, Should be running in 10 seconds
Jan 29 15:47:48 den02mwa init.tfa[79935]:
    Successfully updated jvmXmx to 128 in TFA...
Jan 29 15:47:56 den02mwa init.tfa[79935]:
    OSWatcher is already deployed at /opt/oracle.ahf/tfa/ext/oswbb
Jan 29 15:47:56 den02mwa init.tfa[79935]:
    Cannot find valid Non root user to run OSWatcher
Jan 29 18:50:41 den02mwa systemd[1]:
    Stopping Oracle Trace File Analyzer...
Jan 29 18:50:41 den02mwa init.tfa[79935]:
    Telemetry not enabled - Not Starting Adapter
Jan 29 18:50:51 den02mwa systemd[1]:
    Stopped Oracle Trace File Analyzer.

Starting TFA Using tfactl

To start the TFA daemon:

tfactl start

Example output:

# tfactl start

Starting TFA..

Created symlink
/etc/systemd/system/multi-user.target.wants/oracle-tfa.service ->
/etc/systemd/system/oracle-tfa.service.

Created symlink
/etc/systemd/system/graphical.target.wants/oracle-tfa.service ->
/etc/systemd/system/oracle-tfa.service.

Waiting up to 100 seconds for TFA to be started..
. . . . .

Successfully started TFA Process..
. . . . .

TFA Started and listening for commands

Stopping TFA Using tfactl

To stop the TFA daemon:

tfactl shutdown

Example output:

# tfactl shutdown

Shutting down TFA

Removed /etc/systemd/system/multi-user.target.wants/oracle-tfa.service.
Removed /etc/systemd/system/graphical.target.wants/oracle-tfa.service.

Successfully shutdown TFA..

Behavior of Oracle Orachk or Oracle Exachk Daemon

Starting with Oracle Autonomous Health Framework (AHF) 23.9, use the reset and unset options to control how Oracle Orachk or Oracle Exachk default schedulers are handled during autostart and autostop operations.

The following commands are available:

Command	Description
exachk -autostart reset	Starts compliance checking and loads the default Oracle Exachk schedulers.
orachk -autostart reset	Starts compliance checking and loads the default Oracle Orachk schedulers.
ahfctl compliance -autostart reset	Starts compliance checking and loads the default schedulers.
exachk -autostop unset	Stops compliance checking and removes all unmodified default Oracle Exachk schedulers.
orachk -autostop unset	Stops compliance checking and removes all unmodified default Oracle Orachk schedulers.
ahfctl compliance -autostop unset	Stops compliance checking and removes all unmodified default schedulers.

Daemon Behavior Through AHF 23.8

Through AHF 23.8, exachk -autostart, orachk -autostart, ahfctl compliance -autostart, and ahfctl upgrade could modify the scheduler configuration depending on the schedulers present before the operation.

The following table shows the scheduler configuration before and after autostart or an upgrade.

Before autostart or Upgrade	After autostart or Upgrade
Default schedulers	Default schedulers
User-defined + default schedulers	User-defined schedulers
Only user-defined schedulers	Only user-defined schedulers
User-defined + modified default schedulers	User-defined + modified default schedulers
Two default schedulers: one modified and one unmodified	Only the modified default scheduler
Only one of the two default schedulers	Both default schedulers
No schedulers	No schedulers

The following table shows the scheduler configuration before and after autostop.

Before autostop	After autostop
Default schedulers	No schedulers
User-defined + default schedulers	User-defined schedulers only
Only user-defined schedulers	Only user-defined schedulers
User-defined + modified default schedulers	User-defined + modified default schedulers
Two default schedulers: one modified and one unmodified	Only the modified default scheduler
Only one of the two default schedulers	No schedulers
No schedulers	No schedulers

Daemon Behavior Starting with AHF 23.9

Starting with AHF 23.9, normal autostart, autostop, and upgrade operations preserve the existing scheduler configuration.

Running exachk -autostart, orachk -autostart, ahfctl compliance -autostart, or ahfctl upgrade does not alter existing default or user-defined scheduler entries.

Before autostart or Upgrade	After autostart or Upgrade
Default schedulers	Default schedulers
User-defined + default schedulers	User-defined + default schedulers
Only user-defined schedulers	Only user-defined schedulers
User-defined + modified default schedulers	User-defined + modified default schedulers
Two default schedulers: one modified and one unmodified	Two default schedulers: one modified and one unmodified
Only one of the two default schedulers	Only one of the two default schedulers
No schedulers	No schedulers

The same preservation behavior applies when you run autostop followed by a normal autostart: the schedulers that existed before autostop are restored.

Resetting to the Default Schedulers

Use -autostart reset when you want to discard the existing scheduler configuration and load only the default schedulers.

For example:

exachk -autostart reset

or:

orachk -autostart reset

Regardless of the scheduler configuration before the command, the resulting configuration contains the default schedulers:

Before -autostart reset	After -autostart reset
Default schedulers	Default schedulers
User-defined + default schedulers	Default schedulers
Only user-defined schedulers	Default schedulers
User-defined + modified default schedulers	Default schedulers
Two default schedulers: one modified and one unmodified	Default schedulers
Only one of the two default schedulers	Default schedulers
No schedulers	Default schedulers

Removing Unmodified Default Schedulers

Use -autostop unset to stop compliance checking and remove all unmodified default schedulers.

For example:

exachk -autostop unset

or:

orachk -autostop unset

If you subsequently run a normal -autostart, user-defined schedulers and modified default schedulers are preserved, but the removed unmodified default schedulers are not recreated.

Before -autostop unset Followed by -autostart	After -autostart
Default schedulers	No schedulers
User-defined + default schedulers	User-defined schedulers
Only user-defined schedulers	Only user-defined schedulers
User-defined + modified default schedulers	User-defined + modified default schedulers
Two default schedulers: one modified and one unmodified	Only the modified default scheduler
Only one of the two default schedulers	No schedulers
No schedulers	No schedulers

Choosing the Appropriate Operation

Use the following table to determine which combination to use:

Operation	Result
-autostop, then -autostart	Stops compliance checking without removing the scheduler configuration. Starting it again restores the schedulers that existed before autostop.
-autostop unset, then -autostart	Stops compliance checking and removes unmodified default schedulers. Starting it again loads any remaining user-defined and modified default schedulers.
-autostop, then -autostart reset	Stops compliance checking. Starting with reset discards the previous scheduler configuration and loads only the default schedulers.
-autostop unset, then -autostart reset	Stops compliance checking and removes unmodified default schedulers. Starting with reset loads only the default schedulers.

Removing Default Schedulers and Restoring Them

The following example removes the unmodified default Oracle Exachk schedulers and then restores the default configuration:

# exachk -autostop unset

Removing exachk cache discovery....
Successfully completed exachk cache discovery removal.
Successfully copied Daemon Store to Remote Nodes

# exachk -autostart reset

Successfully copied Daemon Store to Remote Nodes
exachk is using TFA Scheduler. TFA PID: 113253
Daemon log file location is :
/opt/oracle.ahf/data/test-server/exachk/user_root/output/exachk_daemon.log

# exachk -get all

------------------------------------------------------------
Scheduled runs:
------------------------------------------------------------
ID: exachk.autostart_client_exatier1
------------------------------------------------------------
AUTORUN_FLAGS  =  -usediscovery -profile exatier1 -dball -showpass -tag autostart_client_exatier1 -readenvconfig
AUTORUN_SCHEDULE  =  3 2 * * 1,2,3,4,5,6
COLLECTION_RETENTION  =  7
------------------------------------------------------------

------------------------------------------------------------
ID: exachk.autostart_client
------------------------------------------------------------
AUTORUN_FLAGS  =  -usediscovery -tag autostart_client -readenvconfig
AUTORUN_SCHEDULE  =  3 3 * * 0
COLLECTION_RETENTION  =  14
------------------------------------------------------------

Removing the Default Schedulers

The following example removes the unmodified default schedulers:

# exachk -autostop unset

Removing exachk cache discovery....
Successfully completed exachk cache discovery removal.
Successfully copied Daemon Store to Remote Nodes

# exachk -get all

No scheduler for any ID

Loading the Default Schedulers

The following example uses -autostart reset to load the default Oracle Exachk schedulers:

# exachk -autostart reset

Successfully copied Daemon Store to Remote Nodes
exachk is using TFA Scheduler. TFA PID: 113253
Daemon log file location is :
/opt/oracle.ahf/data/test-server/exachk/user_root/output/exachk_daemon.log

# exachk -get all

------------------------------------------------------------
Scheduled runs:
------------------------------------------------------------
ID: exachk.autostart_client_exatier1
------------------------------------------------------------
AUTORUN_FLAGS  =  -usediscovery -profile exatier1 -dball -showpass -tag autostart_client_exatier1 -readenvconfig
AUTORUN_SCHEDULE  =  3 2 * * 1,2,3,4,5,6
COLLECTION_RETENTION  =  7
------------------------------------------------------------

------------------------------------------------------------
ID: exachk.autostart_client
------------------------------------------------------------
AUTORUN_FLAGS  =  -usediscovery -tag autostart_client -readenvconfig
AUTORUN_SCHEDULE  =  3 3 * * 0
COLLECTION_RETENTION  =  14
------------------------------------------------------------