Cost and Usage Reports Overview

A cost report is a comma-separated value (CSV) file that is similar to a usage report, but also includes cost columns. The report can be used to obtain a breakdown of your invoice line items at resource-level granularity. As a result, you can optimize your Oracle Cloud Infrastructure spending, and make more informed cloud spending decisions.

A usage report is a comma-separated value (CSV) file that can be used to get a detailed breakdown of resources in Oracle Cloud Infrastructure for audit or invoice reconciliation.

In summary, usage reports indicate the quantity of what is consumed, while cost reports indicate the cost of resource consumption.

Note

Cost and usage reports do not apply to non-metered tenancies.

How Cost Reports Work

Cost reports are automatically generated every six hours, and are stored in an Oracle-owned Object Storage bucket. The reports contain one row per each Oracle Cloud Infrastructure resource (such as instance, Object Storage bucket, VNIC) per hour along with consumption information (usage, price, cost), metadata, and tags. Cost reports generally contain six hours of usage data, and occasionally late-arriving data, but the data can be delayed up to 24 hours. Cost reports are retained for one year.

Cost reports can contain corrections. Corrections are added as new rows to the report, with the lineItem/iscorrection column set and the referenceNo value of the corrected line populated in the lineItem/backReference column.

The file name for each cost report is appended with an automatically incrementing numerical value, and the first file is appended with -00001.csv.gz. Cost report files are split into multiple files when more than 1 million records are present in the cost report file. When a file split occurs, new successive files are generated and are appended with -00002.csv.gz, -00003.csv.gz, and so on, for each file split. If the cost report file size stays under the file size threshold, then file splitting does not occur and only a single file is generated.

Cost Report Schema

The following table shows the cost report schema.

Field Name Description
lineItem/referenceNo Line identifier. Used for debugging and corrections.
lineItem/TenantId The identifier (OCID) for the Oracle Cloud Infrastructure tenant.
lineItem/intervalUsageStart The start time of the usage interval for the resource in UTC.
lineItem/intervalUsageEnd The end time of the usage interval for the resource in UTC.
product/service The service that the resource is in.
product/compartmentId The ID of the compartment that contains the resource.
product/compartmentName The name of the compartment that contains the resource.
product/region The region that contains the resource.
product/availabilityDomain The availability domain that contains the resource.
product/resourceId The identifier for the resource.
usage/billedQuantity

The quantity of the resource that has been billed over the usage interval.

Note: billedQuantity, myCost, and unitPrice are inclusive of Overage numbers.

cost/billingUnitReadable The unit measure associated with the usage/billedQuantity in the line. This field is structured as: <count> <GiB/MiB/TiB/PiB> <HOURS/MILLIS/MONTH/SECOND> <measure>. For example: ONE GiB MONTH DATA_TRANSFERRED.
cost/subscriptionId A unique identifier associated with your commitment or subscription.
cost/productSku The Part Number for the resource in the line.
product/description The product description for the resource in the line.
cost/unitPrice

The cost billed to you for each unit of the resource used.

Note: billedQuantity, myCost, and unitPrice are inclusive of Overage numbers.

cost/myCost

The cost charged for this line of usage. myCost is equal to usage/billedQuanty * cost/unitPrice.

Note: billedQuantity, myCost, and unitPrice are inclusive of Overage numbers.

cost/currencyCode The currency code for your tenancy.
usage/billedQuantityOverage The usage quantity for which you were billed.
cost/unitPriceOverage The cost per unit of usage for overage usage of a resource.
cost/myCostOverage The cost billed for overage usage of a resource.
lineItem/backReference Data amendments and corrections reference. If a correction to an existing line item is needed, a new row is added with the corrected values and a reference to the original line. Used with the lineItem/isCorrection field.
lineItem/isCorrection Used if the current line is a correction. See the lineitem/backReference column for a reference to the corrected line item.
tags/ The report contains one column per tag definition (includes all tag definitions, not just cost tracking tags).

How Usage Reports Work

Usage reports are automatically generated daily, and are stored in an Oracle-owned Object Storage bucket. The reports contain one row per each Oracle Cloud Infrastructure resource (such as instance, Object Storage bucket, VNIC) per hour along with consumption information, metadata, and tags. Usage reports generally contain 24 hours of usage data, although occasionally a usage report can contain late-arriving data that is older than 24 hours. Usage reports are retained for one year.

Note

If you change any cost tracking tags during a particular hour time slot, the last cost tracking tag that is chosen is what gets applied to that hour. For example, if you changed a tag from "AAA" to "BBB" at 10:40, the usage for 10:00-11:00 would reflect "BBB" for the tag. In addition, tags cannot be applied retroactively.

Usage reports can contain corrections. Corrections are added as new rows to the report, with the lineItem/iscorrection column set and the referenceNo value of the corrected line populated in the lineItem/backReference column.

File names for each usage report are appended with an automatically incrementing numerical value.

Usage Report Schema

The following table shows the usage report schema.

Field Name Description
lineItem/referenceNo Line identifier. Used for debugging and corrections.
lineItem/TenantId The identifier (OCID) for the Oracle Cloud Infrastructure tenant.
lineItem/intervalUsageStart The start time of the usage interval for the resource in UTC.
lineItem/intervalUsageEnd The end time of the usage interval for the resource in UTC.
product/service The service that the resource is in.
product/resource The resource name used by the metering system.
product/compartmentId The ID of the compartment that contains the resource.
product/compartmentName The name of the compartment that contains the resource.
product/region The region that contains the resource.
product/availabilityDomain The availability domain that contains the resource.
product/resourceId The identifier for the resource.
usage/consumedQuantity The quantity of the resource that has been consumed over the usage interval.
usage/billedQuantity The quantity of the resource that has been billed over the usage interval.
usage/consumedQuantityUnits The unit for the consumed quantity and billed quantity.
usage/consumedQuantityMeasure The measure for the consumed quantity and billed quantity.
lineItem/backReference Data amendments and corrections reference. If a correction to an existing line item is needed, a new row is added with the corrected values and a reference to the original line. Used with the lineItem/isCorrection field.
lineItem/isCorrection Used if the current line is a correction. See the lineitem/backReference column for a reference to the corrected line item.
tags/ The report contains one column per tag definition (includes all tag definitions, not just cost tracking tags).

Accessing Cost and Usage Reports

Cost and usage reports are comma-separated value (CSV) files that are generated daily and stored in an Object Storage bucket. This topic describes how to access these reports.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

If you're new to policies, see Getting Started with Policies and Common Policies.

To use cost and usage reports, the following policy statement is required:

define tenancy usage-report as ocid1.tenancy.oc1..aaaaaaaaned4fkpkisbwjlr56u7cj63lf3wffbilvqknstgtvzub7vhqkggq
endorse group <group> to read objects in tenancy usage-report
Note

This example has a specific tenancy OCID, because the reports are stored in an Oracle-owned Object Storage bucket hosted by Oracle Cloud Infrastructure, and not a customer's tenancy.

Authentication and Authorization

Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and authorization, for all interfaces (the Console, SDK or CLI, and REST API).

An administrator in your organization needs to set up groups , compartments , and policies  that control which users can access which services, which resources, and the type of access. For example, the policies control who can create new users, create and manage the cloud network, launch instances, create buckets, download objects, and so on. For more information, see Getting Started with Policies. For specific details about writing policies for each of the different services, see Policy Reference.

If you’re a regular user (not an administrator) who needs to use the Oracle Cloud Infrastructure resources that your company owns, contact your administrator to set up a user ID for you. The administrator can confirm which compartment or compartments you should be using.