Start Using Oracle Autonomous Health Framework

2.6 Start Using Oracle Autonomous Health Framework

Understanding the Directory Structure
Review the list of key Oracle Autonomous Health Framework directories.
Configuring Oracle Trace File Analyzer and Oracle Orachk/Oracle Exachk to Use the Same Notification Addresses
Configure notification emails to notify the recepients the results of Oracle Orachk and Oracle Exachk compliance checking, or when Oracle Trace File Analyzer detects significant faults.
Oracle Trace File Analyzer Command-Line and Shell Options
The tfactl tool functions as a command-line interface, shell interface, and menu interface.
Manage Oracle Trace File Analyzer and Oracle Orachk Daemons Using systemctl Commands
Run the systemctl commands as root user on an Oracle Linux server. You can also start/stop Oracle Trace File Analyzer daemon using the tfactl shutdown and tfactl start commands.
Behavior of Oracle Orachk or Oracle Exachk Daemon
AHF 23.9 includes a new command option reset to change the behavior of Oracle Orachk or Oracle Exachk daemon during autostart, autostop, and upgrade.

Parent topic: Get Started

2.6.1 Understanding the Directory Structure

Review the list of key Oracle Autonomous Health Framework directories.

Table 2-9 Key Oracle Autonomous Health Framework Directories

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`	JRE home directory.
`AHF_LOC/common`	Oracle Autonomous Health Framework common directory that contains libraries, ACR, ORDS, and so on.
`AHF_LOC/bin`	Directory that contains Oracle Autonomous Health Framework binaries including the command-line interface `tfactl` and `orachk`.
`AHF_LOC/analyzer`	Oracle Autonomous Health Framework Analyzer directory.
`AHF_LOC/data`	Oracle Autonomous Health Framework data directory contains data generated by Oracle Autonomous Health Framework components such as configuration files, Berkeley DB (BDB), Index data, and so on.
`AHF_LOC/tfa`	Oracle Trace File Analyzer home directory.
`DATA_DIR`	Directory where Oracle Autonomous Health Framework stores diagnostic collections and Metadata.
`DATA_DIR/repository`	Directory where Oracle Autonomous Health Framework stores diagnostic collections.
`DATA_DIR/HOST/diag`	This directory contains logs from all components.

Parent topic: Start Using Oracle Autonomous Health Framework

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

Configure notification emails to notify the recepients the results of Oracle Orachk and Oracle Exachk compliance checking, or when Oracle Trace File Analyzer detects significant faults.

Use the ahfnotificationaddress option to configure Oracle Trace File Analyzer and Oracle Orachk/Oracle Exachk to use the same notification addresses.

Specify a space-delimited list of email addresses.
```
# tfactl set ahfnotificationaddress="id1 id2..."
```
You use the tfactl set ahfnotificationaddress command to set or update the existing list of email addresses.

If you specify the email addresses while installing Oracle Autonomous Health Framework, then Oracle Autonomous Health Framework persists those email addresses in the install.properties file. Oracle Orachk and Oracle Exachk pick those email addresses from the install.properties file, and then updates the NOTIFICATION_EMAIL property for scheduled jobs. However, if you explicitly specify email addresses while creating jobs, then Oracle Orachk and Oracle Exachk override the email addresses in the install.properties file. By default, Oracle Trace File Analyzer does not set notification emails using the email addresses in the install.properties file; instead, you will have to explicitly specify the email addresses.
```
# tfactl set ahfnotificationaddress="test-user1@example.com test-user1@example.com"
Successfully set the AHF Notification Address
```
Run the orachk -get NOTIFICATION_EMAIL and exachk -get NOTIFICATION_EMAIL commands to view the list of notification email addresses set for Oracle Orachk and Oracle Exachk scheduled jobs.

To get the list of notification emails:

# tfactl get ahfnotificationaddress

Fetches and displays the list of notification email IDs from the install.properties file.

# tfactl get ahfnotificationaddress
AHF Notification Address : test-user1@example.com test-user1@example.com

To unset notification emails:

# tfactl unset ahfnotificationaddress

Removes the notification email IDs from the install.properties file.

# tfactl unset ahfnotificationaddress
Successfully unset the AHF Notification Address

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

For Oracle Orachk/Oracle Exachk:

Specify a comma-delimited list of email addresses, as follows:

$ orachk –set "NOTIFICATION_EMAIL=some.person@acompany.com,another.person@acompany.com"

$ exachk –set "NOTIFICATION_EMAIL=some.person@acompany.com,another.person@acompany.com"

Optionally, you can specify the name of the profile. If you do not specify, then id=DEFAULT. For example:

$ orachk -id dba -set "NOTIFICATION_EMAIL=some.person@acompany.com,another.person@acompany.com"

$ exachk -id dba -set "NOTIFICATION_EMAIL=some.person@acompany.com,another.person@acompany.com"

For Oracle Trace File Analyzer:

To set the notification email for a specific ORACLE_HOME, include the operating system owner in the command:

$ tfactl set notificationAddress=os_user:email

To set the notification email for any ORACLE_HOME:

$ tfactl set notificationAddress=email

2.6.3 Oracle Trace File Analyzer Command-Line and Shell Options

The tfactl tool functions as a command-line interface, shell interface, and menu interface.

Table 2-10 Oracle Trace File Analyzer Interfaces

Interface	Command	How to use
Command-line	`$ tfactl command`	Specify all command options at the command line.
Shell interface	`$ tfactl`	Set and change the context and then run commands from within the shell.
Menu Interface	`$ tfactl menu`	Select the menu navigation options and then choose the command that you want to run.

Using tfactl, you can:

Run administration commands
Collect diagnostic data
Analyze diagnostic data collection

Running tfactl commands depends upon the level of access you have to tfactl. Run the administration commands as root or sudo. Or, run a subset of commands as:

An Oracle Database home owner or Oracle Grid Infrastructure home owner.
A member of OS DBA or ASM groups.

To grant other users access to tfactl:

tfactl access

To use tfactl as a command-line tool:

tfactl [command][options]

To use tfactl as a shell interface, enter tfactl, and then run the commands as needed:

$ tfactl
tfactl>

Append the -help option to any of the tfactl commands to obtain command-specific help.

$ tfactl [command] -help

2.6.4 Manage Oracle Trace File Analyzer and Oracle Orachk Daemons Using systemctl Commands

Run the systemctl commands as root user on an Oracle Linux server. You can also start/stop Oracle Trace File Analyzer daemon using the tfactl shutdown and tfactl start commands.

systemctl status oracle-tfa.service
systemctl start oracle-tfa.service
systemctl stop oracle-tfa.service

# 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.

# 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

# 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..

Parent topic: Start Using Oracle Autonomous Health Framework

2.6.5 Behavior of Oracle Orachk or Oracle Exachk Daemon

AHF 23.9 includes a new command option reset to change the behavior of Oracle Orachk or Oracle Exachk daemon during autostart, autostop, and upgrade.

Command Description

Command	Description
`exachk -autostart reset` `orachk -autostart reset` `ahfctl compliance -autostart reset`	Starts and loads the default schedulers.
`exachk -autostop unset` `orachk -autostop unset` `ahfctl compliance -autostop unset`	Removes all default unmodified schedulers.

exachk -autostart reset

orachk -autostart reset

ahfctl compliance -autostart reset

Starts and loads the default schedulers.

exachk -autostop unset

orachk -autostop unset

ahfctl compliance -autostop unset

Removes all default unmodified schedulers.

Daemon behavior until AHF 23.8

The behavior of exachk -autostart, orachk -autostart, ahfctl compliance -autostart, and ahfctl upgrade are the same. The table below illustrates different scenarios of schedulers and their behavior before and after autostart and upgrade.

Before autostart/upgrade	After autostart/upgrade
Default schedulers	Default schedulers
User-defined + default schedulers	User-defined
Only user-defined	Only user-defined
User-defined + modified default schedulers	User-defined + modified default schedulers
2 default schedulers: One modified default and the other is not	Only modified default scheduler
Only one default scheduler out of 2 default schedulers	Both default schedulers
No schedulers	No schedulers

The table below illustrates different scenarios of schedulers and their behavior before and after exachk -autostart, orachk -autostart, and ahfctl compliance -autostart.

Before autostop	After autostop
Default schedulers	No schedulers
User-defined + default schedulers	User-defined schedulers only
Only user-defined	Only user-defined
User-defined + modified default schedulers	User-defined + modified default schedulers
2 default schedulers: One modified default and the other is not	Only modified default scheduler
Only one default scheduler out of 2 default schedulers	No scheduler
No scheduler	No scheduler

Daemon behavioral changes in AHF 23.9

The behavior of exachk -autostart, orachk -autostart, ahfctl compliance -autostart, and ahfctl upgrade remains the same as in AHF 23.8. There will be no changes to the scheduler entries be it default schedulers or user-defined schedulers.

Before autostart/upgrade or autostop and then autostart	After autostart/upgrade or autostop and then autostart
Default schedulers	Default schedulers
User-defined + default schedulers	User-defined + default schedulers
Only user-defined	Only user-defined
User-defined + modified default schedulers	User-defined + modified default schedulers
2 default schedulers: One modified default and the other is not	2 default schedulers: One modified default and the other is not
Only one default scheduler out of 2 default schedulers	Only one default scheduler out of 2 default schedulers
No schedulers	No schedulers

The table below illustrates the behavior after autostart reset.

Before -autostart reset	After -autostart reset
Default schedulers	Default schedulers
User-defined + default schedulers	Default schedulers
Only user-defined	Default schedulers
User-defined + modified default schedulers	Default schedulers
2 default schedulers: One modified default and the other is not	Default schedulers
Only one default scheduler out of 2 default schedulers	Default schedulers
No schedulers	Default schedulers

The table below illustrates the behavior when autostop unset is run and then autostart.

Before -autostop unset and then autostart	After -autostop unset and then autostart
Default schedulers	No schedulers
User-defined + default schedulers	User-defined
Only user-defined	Only user-defined
User-defined + modified default schedulers	User-defined + modified default schedulers
2 default schedulers: One modified default and the other is not	Only modified default scheduler
Only one default scheduler out of 2 default schedulers	No schedulers
No schedulers	No schedulers

Use Cases

Use case	Outcome
`-autostop` and then `-autostart`	`autostop` will only deconfigure the compliance and autostart will start the compliance and load all the schedulers that were present before `autostop`.
`-autostop unset` and then `-autostart`	`autostop unset` will deconfigure the compliance and remove all the default unmodified schedulers and `autostart` will start the compliance and load the user-defined schedulers and modified default schedulers if they exist.
`-autostop` and then `-autostart reset`	`autostop` will only deconfigure the compliance and `autostart reset` will start the compliance and only load the default schedulers.
`-autostop unset` and then `-autostart reset`	`autostop unset` will deconfigure the compliance and remove all the default unmodified schedulers and `autostart reset` will start the compliance and only load the default schedulers.

Example 2-28 exachk -autostop unset, exachk -autostart reset, and exachk -get all

# 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
------------------------------------------------------------

Example 2-29 exachk -autostop unset and exachk -get all

# 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

Example 2-30 exachk -autostart reset and exachk -get all

# 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
------------------------------------------------------------

Parent topic: Start Using Oracle Autonomous Health Framework