BTP Directory Usage

This monitor reports the resource consumption of one SAP BTP directory, for every subaccount,
service, plan and measure it contains.
It reads the monthlyDirectoryUsage API of the SAP Usage Data Management service.
It raises alarms when usage crosses a limit, when it rises sharply from one month to the next,
and when a subaccount and service that used to report usage stops appearing.
It covers usage only, in the units the platform meters, and works whatever commercial model
the global account is licensed under.

Note: this monitor exists for clients who do not want to grant reporting on the whole global account. A directory key sees its own directory and nothing else. When the whole global account is available, BTP Global Usage reports the same figures in a single call.

• An instance of the Usage Data Management service on plan reporting-directory, created with the GUID of the directory, and a service key.
• A Web Service connector of its own, on that service key.

Note: this is not the connector used by BTP Global Usage and BTP Subaccount Usage. The two scopes are separated in both directions: a directory key answers 403 on the global account API, and a GA_Admin key answers 403 on the directory API. One connector cannot serve both.

Note: one instance, one key and one connector are needed per directory. The directory is chosen when the service instance is created and cannot be changed afterwards.

The cockpit cannot create this plan: it offers no field for the directory GUID and reports an empty error message when creation fails. Use the CLI, with the Directory ID from the directory's Overview page:

cf create-service uas reporting-directory <name> -c '{"directoryGuid":"<directory-id>"}'
cf create-service-key <name> <key-name>
cf service-key <name> <key-name>

Note: the target subaccount must sit inside the directory, not directly under the global account, and the directory's reporting-directory entitlement must have Auto-Assign to Subaccounts enabled. Without it the subaccount never actually receives the quota, even though the directory shows it.

All values come from the service key of the reporting-directory instance.

Note: the URL is the same address as the BTP Global Usage connector, but the authentication server is not: it carries the directory's own GUID. The token is what decides which data the same address returns.

Note: the availability end point deliberately asks for an old month. The call returns an empty result quickly, which is all the check needs. Do not give this end point to the GA_Admin connector: it answers 403 and the whole system is then reported as unreachable.

• A single call per run returns every subaccount, service, plan and measure of the directory. Adding a line to the surveillance table costs no additional call.
• The Directory GUID field is optional. The service key of the connector already selects the directory and the API ignores any other value. Fill it in only to document which directory the job reads.

• Defines how many months before the current one are collected. Default is 2.
• Keep it at 2 or more. The increase alarm compares the last two months that have ended, and with 0 there are none.
• Earlier months also feed the metadata export, where figures that are still settling after month end are picked up.

Note: the current month is never compared. It is still filling, so measuring it against a whole month would report a fall every time a month begins.

• If enabled, the collected usage records are sent as metadata to the configured plugins/integrations
• All collected records are sent, not only those matching a surveillance rule
• Each record carries every field the API returns, including the space, data centre and the identifiers behind the display names

Note: a record is only sent when its usage changed since the previous run, otherwise the same figures would be sent on every cycle. The comparison is per row, space and service instance included, so the rows a metric adds together are still exported one by one.

Note: always set a single Measure on a line that carries a Usage threshold. Measures do not share a unit: API calls, gigabytes and hours are all plain numbers.

Note: no increase is computed when the previous month had no usage, since a percentage of zero has no meaning.

Note: the monitor remembers the last month each subaccount and service reported, so the no data warning is still raised once a series has disappeared from the collected range altogether. A series silent for 12 months is forgotten and its alarm clears.

Note: SAP returns one row per Cloud Foundry space, service instance and application. The rows of the same subaccount, service, plan and measure are added together and reported as a single figure, so a service used in three spaces gives one metric and one alarm carrying its total.

• Usage: the usage value and unit, the service, plan and measure, the breached threshold, the directory, the subaccount and the month.
• Increase: the increase in percent, the two values compared, the service, plan and measure, the directory, the subaccount and both months.
• No data (WARNING): the service, plan and measure, the last month reported, the number of months of silence and the allowed delay.
• Alarms are stable across runs: the same series updates its alarm rather than raising a new one.

Effect: Publishes the usage of every subaccount, service, plan and measure of the directory as metrics, and raises no alarm. This is the line to start with, so the normal range can be observed before choosing any threshold.

Effect: Compares the audit log volume of the last two whole months. Sends a WARNING when it has doubled and a MAJOR when it has grown six times.

Effect: Sends a MAJOR alarm when the production subaccount of the directory passes 4 GB of Cloud Foundry memory this month, and a WARNING when it has reported no Cloud Foundry usage for more than two months.

Note: the measure is part of the metric name, as promonitor.btp.directory_usage.<measure>. It differs from the BTP Global Usage metrics on purpose: the directory figures are a subset of the same rows, and sharing one name would write two values into a single series.

Note: the value is a cumulative month to date figure and must be read as a gauge. A dashboard that aggregates the series as a sum will multiply it by the number of runs in the month.

Note: metrics are sent from the first run even when no threshold is configured, so the normal range can be observed before choosing thresholds.