HPA Metrics summary External API metrics

The External API endpoints /external-api/hosts and /external-api/hosts/cpu are built only from the metrics of the environment’s HpaInfrastructure agent, whose process is named after the environment (e.g. hex-perf20|cal18ds|HpaInfrastructure). Two trees of that agent are read:

  • SystemEdge: one branch per machine, SystemEdge|<host>|...;
  • Oracle (Oracle only): one branch per database, Oracle Databases|<database host>|<database name>|..., and one branch per Oracle RAC instance, Oracle RAC @ <database name>|Instances|<instance>|....

Prerequisites: the HpaInfrastructure agent with its SystemEdge extension, and its Oracle / Oracle RAC extensions for database hosts, with the grants listed in the Oracle agent installation (v_$osstat / gv_$osstat included).

Metric sources

A host is listed only when its CPU metric (column Listed by) has a value during the requested period. Each field holds the last value of its metric over that period, null when the metric does not exist for that kind of host. For the CPU usage, samples recorded while the agent was not reporting (zero count) are ignored: a bucket made only of such samples is null, not 100 %.

Host type Listed by (CPU metric) name cpu_model cpu_count ram_in_kb db_host CPU usage (/hosts/cpu)
SystemEdge machine SystemEdge|<host>|CPU:TotalIdlePercent <host>, see naming <description> of SystemEdge|<host>|HostResources|DeviceName|<description>:Device Status SystemEdge|<host>|CPU:Processor Count SystemEdge|<host>|Memory:Total Memory (KBytes) false 100 - SystemEdge|<host>|CPU:TotalIdlePercent
Oracle database Oracle Databases|<database host>|<database name>|Resource Utilization:Host CPU Utilization (%) <database host> null null Oracle Databases|<database host>|<database name>|Operating System:Physical Memory (in GB) x 1024 x 1024 true ...|Resource Utilization:Host CPU Utilization (%)
Oracle RAC instance Oracle RAC @ <database name>|Instances|<instance>|Resource Utilization:Host CPU Utilization (%) <instance>-instance-<rank>, see naming null null Oracle RAC @ <database name>|Instances|<instance>|Operating System:Physical Memory (in GB) x 1024 x 1024 true ...|Resource Utilization:Host CPU Utilization (%)

Notes:

  • cpu_count is the number of logical CPUs, not sockets.
  • cpu_model is the first DeviceName naming a CPU vendor (Intel, AMD, Xeon, EPYC, Opteron, Ryzen, ARM), e.g. GenuineIntel, 4 cores. The other devices, such as Linux System Linux workstation/server, are ignored.
  • Host CPU Utilization (%) is the CPU usage of the whole database host, the same measure as 100 - TotalIdlePercent for a SystemEdge machine. Resource Utilization:CPU Usage Per Sec (%), the share of the host CPU used by Oracle itself, is not exposed by the External API.
  • The Oracle Host Name and Instance Name metrics are string events, not stored: host names are always read from the metric path.

Naming

  • SystemEdge machine: SystemEdge runs on the HpaInfrastructure agent’s own machine. When the <host> segment matches the agent host (case and domain ignored), it is kept as is. Otherwise, e.g. SystemEdge|127.0.0.1, the host is named after the agent host.
  • Oracle database: the database host configured in the Oracle collector, often an IP address (e.g. 10.0.10.21). Several databases on the same host give a single entry.
  • Oracle RAC instance: the path carries no host, and the instance id is not exposed by the collector. The name is <instance>-instance-<rank>, where <rank> is the position of the instance within its RAC, in instance name order, starting at 1 (e.g. PROD1-instance-1, PROD2-instance-2). An instance without CPU data during the period is not counted, so the ranks of the following instances shift.

Database hosts and SystemEdge machines are never merged: an Oracle database host is always named differently from the SystemEdge machines.