====== 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. ===== Prerequisites ===== * 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. ==== Creating the service instance ==== 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 -c '{"directoryGuid":""}' cf create-service-key cf service-key **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. ===== Connector configuration ===== All values come from the service key of the ''reporting-directory'' instance. ^ Field ^ Value ^ | Authentication type | ''OAUTH2_CLIENT_CREDENTIALS'' | | Client authentication mode | ''BODY_PARAMS'' | | Authentication server | the key's ''url'' field, **with ''/oauth/token'' appended** | | Client ID | the key's ''clientid'' | | Client secret | the key's ''clientsecret'' | | URL | the key's ''target_url'' | | Availability end point | ''/reports/v1/monthlyDirectoryUsage?fromDate=202001&toDate=202001'' | | Expected code | ''200'' | **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. ===== Configuration hints ===== * 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. ==== Months back ==== * 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. ==== Send metadata ==== * 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. ===== Surveillance table ===== ^ Parameter ^ Description ^ | Active | Use this field to activate or deactivate a line of configuration. | | Subaccount | A filter on the subaccount name inside the directory. Use ''*'' for all, or part of the name. | | Service | A filter to match only a given service, by its display name, for example ''Audit Log Service''. | | Plan | A filter to match only a given service plan, by its display name, for example ''Standard''. | | Measure | A filter to match only a given measure, for example ''api_calls'' or ''memory_per_hour''. | | Usage | A graded threshold on the usage of the most recent month. Leave a grade at ''0'' to disable it. | | Increase % | A graded threshold on the increase, in percent, between the last two whole months. Leave a grade at ''0'' to disable it. | | No data after (months) | Raises a warning when a subaccount and service has reported nothing for longer than this many months. ''0'' disables it. Default ''1''. | | Auto clear | If checked, the alarm is cleared automatically once the condition is gone. | | enable Alarm | If checked, this line of surveillance will be used for alarm generation. | | enable QOS | If checked, this line of surveillance will be used for metric generation. | **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. ===== Alarm content ===== * **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. ===== Examples ===== ==== Example 1 ==== ^ Active ^ Subaccount ^ Service ^ Plan ^ Measure ^ Usage ^ Increase % ^ No data after ^ Auto clear ^ enable Alarm ^ enable QOS ^ | true | * | * | * | * | G2W:0 W2M:0 | G2W:0 W2M:0 | 0 | true | false | true | **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. ==== Example 2 ==== ^ Active ^ Subaccount ^ Service ^ Plan ^ Measure ^ Usage ^ Increase % ^ No data after ^ Auto clear ^ enable Alarm ^ enable QOS ^ | true | * | Audit Log Service | * | volume_stored_total | G2W:0 W2M:0 | G2W:100 W2M:500 | 0 | true | true | true | **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. ==== Example 3 ==== ^ Active ^ Subaccount ^ Service ^ Plan ^ Measure ^ Usage ^ Increase % ^ No data after ^ Auto clear ^ enable Alarm ^ enable QOS ^ | true | PROD | Cloud Foundry Runtime | * | memory_per_hour | G2W:0 W2M:4 | G2W:0 W2M:0 | 2 | true | true | true | **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. ===== Generated metrics ===== ^ metricId ^ metricUnit ^ metricTarget ^ metricDescription ^ | BTP_DIRECTORY_USAGE | the unit reported by SAP | [GLOBAL_ACCOUNT][DIRECTORY][SUBACCOUNT][SERVICE][PLAN][MEASURE][METRIC_NAME][PERIOD] | Sends the consumption reported for one subaccount, service, plan and measure of the directory. | **Note:** the measure is part of the metric name, as ''promonitor.btp.directory_usage.''. 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.