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](https://docs.cloud.google.com/service-infrastructure/docs/service-control/reference/rest/v1/Operation.md.txt).

If your service already supports a concept of
[resource labels](https://docs.cloud.google.com/resource-manager/docs/creating-managing-labels.md.txt), we recommend
that you forward those labels in your usage reports. Labels must conform to the
[syntax requirements](https://docs.cloud.google.com/resource-manager/docs/creating-managing-labels.md.txt#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 | <var translate="no">USER_SUPPLIED</var> | The name of the resource associated with a usage metric. |
| cloudmarketplace.googleapis.com/container_name | <var translate="no">USER_SUPPLIED</var> | The name of a resource container. |

Labels are forwarded to Cloud Billing [cost management](https://docs.cloud.google.com/cost-management)
tools, including [cost reports](https://docs.cloud.google.com/billing/docs/how-to/reports.md.txt) and
[billing exports](https://docs.cloud.google.com/billing/docs/how-to/export-data-bigquery.md.txt).

## 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](https://developers.google.com/gcp-marketplace-saas).