1. Oracle Autonomous Health Framework User's Guide
  2. ahf analysis

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

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

ahf analysis create --type impact Command Parameters

  • -h, --help
    Show this help and exit.
  • --type impact
    Specify the type of report to generate.
  • --scope [fleet|cluster|database]
    Specify to generate an AHF Balance Fleet Report, Cluster Report, or 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 the 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 fleet name can be any name of your choice, such as MyFleet. It is used only 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:

    This option is not required if AHF Balance has already been configured. For more information, see ahf configuration.

  • --connect-string CONNECT_STRING
    Specify the connect string for the Oracle Enterprise Manager Repository.

    Note:

    This option is not required if AHF Balance has already been configured. For more information, see ahf configuration.

  • --limit-db-changes DB_CHANGE_LIMIT
    Limit the number of recommended database changes.

Syntax: AHF Insights

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

Parameters

ahf analysis create --type insights Command Parameters

  • -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). The value specified with --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 specified timestamp.

    Supported time formats:

    • "YYYY-MM-DDTHH:MM:SS"
    • "YYYY-MM-DD HH:MM:SS"
  • --from <DATETIME>, --to <DATETIME>
    Specify the --from and --to 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"

    The time difference between the --from and --to values must not exceed 4 hours.

  • --refresh
    Provide fresh data from AHF Insights sources. Specify --refresh alone or together with --last.
  • --include-cell-data
    Specify to include cell data in the AHF Insights sources.
  • --tag TAGNAME
    Specify to collect the files into the TAGNAME directory within 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

ahf analysis explore Command Parameters

  • -h, --help
    Show this help and exit.
  • --from-file FILE
    Specify to read from a file. If you do not specify the file extension, 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

ahf analysis create --type alert history Command Parameters

  • -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, and error.
  • --scenario SCENARIO
    Specify the scenario name.

  • --from DATETIME
    Analyze data from the specified start time. Supported formats are:

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

  • 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