@@@@Platform-“OnPrem”

@@@@Product-“Database”

@@@@ReleaseVersion-“26.11”

@@@@info-map-label-“Start Using Oracle Autonomous Health Framework”

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:

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:

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="test-user1@example.com test-user2@example.com"

    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

  1. 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 : test-user1@example.com test-user2@example.com

Removing Notification Email Addresses

  1. 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=some.person@acompany.com,another.person@acompany.com"

For Oracle Exachk:

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

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=some.person@acompany.com,another.person@acompany.com"

For Oracle Exachk:

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

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:dba@example.com

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=admin@example.com

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:

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:

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