Best practices for usage reporting

For usage-based SaaS products, Google Cloud Marketplace attributes usage to a single Google Cloud project, specified by the usageReportingId field. In some scenarios, a SaaS product might be shared broadly within a customer's organization and used across many customer projects. To enable support for more specific cost attribution, we recommend that usage-based SaaS products include the optional userLabels field on their usage report operation.

If your service already supports a concept of resource labels, we recommend that you forward those labels in your usage reports. Labels must conform to the syntax requirements.

Usage labels

Cloud Marketplace reserves the following labels. You can use these labels to identify additional context for usage within your service platform. We recommend that you include these labels in your usage reports by default.

Label Key	Label Value	Description>
cloudmarketplace.googleapis.com/resource_name	USER_SUPPLIED	The name of the resource associated with a usage metric.
cloudmarketplace.googleapis.com/container_name	USER_SUPPLIED	The name of a resource container.

Labels are forwarded to Cloud Billing cost management tools, including cost reports and billing exports.

Usage labeling example

For this example, imagine your organization offers a storage product called SaaS Storage Solutions.

A customer, Carl, has purchased your storage offering for their Google Cloud project e-commerce-website, to host the user_profiles_db and products_db databases for their ecommerce website:

• user_profiles_db contains information about users that visit Carl's site.
• products_db contains information about products that Carl sells on their site.

If you want to provide Carl a detailed cost breakdown of their usage, you can use the userLabels key-value pair to report the cost of usage for each database separately.

For example, to report the cost attributed to Carl's products_db storage usage, you could send the following report, which indicates that Carl's products_db storage is costing them 100 units:

operation = {
  'operationId': '<UUID>',
  'operationName': 'db-total-storage',
  'consumerId': 'project:carl_website',
  'startTime': '<Timestamp>',
  'endTime': '<Timestamp>',
  'metricValues': [{
      'int64Value': 100,
  }],
  'userLabels': {
    'cloudmarketplace.googleapis.com/container_name': 'e-commerce-website',
    'cloudmarketplace.googleapis.com/resource_name': 'products_db'
  }
}

service.services().report(
  serviceName=service_name, body={
    'operations': [operation]
}).execute()

In this example, service_name is the Project ID of Carl's Google Cloud project.

For a more detailed example of using userLabels, refer to the SaaS codelab.