Chargeback

You can see how the internal organizations or business divisions in your company contribute to the overall license usage using the chargeback feature. This information might also help you monitor the namespaces during migrating your software to Cloud, or with establishing the potential chargeback. Chargeback groups are based on namespaces.

Chargeback - Filtering the license usage data by user-defined groups

For license compliance purposes, License Service automatically collects information about the highest license usage of your products in all namespaces in the entire cluster. However, for internal accounting, you might need to calculate the expenses associated with the license usage of the individual internal organizations or business divisions in your company, that is - chargeback.

Using the chargeback feature, you can define groups and assign namespaces to these groups. Then, you can retrieve the license usage reports for the individual groups. As a result, you can analyze and understand the contribution of each group to the overall license usage, especially during the peak, or for any time range. You can also see which group has the highest and lowest usage, and what software is mostly used throughout your organization.

To filter the license usage by groups, divide your namespaces into groups by labeling them. You can assign multiple namespaces to one group. If you do not assign a namespace to any group, you do not track its contribution to the overall usage. Next, enable filtering feature in the IBMLicensing custom resource, and retrieve the license usage with the /products API with groupName parameter.

Enabling chargeback in License Service

To enable or configure the chargeback feature in License Service, see Enabling chargeback feature.

Retrieving license usage data by user-defined groups

To retrieve the license usage data for the defined group, use the /products API and use the groupName parameter for filtering. You can retrieve license usage for more than one group by adding more groupName=<groupName> parameters to get the total contribution of these groups. Additionally, set the startDate=<YYYY-MM-DD> and endDate=<YYYY-MM-DD> parameters to specify the reporting period that you want to query.

Important: If you do not set the startDate=<YYYY-MM-DD> and endDate=<YYYY-MM-DD> parameters, the API retrieves the highest license usage of your products for the group or groups only if the highest license usage is registered after you enabled chargeback.

API URL: <License Service URL>/products?token=<token>&groupName=<groupName>&startDate=<YYYY-MM-DD>&endDate=<YYYY-MM-DD>

Tip: By default, the API retrieves data in .json format. You can change the format to .csv by adding the format=csv parameter to your query.

For more information about the /products API and the parameters, see Retrieving license usage of products.

Understanding the reported values

The API retrieves the license usage of products that are deployed in the namespaces that are assigned to the defined group or groups. The license usage is expressed by the metricQuantity value which is the number of metric units that the group contributes to the overall usage of the product on the cluster. As a result, the metricQuantity can be expressed by a fraction.

Example scenario

You can use chargeback to track license usage for your products in different divisions in your organization. First, think about how many groups you can distinguish, and gather information about which namespaces these groups use.

In this example, Cluster Administrator defines two groups: HR and Procurement by adding the labels to appropriate namespaces, and then enables filtering by group. As Cluster Administrator defines only 2 groups that use only one product, the chargeback retention period is set to 90 days as recommended for small environments.

The following API retrieves license usage for the HR group for 2 weeks in July:

API URL: LS-host/products?token=token&groupName=HR&startDate=<2021-07-01>&endDate=<2021-07-14>

Response:

 "name": "IBM Cloud Pak for Integration",
 "id": "c8b82d189e7545f0892db9ef2731b90d",
 "metricPeakDate": "2021-07-08",
 "metricName": "VIRTUAL_PROCESSOR_CORE",
 "metricQuantity": 1.5

The following API retrieves license usage for the Procurement group for the same period:

API URL: LS-host/products?token=token&groupName=Procurement&startDate=<2021-07-01>&endDate=<2021-07-14>

Response:
```
 "name": "IBM Cloud Pak for Integration",
 "id": "c8b82d189e7545f0892db9ef2731b90b",
 "metricPeakDate": "2021-07-08",
 "metricName": "VIRTUAL_PROCESSOR_CORE",
 "metricQuantity": 0.5
```

Based on the example, the HR group contributes 1.5 VPCs of the overall usage of IBM Cloud Pak for Integration on the peak date, while Procurement group contributes 0.5 VPC.

The following API retrieves the overall license usage that is registered on a cluster:

LS-host/products?token=token

Response:

 "name": "IBM Cloud Pak for Integration",
 "id": "c8b82d189e7545f0892db9ef2731b90d",
 "metricPeakDate": "2021-07-08",
 "metricName": "VIRTUAL_PROCESSOR_CORE",
 "metricQuantity": 4

As the overall license usage of IBM Cloud Pak for Integration on the peak date equals 4, and the HR group contributes 1.5 VPCs and the Procurement group 0.5 VPC, you can calculate that the remaining usage, 2 VPCs, is used outside of the defined groups.

The following image represents the license usage on the cluster.

The image shows the breakdown of the license usage on the cluster.

The following statements summarize the license usage calculations for the cluster:

The group contribution, that is expressed in the number of metrics, is a sum of converted metric contributions of all bundled products that are reported for this group.
The converted metric contribution of a bundled product in the group is proportional to the overall use of the product on the cluster.
To calculate the contribution of the HR group, the converted metric contribution needs to be estimated for IBM MQ Advanced and IBM MQ.
The following example shows how to calculate the converted metric contribution for IBM MQ Advanced that is deployed within the HR group.

Table 2. Overall usage of IBM MQ Advanced
Information	Value	Comments
Overall usage of IBM MQ Advanced on the cluster	1 vCPU + 1 vCPU + 2 vCPUs = 4 vCPUs	To calculate the overall usage of the bundled product, add the vCPUs that are used by all the instances of the bundled product in the cluster. vCPU is calculated according to the IBM Container Licensing rules. For more information, see IBM Container Licenses on Passport Advantage.
Metric conversion for IBM MQ Advanced	2:1	Metric conversion is defined in the licensing document of the product
Metric converted quantity for IBM MQ Advanced on the cluster	4 vCPUs * 2:1 = 2 VPCs	To calculate the metric converted quantity, multiply the overall usage of the bundled product on the cluster by the metric conversion ratio. As a result, the value represents the number of VPCs that the bundled product contributes on the cluster
Converted metric contribution of IBM MQ Advanced in the `HR` group	1 vCPU /4 vCPUs * 2 VPCs = 0.5 VPC	To calculate the contribution of the bundled product within the group divide the number of the vCPUs used within the group by the overall number of vCPUs used on the cluster and multiply it by the metric converted quantity for the cluster.

You can base on the example to similarly calculate the converted metric contribution of any bundled product within the group.