9.5.2 ahf analysis

Use the ahf analysis command to generate AHF Insights, AHF Balance reports, and activity-specific Alert Histories.

AHF 25.11

AHF 25.11 introduces a new capability that generates activity-specific Alert Histories, providing a unified and detailed timeline of actions occurring across AHF-monitored components. This feature enhances diagnostic capabilities, accelerates troubleshooting, and improves overall system observability.

Consolidated Timeline of Actions

Oracle Database components frequently write to multiple logs and trace files while performing operations or handling exceptions. For example:

  • Shutting down an instance in a Real Application Cluster (RAC) triggers cluster-wide reconfiguration events.
  • A disk rebalance operation consists of several steps, each logged by different components.

The Alert History feature consolidates relevant log and trace entries into a single, coherent timeline for any given activity, enabling users to quickly understand the sequence of events.

Automated Log Parsing and Persistence

AHF continuously monitors required logs and trace files across components. It automatically extracts relevant entries and persists them as Alert Histories. These persisted histories can be easily accessed on demand using the AHF command-line interface (CLI).

Proactive Problem Detection and Alerts

By maintaining activity-specific alert histories, AHF can proactively identify patterns and potential issues. This enables earlier detection of failures, faster response times, and improved system reliability.

Customer Accessibility

  • The feature is enabled by default, requiring no additional setup.
  • Customers can generate activity-specific alert histories using the AHF CLI:
    ahf analysis create --type alert-history <arguments>

Configuring Alert History

The Alert History feature is enabled by default but can be configured using the following command:

ahf configuration set --property ahf.collectors.alert-history --value {on|off}

Behavior Notes:

  • Alert History events are indexed only when the property ahf.collectors.alert-history is set to on.
  • If the property is switched to off, previously generated alert histories remain available and can still be viewed via the CLI.
  • No additional configuration changes are required for the feature to function when enabled.

AHF 24.11

AHF Balance now allows limiting the number of databases included in performance tuning recommendations. This makes it easier to implement gradual configuration changes to enhance performance without overwhelming change management processes.

AI-Driven Tuning with AHF Balance

AHF Balance uses AI to provide tuning recommendations for database CPU_COUNT. Database Administrators (DBAs), Cluster Administrators, and Fleet Administrators can leverage these recommendations to optimize database performance while maximizing hardware utilization.

Enhanced Flexibility for Tuning Recommendations

Previously, AHF Balance considered all databases within a cluster as candidates for CPU_COUNT adjustments. This often led to recommendations for modifying CPU_COUNT on 50 or more databases, posing challenges for implementing such extensive changes simultaneously.

With the new --limit-db-changes option, AHF Balance enables incremental performance improvement by capping the number of databases included in tuning recommendations. This allows administrators to make changes in manageable stages through successive iterations of tuning.

Note:

Before running the ahf analysis command with the --type impact option, ensure that you first run the configuration command: ahf configuration set --type impact --user-name USER_NAME --connect-string CONNECT-STRING

This step is necessary to set up the required connection details before performing the analysis.

Command Usage Examples
  • Fleet Analysis:
    To perform an analysis for a fleet and limit the number of database changes across clusters, use:
    ahf analysis create --type impact --scope fleet --name <fleet-name> --limit-db-changes <positive-integer-number-of-databases>
  • Cluster Analysis:
    To perform an analysis for a specific cluster and limit the number of database changes, use:
    ahf analysis create --type impact --scope cluster --name <cluster-name> --limit-db-changes <positive-integer-number-of-databases>
  • Database Analysis within a Cluster:
    To perform an analysis for a specific database within a cluster, use:
    ahf analysis create --type impact --scope database --name <db-name> --cluster <cluster-name> --limit-db-changes <positive-integer-number-of-databases>

By limiting database changes, AHF Balance provides a more controlled and efficient approach to performance tuning, ensuring smoother implementation and improved results.

AHF 23.8

Starting in AHF 23.8, you will be able to upload AHF Insights report automatically if Object Store is configured as part of AHF. Uploading AHF Insights reports helps Oracle Cloud Operations to identify, investigate, track, and resolve system health issues and divergences in best practice configurations quickly and effectively.

Oracle Autonomous Database on Dedicated Exadata Infrastructure and Oracle SaaS

To set REST endpoints (Object Store's), run:
ahfctl setupload -name oss -type https -user <user> -url <object_store> -password
To upload AHF Insights report to Object Store, run: 
ahf analysis create --type insights
.

ahf analysis create

ahf analysis create [-h] [--type {insights|impact}] [[--last n{m|h} [--refresh] | --for DATETIME | --from DATETIME --to DATETIME] [--tag TAGNAME] | [--scope SCOPE --name NAME --cluster CLUSTER --clusters CLUSTER_LIST]][--output-file PATH] [--to-json]
ahf analysis create [-h] [--type {alert-history|patch-summary|capacity|insights|impact}] [--component COMPONENT] [--last n{m|h} | --from DATETIME --to DATETIME] [--instance INSTANCE] [--database DATABASE] [--from DATETIME --to DATETIME] [--diskgroup DISK_GROUP] [--disknumber DISK_NUMBER] [--diskname DISK_NAME] [--severity SEVERITY] [--scenario SCENARIO] [--metric METRIC --cluster CLUSTER] [--nodes NODES] [--from DATETIME --to DATETIME] [--last n{m|h} [--refresh] | --for DATETIME | --from DATETIME --to DATETIME] [--tag TAGNAME] [--scope SCOPE --name NAME --cluster CLUSTER --clusters CLUSTER_LIST] [--output-file PATH]

Syntax: AHF Balance

ahf analysis create [-h] --type impact --scope [fleet|cluster|database] [--cluster CLUSTER_NAME] [--clusters space-delimited list of clusters
] [--em-group] --name NAME

Parameters

Table 9-125 ahf analysis create --type impact Command Parameters

Parameter Description

-h, --help

Show this help and exit.

--type impact

 Specify the type of report to generate.

--scope [fleet|cluster|database]

Specify to generate AHF Balance reports - Fleet Report, Cluster Report, and Database Report

Specify the --scope and --name options to create an impact analysis.

The --cluster option is required for database impact analysis.

--output-file PATH

Specify to create output file in the specified location.

--clusters clu1 clu2 clu3

Specify a space-delimited list of clusters to include in the fleet scope.

--name NAME

Specify the name of the fleet, EM Group, cluster, or database to report on.

Note:

The name of the fleet can be anything of your choosing, such as 'MyFleet'. It is only used to label the report.

--em-group

Specify the EM group name.

Note:

This option is mutually exclusive with the --clusters option and must be used with the --scope fleet option.
For example: 
ahf analysis create --type impact --scope fleet --name <em-group-name> --em-group

--user-name USER_NAME

Specify the Oracle Enterprise Manager Repository user name.

Note:

Not required if AHF Balance has been configured. For more information, see ahf configuration.

--connect-string CONNECT_STRING

Specify the connect string for the Oracle Enterprise Manager Repository.

Note:

Not required if AHF Balance has been configured. For more information, see ahf configuration.

--limit-db-changes DB_CHANGE_LIMIT

Limits the number of database changes recommended.

Syntax: AHF Insights

ahf analysis create [-h] --type insights [--last n{m|h} | --for DATETIME | --from DATETIME --to DATETIME] [--refresh] [--tag TAGNAME
]

Parameters

Table 9-126 ahf analysis create --type insights Command Parameters

Parameter Description

-h, --help

Show this help and exit.

--type insights

 Specify the type of report to generate.

--last n{m|h}

Specify the --last parameter to analyze data for the past number of minutes (m) or hours (h).

--last cannot be greater than 12 hours.

--for <DATETIME>

Specify the --for parameter to analyze data for a 2 hour period before and after the timestamp specified.

Supported time formats:
"YYYY-MM-DDTHH:MM:SS"
"YYYY-MM-DD HH:MM:SS"

--from <DATETIME>

--to <DATETIME>

Specify the --from and --to parameters (you must use these two parameters together) to analyze data for a specific time interval.

Supported time formats:
"YYYY-MM-DDTHH:MM:SS"
"YYYY-MM-DD HH:MM:SS"
"YYYY-MM-DD"

Time difference between from and to time should not be more than 4 hours.

--refresh

Provides fresh data from AHF Insights sources.

Specify --refresh alone or together with --last to provide fresh data from AHF Insights sources.

--include-cell-data

Specify to include data from cell into AHF Insights sources.

--tag TAGNAME

Specify to collect the files into the TAGNAME directory inside the repository.

Syntax: ahf analysis explore

ahf analysis explore [-h] [--with scope] [--from-file FILE]

Note:

Starting with Oracle AI Database 26ai, the ahf analysis explore --with scope command is desupported. For more information on GIMR, refer to Analyze Issue Root Cause.

Parameters

Table 9-127 ahf analysis explore Command Parameters

Parameter Description

-h, --help

Show this help and exit.

--from-file FILE

Specify to read from a file.

If you do not specify the file extension, then AHF Scope assumes .mdb as the file extension.

Syntax: AHF Alert History

ahf analysis create [-h] [--type {alert-history|patch-summary|capacity|insights|impact}] [--component COMPONENT] [--last n{m|h} | --from DATETIME --to DATETIME] [--instance INSTANCE] [--database DATABASE] [--from DATETIME --to DATETIME] [--diskgroup DISK_GROUP] [--disknumber DISK_NUMBER] [--diskname DISK_NAME] [--severity SEVERITY] [--scenario SCENARIO] [--metric METRIC --cluster CLUSTER] [--nodes NODES] [--from DATETIME --to DATETIME] [--last n{m|h} [--refresh] | --for DATETIME | --from DATETIME --to DATETIME] [--tag TAGNAME] [--scope SCOPE --name NAME --cluster CLUSTER --clusters CLUSTER_LIST] [--output-file PATH]

Parameters

Table 9-128 ahf analysis create --type alert history Command Parameters

Parameter Description

-h, --help

Show this help and exit.

--to-json

Display the output in JSON format.

--component COMPONENT

Specify the component to analyze. Currently, only the ASM component is supported for Alert History.

--instance INSTANCE

Filter results by instance name.

--diskgroup DISK_GROUP

Specify the name of the ASM disk group.

--disknumber DISK_NUMBER

Specify the disk number within the ASM disk group.

--diskname DISK_NAME

Specify the disk name within the ASM disk group.

--severity SEVERITY

Filter alerts by severity. Supported values are: info, warning, error.

--scenario SCENARIO

Specify the scenario name.

--from DATETIME

Analyze data from the specified start time. Accepts the following formats:

  • "YYYY-MM-DDTHH:MM:SS[Z]"
  • "YYYY-MM-DD HH:MM:SS"
  • "YYYY-MM-DD"

--to DATETIME

Analyze data up to the specified end time. Accepts the same formats as the --from option.

--last n{m|h|d}

Analyze data from the last 'n' minutes (m), hours (h), or days (d).

Command Usage Examples

Use these options to create an Alert History analysis for a specific component, time range, or resource:

[--component COMPONENT] [--instance INSTANCE]
[--from DATETIME --to DATETIME]
[--diskgroup DISK_GROUP] [--disknumber DISK_NUMBER] [--diskname DISK_NAME]
[--severity SEVERITY] [--scenario SCENARIO]

You can filter alert history by component, instance, disk group, disk number, disk name, severity, and scenario.

Note:

  • Disks in different disk groups may share the same name. It is recommended to use --diskname together with --diskgroup.
  • Disk numbers may also overlap across disk groups. Use --disknumber with --diskgroup to ensure accurate filtering.
  • Create an alert history analysis for a specific time range:
    ahf analysis create --type alert-history --from 2022-10-10T14:00:00Z --to 2022-10-10T15:30:00Z
  • Filter by component and instance:
    ahf analysis create --type alert-history --component ASM --instance +asm1
  • Filter by disk group and severity:
    ahf analysis create --type alert-history --diskgroup DG1 --severity info

Important:

  • Alert History message generation is currently supported only for the ASM component.
  • The following scenarios are supported in this release: dismount, dismount_force, offline, and mount.
  • Alert History is available only for time ranges within the last 30 days.

Example 9-125 AHF Insights Analysis Usage Examples

Specify [--last | --for | --from --to] to create an analysis for a given period of time. Maximum time interval allowed is 4 hrs.

Specify [--refresh] alone or together with [--last] to provide fresh data from AHF Insights sources.

  • Create analysis report from the data collected in the last 3 hours:
    ahf analysis create --type insights --last 3h
  • Create analysis for a 2-hour period centered at the specified timestamp:
    ahf analysis create --type insights --for 2022-10-10T14:00:00
  • Create analysis for a given time range:
    ahf analysis create --type insights --from 2022-10-10T14:00:00 --to 2022-10-10T15:30:00
  • Create analysis specifying a timezone:
    ahf analysis create --type insights --from 2022-10-10T14:00:00 --to 2022-10-11T13:30:00
  • Create analysis with most recent data:
    ahf analysis create --type insights --refresh
  • Create analysis with a tag:
    ahf analysis create --type insights --tag my_tag

Example 9-126 AHF Balance Usage Examples

Specify [--scope] and [--name] options to create an impact analysis.

The [--cluster] option is required for database impact analysis.

  • Create analysis for a fleet (all clusters):
    ahf analysis create --type impact --scope fleet --name fleet1
  • Create analysis for a fleet (cluster list):
    ahf analysis create --type impact --scope fleet --name fleet1 --clusters clu1 clu2 clu3
  • Create analysis for a cluster:
    ahf analysis create --type impact --scope cluster --name cluster1
  • Create analysis for a database:
    ahf analysis create --type impact --scope database --cluster cluster1 --name database1
  • Create analysis specifying the output directory:
    ahf analysis create --type impact --scope fleet --name fleet1 --output-file /custom_path/custom_name.html
  • Create analysis specifying EM repository user name and password:
    ahf analysis create --type impact --scope fleet --name fleet1 --user-name oracle --connect-string <cs>

Example 9-127 AHF Alert History Usage Examples

  • Create an alert history analysis for a specific disk group mount event:
    # ahf analysis create --type alert-history --scenario mount
Alert Summary:
Host : hostname1
-----------------------
[2025-10-22T05:00:48.128+00:00] [INFO] [+ASM1] Diskgroup 1 (DATAC2): Mounted with the following properties
                                                 Redundancy Type: high
                                                 compatible.asm: 11.2.0.4.0
                                                 compatible.rdbms: 11.2.0.3.0
                                                 Mount Incarnation: 0x0D57CFC0
                                                 Creation timestamp: 2024/11/06 22:57:08

Host : hostname2
-----------------------
No alert history found for input parameters
  • Create an alert history analysis for ASM disk offline events in a specific disk group:
    # ahf analysis create --type alert-history --component ASM --scenario offline --severity info --diskname DATAFILE --diskgroup 2
Alert Summary:
Host : hostname
---------------
[2024-10-05T10:23:12.775+00:00] [INFO] [aime111]    Diskgroup 2 (DATAFILE): Disk 0 (DATAFILE0) is being offlined because x000 process with OS PID 13420 is expelling the disk from the diskgroup
[2024-10-05T10:23:18.775+00:00] [INFO] [aime111]    Diskgroup 2 (DATAFILE): Disk 0 (DATAFILE_0000) is being offlined because r000 process with OS PID 24167 could not read from the disk when repairing ASM file 9 extent 0

Parent topic: Running Unified AHF CLI Administration Commands