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). Three groups of metrics 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>|...;
• Hpa|Cpu: the CPU inventory of the agent’s own machine, Hpa|Cpu:Model and Hpa|Cpu:Sockets Count.

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). cpu_model and cpu_socket_count also need an agent reporting the Hpa|Cpu metrics: an older agent leaves cpu_socket_count null, and cpu_model falls back to the SystemEdge device name.

Metric sources

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

Host type	Listed by (CPU metric)	name	cpu_model	cpu_count	cpu_socket_count	ram_in_kb	db_host	CPU usage (/hosts/cpu)
SystemEdge machine	SystemEdge|<host>|CPU:TotalIdlePercent	<host>, see naming	live value of Hpa|Cpu:Model, else <description> of SystemEdge|<host>|HostResources|DeviceName|<description>:Device Status	SystemEdge|<host>|CPU:Processor Count	last value of Hpa|Cpu:Sockets Count of the agent host	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 (%)	live value of Oracle Databases|<database host>|<database name>:Host Name, else <database host>, see naming	null	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 (%)	live value of Oracle RAC @ <database name>|Instances|<instance>:Host Name, else <instance>-instance-<rank>, see naming	null	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 (hardware threads), not sockets.
• cpu_socket_count is the number of CPU sockets (virtual sockets on a VM, often one per vCPU), i.e. the last value of Hpa|Cpu:Sockets Count, reported by the HpaInfrastructure agent for its own machine and attached to the host named after that agent host. It is null when the agent does not report it (agent older than this metric) or when the host is not an agent machine.
• cpu_model is the live value of Hpa|Cpu:Model, reported by the HpaInfrastructure agent for its own machine, e.g. Intel(R) Xeon(R) CPU E3-1240 v6 @ 3.70GHz. Without it (older agent, failed read), it 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 the CPU usage of the database process, see Process CPU.
• When one entry gathers several CPU metrics (several databases on one machine, a database host merged into a SystemEdge machine), the lowest value of each bucket is kept.

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 and RAC instance: the value of the instance’s Host Name metric, the machine name reported by Oracle (V$INSTANCE.HOST_NAME), e.g. sd-138994. This metric is a string event, which is not stored: its value is read live from the Enterprise Manager, over the last 2 minutes. The current name is therefore applied whatever the requested period.
• Without live value (agent not reporting for 2 minutes, database down, Enterprise Manager extension unreachable or older than the HPA server), the name is read from the metric path:
  • Oracle database: the database host configured in the Oracle collector, often an IP address (e.g. 10.0.10.21);
  • 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.

Databases and RAC instances running on the same machine give a single entry. Names are compared with case and domain ignored (SD-138994 and sd-138994.corp.local are the same machine), an IP address being compared whole. The entry shows the first name in alphabetical order, and the RAM of its first database reporting one. A RAC spread over several machines gives one entry per machine.

A database host named like a SystemEdge machine (same comparison) is merged into it: the entry keeps the SystemEdge name, cpu_model, cpu_count, cpu_socket_count and ram_in_kb (the Oracle RAM is used only when SystemEdge reports none), and db_host is true.

Entries are listed SystemEdge machines first, by name, then the other database hosts, by name.

Process CPU

/external-api/processes/cpu also reads the HPA agents of the environment. Every value is a share of the whole machine, the same scale as the host CPU usage.

Process type	process	CPU usage	Host
JVM (JVM)	agent name, restart suffix (%1) dropped, e.g. DataServer	CPU:Utilization % (process) of the agent	agent host, named as by /hosts when it lists that machine (case and domain ignored)
Oracle database (DB)	<database name>, e.g. CAL18DS	Oracle Databases|<database host>|<database name>|Resource Utilization:CPU Usage Per Sec (%)	the /hosts entry of the database
Oracle RAC instance (DB)	<database name>|<instance>, e.g. CAL18DSR|CAL18DSR	Oracle RAC @ <database name>|Instances|<instance>|Resource Utilization:CPU Usage Per Sec (%)	the /hosts entry of the instance

Notes:

• JVM: each point is the CPU usage over its whole bucket, Σ(value × count) of the process’ points over the count of the bucket fully reported. That full count is the highest count among every JVM of the environment at each 15 s (6 samples for a JVM running the whole interval), summed over the bucket (360 for 15 minutes), read by a second evaluation. The part of the bucket a process did not run counts as 0, a monitoring gap is left out.
• Database: Oracle records one value every 30 to 35 seconds, so each point is the database’s average weighted by count. Host CPU is averaged by sample count (DPS metric type VALUE), a gap there being an outage rather than an idle machine.
• The resolution is a multiple of 15 minutes and the period is rounded down to the quarter: stored data is 15 minutes per slice once aged, and agents measure on unaligned 15 s windows.
• CPU Usage Per Sec (%) is Oracle’s CPU Usage Per Sec divided by the number of CPUs of the host.
• An agent with process CPU disabled (introscope.agent.disableProcessCPUUtilization) gives no JVM series.
• Only the databases and RAC instances /hosts lists for the period are read: a database without Host CPU Utilization (%) during the period gives no process.
• Several series of one process (an agent and its restart duplicate, one database monitored by two agents) are merged by adding their value × count over the same full count.