Oracle Cloud Infrastructure

Introduction#

Middleware's Oracle Cloud Infrastructure (OCI) integration collects metrics from OCI Monitoring for every tenancy you connect. Use it to monitor compute instances, block volumes, networking, load balancers, object storage, Autonomous Database, MySQL HeatWave, Kubernetes Engine (OKE), Functions and API Gateway, with built-in dashboards for each service.

How it works:

• Middleware reads metrics with read-only access to your tenancy. Nothing is installed in your tenancy.
• Every region your tenancy subscribes to and every compartment in it are discovered automatically, including regions and compartments added later.
• Metrics are collected every 5 minutes at 1-minute resolution. Data appears a few minutes behind real time while OCI finishes ingesting it.
• Each metric carries the resource's name, type, lifecycle state, compartment and OCI tags, so you can filter and group by them.

Integration Setup#

Prerequisites#

• An OCI tenancy and a user who can manage IAM groups, users and policies (for example, a member of the Administrators group).
• Your tenancy's home region. It is shown in the OCI Console under Profile > Tenancy, and is where IAM changes are made.
• To collect compute instance metrics (oci_computeagent), the Compute Instance Monitoring plugin of the Oracle Cloud Agent must be enabled on your instances, and the instances must be able to reach OCI services (through a public IP, a NAT gateway or a service gateway).

Oracle Cloud Configuration#

Middleware needs a user in your tenancy with an API key and three read-only permissions:

1Allow group MiddlewareMonitoring to inspect tenancies in tenancy
2Allow group MiddlewareMonitoring to read metrics in tenancy
3Allow group MiddlewareMonitoring to inspect all-resources in tenancy

1oci session authenticate --region <home-region> --profile-name mwsetup

1USER_EMAIL=you+mwmonitoring@example.com PROFILE=mwsetup AUTH=security_token \
2  bash oci-mw-monitoring-setup.sh

1#!/usr/bin/env bash
2# Creates the Middleware monitoring identity in an OCI tenancy and prints
3# the values for the Middleware "Connect your tenancy" form.
4set -euo pipefail
5
6PROFILE=${PROFILE:-DEFAULT}            # OCI CLI profile of a tenancy administrator
7AUTH=${AUTH:-}                         # "security_token" for profiles from `oci session authenticate`
8USER_EMAIL=${USER_EMAIL:?Set USER_EMAIL (Identity Domains require an email for every user)}
9GROUP=MiddlewareMonitoring
10USER_NAME=mw-monitoring
11POLICY=MiddlewareMonitoring
12KEY_DIR=${KEY_DIR:-$HOME/.oci/mw-monitoring}
13
14export SUPPRESS_LABEL_WARNING=True
15oci_() { oci --profile "$PROFILE" ${AUTH:+--auth "$AUTH"} "$@"; }
16value() { local v; v=$("$@" 2>/dev/null || true); [ "$v" = "null" ] && v=""; printf '%s' "$v"; }
17
18TENANCY=$(awk -v p="[$PROFILE]" '$0==p{f=1;next} /^\[/{f=0} f&&/^tenancy[[:space:]]*=/{sub(/^tenancy[[:space:]]*=[[:space:]]*/,"");print}' ~/.oci/config)
19HOME_REGION=$(oci_ iam region-subscription list --tenancy-id "$TENANCY" \
20  --query 'data[?"is-home-region"] | [0]."region-name"' --raw-output)
21
22# 1. Group
23GROUP_ID=$(value oci_ iam group list --compartment-id "$TENANCY" --name "$GROUP" --query 'data[0].id' --raw-output)
24[ -n "$GROUP_ID" ] || GROUP_ID=$(oci_ iam group create --compartment-id "$TENANCY" --name "$GROUP" \
25  --description "Middleware observability read-only access" --query 'data.id' --raw-output)
26
27# 2. User, added to the group
28USER_ID=$(value oci_ iam user list --compartment-id "$TENANCY" --name "$USER_NAME" --query 'data[0].id' --raw-output)
29[ -n "$USER_ID" ] || USER_ID=$(oci_ iam user create --compartment-id "$TENANCY" --name "$USER_NAME" \
30  --email "$USER_EMAIL" --description "Middleware OCI monitoring (API key only)" --query 'data.id' --raw-output)
31oci_ iam group add-user --group-id "$GROUP_ID" --user-id "$USER_ID" >/dev/null 2>&1 || true
32
33# 3. Policy in the root compartment
34POLICY_ID=$(value oci_ iam policy list --compartment-id "$TENANCY" --name "$POLICY" --query 'data[0].id' --raw-output)
35[ -n "$POLICY_ID" ] || oci_ iam policy create --compartment-id "$TENANCY" --name "$POLICY" \
36  --description "Read-only access for Middleware OCI monitoring" \
37  --statements "[\"Allow group $GROUP to inspect tenancies in tenancy\",\"Allow group $GROUP to read metrics in tenancy\",\"Allow group $GROUP to inspect all-resources in tenancy\"]" >/dev/null
38
39# 4. API key: generated locally, only the public key is uploaded
40mkdir -p "$KEY_DIR" && chmod 700 "$KEY_DIR"
41KEY="$KEY_DIR/oci_api_key.pem"
42if [ ! -f "$KEY" ]; then
43  openssl genrsa -out "$KEY" 2048 2>/dev/null && chmod 600 "$KEY"
44  openssl rsa -pubout -in "$KEY" -out "$KEY_DIR/oci_api_key_public.pem" 2>/dev/null
45fi
46FINGERPRINT=$(openssl rsa -pubout -outform DER -in "$KEY" 2>/dev/null | openssl md5 -c | awk '{print $NF}')
47UPLOADED=$(value oci_ iam user api-key list --user-id "$USER_ID" \
48  --query "data[?fingerprint=='$FINGERPRINT'] | length(@)" --raw-output)
49[ "${UPLOADED:-0}" != "0" ] || oci_ iam user api-key upload --user-id "$USER_ID" \
50  --key-file "$KEY_DIR/oci_api_key_public.pem" >/dev/null
51
52cat <<EOF
53Tenancy OCID : $TENANCY
54Home region  : $HOME_REGION
55User OCID    : $USER_ID
56Fingerprint  : $FINGERPRINT
57Private key  : paste the contents of $KEY
58EOF

Middleware Configuration#

1. In Middleware, go to Installations → All Integrations and open Oracle Cloud Infrastructure.

2. Under Grant Middleware read-only access, select API key.

3. Under Connect your tenancy, fill in:

   Field	Where to find it
   Tenancy OCID	OCI Console Profile > Tenancy, starts with ocid1.tenancy.
   Home region	OCI Console Profile > Tenancy, for example us-ashburn-1
   User OCID	The monitoring user's details page, starts with ocid1.user.
   Fingerprint	The API key's fingerprint, for example 12:34:56:...
   Private key (PEM)	The full contents of the downloaded private key file, including the BEGIN and END lines

4. Click Verify. Middleware checks each permission separately:

   • Passed for all three: access is complete.
   • Failed for inspect tenancies or read metrics: a required policy statement is missing. Add it and verify again.
   • Missing for inspect all-resources: metrics are still collected, but without resource names, compartment names and tags, and tag filters cannot be used.

A tenancy can be connected once. To monitor several tenancies, click Add Tenancy and repeat these steps for each.

Configuring Metric Collection#

After the tenancy is verified, the Configure metric collection step appears:

• Allow Metric Collection: turns collection on or off for this tenancy.
• Regions: leave empty to collect from every region the tenancy subscribes to, or select specific regions.
• OCI services: turn individual services on or off. The table shows the OCI Monitoring namespaces and the number of metrics collected for each service.
• Compartments: leave empty to collect from the whole tenancy, including all sub-compartments. If you list compartment OCIDs, only those compartments are collected, without their sub-compartments.
• Tag filters: collect only resources with matching OCI tags. Use key (any value) or key:value, and write defined tags as namespace.key, for example Operations.CostCenter:42. A resource is collected when it matches any Include entry (or Include is empty) and no Exclude entry. Tag filters need the inspect all-resources permission.
• Custom attributes: key:value pairs added to every metric from this tenancy, for example team:payments.

Click Save Configuration. Data starts arriving within about 15 minutes.

You can also enable or disable a single service from its own card, such as OCI Compute, under Installations → All Integrations. The card's Data Collected tab lists the metrics collected for that service.

Supported OCI Services#

Middleware collects 179 metrics across these services. To request another OCI service, contact Middleware support.

Accessing Data#

Each service has a default dashboard, listed on the Dashboards page under its service name, for example OCI Compute. To build your own widgets, search for metrics starting with oci_.

Metric names use the format <namespace>.<MetricName>, for example oci_computeagent.CpuUtilization. All metrics are gauges.

Every metric carries these resource attributes:

oci.compartment.name, oci.resource.type, oci.resource.lifecycle_state and the tags need the inspect all-resources permission. Other OCI dimensions, such as shape or availabilityDomain, are kept as metric attributes.

Metrics Collected#

Troubleshooting#

Verify fails with "Authentication failed" for every check

The user OCID, fingerprint or private key does not match. Check that the fingerprint belongs to the key you pasted, and that the private key includes the BEGIN and END lines.

Verify fails for some checks and passes for others, with "Authentication failed"

The API key was added in the last few minutes and has not reached every OCI service yet. Wait a few minutes and click Verify again.

A check fails with "Not authorized"

The policy statement for that permission is missing, or was added less than a minute ago. Check that the policy is in the root compartment and names the group the user belongs to.

No data after saving

• Wait about 15 minutes after saving. Metrics are collected every 5 minutes and run a few minutes behind real time.
• Check that Allow Metric Collection is on and the service is enabled for the tenancy.
• Check that the resources exist in the selected regions and compartments, and match your tag filters.

Compute instances show no CPU or memory metrics

oci_computeagent metrics are published by the Oracle Cloud Agent on each instance. Enable the Compute Instance Monitoring plugin under the instance's Oracle Cloud Agent tab, and make sure the instance can reach OCI services through a public IP, a NAT gateway or a service gateway.

Resource names or tags are missing

Add the inspect all-resources policy statement. Names and tags are refreshed every 15 minutes.

Removing the Integration#

To stop collecting from a tenancy, open Oracle Cloud Infrastructure in Middleware, select the tenancy under Connected tenancies and delete it. Then remove the MiddlewareMonitoring policy, user and group from your tenancy.