Configure Business KPI Service Access

Access the business KPI metrics using the following endpoint:

GET /kpi/metrics

The endpoint URL, identity domain host, and access details are provided during onboarding. The examples in this document use <ENVIRONMENT-FRONTEND-HOST> as the host name from the environment front-end URL (without the https:// scheme and without any application UI path).

For example, if your application UI URL is: https://<ENVIRONMENT-FRONTEND-HOST>/<ENVIRONMENT-NAME>/<APP-NAME>/<UI>;, use only <ENVIRONMENT-FRONTEND-HOST> in KPI Service URLs and scopes. Do not include the path /<ENVIRONMENT-NAME>/<APP-NAME>/<UI>.

Use a dedicated metrics collector (such as Prometheus, Grafana Alloy, or any Prometheus/OpenMetrics-compatible collector) to call this endpoint. Do not scrape the endpoint more frequently than once every 20 seconds.

Exposition Format

The endpoint supports both Prometheus text and OpenMetrics-compatible clients.

Client request Response behavior

Explicitly accepts application/openmetrics-text; version=1.0.0

Returns OpenMetrics 1.0 text exposition.

Accepts text/plain, sends a browser-style Accept header, or sends no Accept header

Returns Prometheus text exposition.

Successful responses include metric family metadata and sample values. Keep the configured Accept behavior stable after the collector has been validated.

Create an OCI IAM Client

Use this procedure when onboarding requires an Oracle Cloud Infrastructure IAM confidential client for the metrics collector.

Before you begin, ensure you have the following:

  • Administrator access to the target cloud account

  • The environment front-end host

  • The identity domain token endpoint host

  • The KPI Service resource application name

  • The KPI Service scope

  • Access to the managed secret store used by the metrics collector

Create a separate confidential client application for the metrics collector. The collector must support OAuth 2.0 client credentials and be able to scrape Prometheus or OpenMetrics text.

  1. Open the OCI Console with an administrator account for the target cloud account.

  2. Go to Integrated Applications.

  3. Select Add application.

  4. Select Confidential Application and launch the workflow.

  5. Enter a name that identifies the consumer and environment, for example OHI-<ENVIRONMENT-NAME>-KPI-SCRAPER.

  6. Select Configure this application as a client now.

  7. Enable the Client Credentials grant type.

  8. In the Token Issuance Policy, set Authorized Resources to Specific.

  9. Select Add Scope.

  10. Select the KPI Service resource application, for example OHI-<ENVIRONMENT-NAME>-KPI-SERVICE.

  11. Select the KPI Service scope:

    https://<ENVIRONMENT-FRONTEND-HOST>/kpi/urn::ohi-kpi-service

  12. Finish the workflow.

  13. Copy the generated client ID.

  14. Use Show Secret once and store the client secret in the managed secret store used by the metrics collector.

  15. Select Activate.

You can use one client application for multiple environments if the token issuance policy includes the KPI Service scope for each environment. In that case, use a generic name, such as OHI-KPI-SCRAPER.

Verify Token Issuance

Use the identity domain token endpoint for the environment:

https://<identity-domain-host>/oauth2/v1/token

Request a token using the client credentials grant:

curl --request POST \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --user '<client-id>:<client-secret>' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=https://<ENVIRONMENT-FRONTEND-HOST>/kpi/urn::ohi-kpi-service' \
  'https://<identity-domain-host>/oauth2/v1/token'

The response must contain an access_token. Do not persist the full token response in logs, dashboards, tickets, or documentation, as it may contain sensitive information.

Verify KPI Service Access

Call the KPI Service using the issued bearer token:

curl --request GET \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Accept: text/plain' \
  'https://<ENVIRONMENT-FRONTEND-HOST>/kpi/metrics'

Expected result:

  • HTTP 200 response from the KPI Service.

  • Prometheus text exposition (by default).

  • KPI metric families and labels for the configured tenant and environment.

If the request returns 401 Unauthorized or 403 Forbidden, verify that the client application is active, the correct scope was requested, the resource application scope is protected and enabled, and the audience matches the KPI Service audience for the environment.

Configure the Scraper

Configure the metrics collector with the Business KPI Service endpoint URL, the required authentication details, and a scrape interval of 20s or longer.

Add a scrape job similar to the following example. This Prometheus example uses native OAuth 2.0 client credentials, with the OAuth 2.0 fields grouped in the Prometheus oauth2 block:

job_name: kpi-metrics-<ENVIRONMENT-NAME>
scheme: https
metrics_path: /kpi/metrics
scrape_interval: 20s
scrape_timeout: 10s
oauth2:
  client_id: <client-id>
  client_secret_file: /etc/prometheus/auxiliaryfiles/kpi-service-client-secret
  grant_type: client_credentials
  scopes:
    - https://<ENVIRONMENT-FRONTEND-HOST>/kpi/urn::ohi-kpi-service
  token_url: https://<identity-domain-host>/oauth2/v1/token
static_configs:
  - targets:
      - <ENVIRONMENT-FRONTEND-HOST>

Scraping Flow

  1. Configure the metrics collector with the Business KPI Service endpoint URL.

  2. Configure the required authentication details provided during onboarding.

  3. Set the scrape interval to 20s or longer.

  4. Scrape the secured /kpi/metrics endpoint.

  5. Store the returned metrics in a Prometheus/OpenMetrics-compatible observability platform.

  6. Use the provided Grafana dashboard templates or create custom dashboards and alerts.