Analyze Issue Root Cause

Autonomous Health Framework Scope (AHF Scope) is a standalone, interactive, real-time capable front-end to Cluster Health Advisor (CHA). AHF Scope requires a very small foot-print on the monitored system.

Note:

The Autonomous Health Framework Scope (AHF Scope) feature of Cluster Health Advisor (CHA) is deprecated in Oracle AI Database 26ai.

To better align with evolving customer needs, Oracle is discontinuing AHF Scope and recommends using Autonomous Health Framework Insights (AHF Insights) as the replacement.

When AHF detects issues such as node evictions, instance evictions, or database performance degradation, it provides a comprehensive report through AHF Insights-highlighting the problem, identifying the root cause, and offering recommended actions.

Additionally, the Database Anomalies Advisor presents a timeline view of anomalies across hosts and database instances. Users can drill down into each finding to understand the underlying cause and suggested resolution.

CHA continuously monitors cluster nodes and Oracle RAC databases for performance and availability issue precursors to provide early warning of problems before they become critical.

Note:

GIMR is optionally supported in Oracle Database 19c. However, it's desupported in Oracle AI Database 26ai. For more information, see Removing Grid Infrastructure Management Repository.

Introduction to AHF Scope

AHF Scope is a lightweight, standalone, interactive front end for Oracle Cluster Health Advisor that supports real-time monitoring through GIMR or offline analysis from archived GIMR data. It is launched with the ahfscope script and is designed for efficient operation by cluster and database experts using keyboard shortcuts, pointer navigation, and contextual menus.

Cluster View - Connecting And Basics Of Monitoring

AHF Scope starts through ahfscope on Linux/UNIX or ahfscope.bat on Windows, using Oracle Wallet services to obtain GIMR connection parameters. After connecting, it presents the top-level Cloud View and exits when the main window is closed.

The default interface combines a navigation tree with an analysis panel containing a system timeline, status line, and entity-specific details. Entities are hierarchically organized under OurCloud, with colors indicating normal, abnormal, missing, or partially missing data; status propagates upward from sub-entities. Users can navigate by selecting tree items, double-clicking focused entities, or pressing Enter, while themes, focus behavior, and persistent display settings support efficient analysis across clusters, hosts, databases, and instances.

Target Entities

CHA supports Host and Instance target entities, each with specialized panels showing an overall state timeline and metric probe histories. Target states use green, yellow, red, and gray to represent normal, probe-level abnormality, diagnosed problems, and missing data; each sample may include observed values, predicted values, probe states, and associated problems. Specialized tabs expose dynamic relationships, such as instances running on hosts, which may change over time independently of the logical navigation hierarchy.

Host Panel

The Host panel provides Host Detail and Instances tabs, showing host status and the time-dependent instances running on it. Because multiple instances may run on one host, the relationship is one-to-many and can include shutdowns or host changes. Users can switch directly to an instance panel by focusing its timeline and pressing Enter, using arrow keys, or double-clicking its name.

An Instance Panel

The Instance panel displays the instance status history and service interruptions, while its Host tab shows the host associated with the instance over time. An instance has a one-to-one relationship with a host at any particular moment, although it may move between hosts. Users can navigate between related hosts and instances through timeline selection, Enter, or double-click actions, with displayed time ranges adapting to the window size.

Browsing Through Time and Pin Operation

Live AHF Scope views continuously advance as new samples arrive, with a cursor marker identifying the current time and abnormal probes. Users can pin a timestamp by double-clicking, pressing p, or using the arrow keys over a target timeline, then fine-tune it with left and right arrows; f restores cursor following. A pinned time is preserved across cluster entities, while Control-assisted cursor movement allows comparison of selected probe values at other timestamps, and live pins are released when they reach the viewport boundary.

Changing the Set of Visible Probes

AHF Scope normally displays only abnormal probes or those associated with a selected problem, but users can switch to all high probes, every probe, correlated probe categories, time-range abnormal probes, or custom probe subsets. Menus and hot keys control these modes, while arrow, page, and mouse-wheel navigation scroll through probes when more signals exist than fit on screen. Probe categories and correlations can be explored through focused timelines or the Expert tab.

Selecting Abnormal Probes in Any Time Range

Users can select a time range by Shift-dragging across a target timeline, activating a filter that displays probes abnormal during the selected interval rather than only at one timestamp. The selection is retained across entities in the cluster, enabling comparisons between hosts or instances. The filter is cleared through the reset option in the context menu or by pressing Escape.

Problems or Anomalies

Red entity states indicate one or more diagnosed problems, each containing an identifier, description, confidence, root cause, corrective actions, associated abnormal probes, inference chains, and optional detailed tables. Problems are ordered primarily by confidence, with KPI-related problems prioritized, and their content may vary by timestamp. Selecting a problem cycles through its description, diagnosis, and supporting probe timelines, while magenta timeline ranges identify periods when the selected problem was active.

Browsing through active time of a problem

When a problem is selected, its active periods appear in magenta on the target timeline. Holding Shift and pressing the left or right arrow key moves the cursor to the previous or next timestamp at which the same problem was reported, allowing rapid review of recurring occurrences.

Expert Mode

Expert mode supports deeper comparison of CHA metric observations with model predictions, helping users assess whether warnings are timely and whether the calibration reflects the monitored workload. It provides additional analytical views beyond Standard mode, particularly for investigating potential false positives, missed diagnoses, and model suitability.

Activating the Expert Mode

Expert mode is enabled with e or through the context menu and adds an Expert tab while changing probe timeline displays. It overlays predicted and observed values, using colors to show probe state, and can instead display residuals: positive differences appear as green regions and negative differences as blue regions. Residual analysis is meaningful only when both predicted and observed values are available and can reveal calibration problems or good model alignment.

Resizing Expert Diagrams

Expert graphs can be vertically zoomed to expose details obscured by automatic scaling. Users place the cursor over the relevant graph and Control-drag with the left mouse button, or use the corresponding Control arrow keys, with graph heights limited to 128 pixels.

Selecting Custom Set of Probes

The Expert tab provides a hierarchical category tree for selecting individual probes or groups of related probes to display. Category relationships are reflected through highlighting, allowing shared probes to be identified and selectively removed. Custom selections can be saved under named configurations, loaded after restarting AHF Scope on the same host, or deleted from persistent storage; selecting a saved set does not activate it until Load is used.

Live and Passive Sessions

AHF Scope maintains a live session for current GIMR metrics and a replay session for historical periods retrieved through the System Timeline. Replay is available only with a GIMR connection; file-based feeds are passive and cannot retrieve additional historical data. Users move the time selector with Shift and mouse or arrow keys, wait for the historical query to complete, and investigate the static replay while live collection continues; moving to the current endpoint or pressing = restores live mode and discards replay data.

ahfscope Console Commands

The ahfscope -i option enables an interactive CLI with commands for listing entities, feeds, metrics, probes, units, missing or flagged values, diagnoses, versions, tracing, zooming, and exiting. Commands support abbreviated prefixes when unambiguous and provide diagnostic summaries or internal data not available through the graphical interface, including feed timing, database tracing, input capture, root-cause output, and topology changes.

List of Hot Keys

AHF Scope hot keys provide mouse-free control for themes, zooming, probe visibility, Expert mode, residual displays, pinning, problem navigation, time filtering, signal scrolling, and live/replay session control. Arrow and page keys navigate entities and signals, Control combinations resize or inspect graphs, and Shift-arrow commands move through problem occurrences or shift the system time selector.

Set of Persistent Settings

AHF Scope persists the selected theme, last start time, details-panel width, window size and position, last probe selection, and named custom probe selections. These settings are associated with a specific user and host and can be reused in subsequent sessions on that host.

Accessibility Aspects

AHF Scope supports complete keyboard operation through Tab, cursor keys, Enter, modifier keys, and hot keys, with no operation timeouts that would prevent use of Sticky Keys or Slow Keys. Its high-contrast, image-free interface supports magnification and does not depend on the operating system’s High Contrast mode. Java accessibility features and JAWS version 17 or later are supported on Microsoft Windows.

Customizing Java Run Time System

Because AHF Scope runs on Java, advanced users can customize JVM behavior through the launch script or _JAVA_OPTIONS. Hardware-accelerated Java 2D rendering through OpenGL or Direct3D can improve display performance, with options available to enable these pipelines and diagnostic output indicating whether acceleration is supported. Rendering behavior may depend on current graphics drivers and, for some hardware, additional framebuffer configuration.

Setting Proper Character Encoding Page On Microsoft Windows

Incorrect Windows console code pages can cause characters such as the Greek micro symbol to display incorrectly in AHF Scope output. Users should check the active code page with chcp and switch from unsuitable defaults such as 437 to a multilingual page such as 850 when necessary.

ahfscope

The ahfscope command launches AHF Scope with options for live GIMR monitoring, file-based replay, interactive CLI access, query configuration, MDB extraction, and debugging. The -f option reads an MDB archive, -i enables interactive commands, -q controls query duration and timing, -C generates JSON without the GUI, and -D enables diagnostic tracing. Without options, AHF Scope connects through JDBC and Oracle Wallet, starts a live session, and initially loads the most recent 60 minutes or the duration configured by -q; archived MDB files can be produced from exported GIMR repository data for offline analysis.
Read More: ahfscope