Cost and Usage Reports
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.
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: |
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: |
cost/myCost
|
The cost charged for this line of usage. Note: |
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.
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-reportThis 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.