Cost Analysis Overview

Cost Analysis is an easy-to-use visualization tool to help you track and optimize your Oracle Cloud Infrastructure spending, allows you to generate charts, and download accurate, reliable tabular reports of aggregated cost data on your Oracle Cloud Infrastructure consumption. Use the tool for spot checks of spending trends and for generating reports. Common scenarios you might be interested in include:

  • Show monthly costs for compartment X and its children, grouped by service or by tag.
  • Show daily costs for tag key A and tag key B, values X, Y and Z, grouped by service and product description (SKU).
  • Show hourly costs for service = compute or database, grouped by compartment name.

You can choose the dates you’re interested in. Filter to the specific tags, compartments, services, or filter you want, and pick how you want it grouped. As a result, a chart and corresponding data table are generated, and can also be downloaded as a data table.

If you want to re-create the breakdown provided by the Classic Version in the Latest Version of the Cost Analysis tool, apply the SKU (Part Number) grouping dimension. To explore your costs in new ways, we recommended viewing your costs based on Service, or Service and Product Description. If you are doing cost tracking, we recommended grouping by Compartment or Tag.

Note

All tags, not only cost tracking tags, are supported.

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  you should work in.

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

To use Cost Analysis, the following policy statement is required:

Allow group <group_name> to read usage-report in 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, etc. 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.

Cost Analysis Query Fields

The following table describes the Cost Analysis query fields.

Field Name Description
Time Period (UTC)

Allows you to query predefined time ranges for data available in the usage store. Other time ranges can be queried using the Classic Version.

The available options in the drop-down (for example, This Month, Last Month) are according to the UTC time zone, and are based on the calendar year. The actual time ranges are indicated in parentheses. When changing the time period, it is also indicated just above the chart.

Granularity (hourly, daily, monthly) is based on the requested date range size. The logic is the following:

  • Hourly: 48 hours or less
  • Daily: > 48 hours, <= 2 months
  • Monthly: > 2 months
Note

Historical data is currently being back-filled for tenancies and may not appear immediately. As that process completes, up to twelve months of past consumption data will become available.
Show

Allows you to view the report in terms of Cost (the default) or Usage.

To view Usage you must apply a filter for a unit, by selecting one from the Filters field, then via the Show Usage Info dialog box. Oracle Cloud Infrastructure services have unit measures that span from GBs/month to CPU/hours to API requests.

When selecting Usage, a dialog appears, which prompts you to add a filter for a unit to view usage data.

Note

For Usage, unit filtering is the only possible selection, and you can only choose one value for the unit.
Cumulative Select this option to modify the values so that they’re cumulative for the selected time period selected. For example, consider if you were looking at 10 days of data, cumulatively, and the values for each day are $5. In such a case, selecting Cumulative displays values of 5, 10, 15, 20, 25, 30, 35, 40, 45, and 50 across the 10 days, respectively. In a non-cumulative chart, the values display as 5, 5, 5, 5, 5, 5, 5, 5, 5, 5.
Filters

Allows filtering on the following:

  • Availability domain
  • Compartment
    Note

    Filtering by compartment displays usage and costs attributed to all resources in the selected compartments, and their child compartments.
    • By OCID
    • By Name
    • By Path (for example, root/compartmentname/compartmentname)
  • Platform (Gen-1 are services which are not OCI native. Gen-2 includes all OCI native services)
  • Tag
    • By Tag Namespace
    • By TagKey + Value
  • Region
  • Service
  • Product description (the human-readable corresponding name)
  • SKU - Part Number (for example, B91444)
  • Unit

See Filters for more information on adding, editing, and removing filters, and filter logic.

Grouping Dimensions

Allows visualizing the data in terms of the particular grouping. A grouping dimension by Service is displayed by default. You can view only one grouping dimension at a time.

  • Availability domain
  • Compartment. When you choose to group by compartment, you can pick the display name value, and a compartment depth. The compartment depth corresponds to the lowest level you want the compartments to be grouped by. All levels above that grouping level return just what is directly in those compartments. The grouping level returns values for all resources in those compartments, plus all resources in compartments below it.
    • Display As
      • Display as Compartment Name
      • Display as Compartment OCID
      • Display as Compartment Path
      Note

      If Compartment OCID or Compartment Name are chosen, you cannot view Compartment Level.
    • Compartment Level
      • All (the default): Every compartment is displayed. Values would display usage/spend associated only with the resources in that specific compartment.
      • Level 1 (root only): Only 1 column is returned (root), and values for resources contained in root and every child compartment are displayed.
      • Level 2 (root/<value>): Displays root, with values for root equaling only those resources in root. All compartments that are direct children of root are also returned. The values for each of those compartments is the sum of all resources therein, or within any children of those compartments.
      • Level 3 (root/<value>/<value>): Returns root, with values for root equaling only those resources in root. All Level 2 compartments are also returned, but with values only equal to the resources contained in each of those specific compartments. The first child level of the level 2 compartments are also returned. The values for the third level of compartment (root/child1/child2 <<) would be equal to the resources in those compartments, plus all the resources in all the children of those compartments.
      • Level 4 (root/<value>/<value>/<value>)
      • Level 5 (root/<value>/<value>/<value>/<value>)
  • Platform (Gen-1 are services which are not Oracle Cloud Infrastructurenative, while Gen-2 includes all native Oracle Cloud Infrastructure services)
  • Region
  • Resource OCID
  • Service
  • Service and Product Description
  • SKU - Part Number
  • SKU - Product Description
  • Tag
  • Unit

See Grouping Dimensions for more information on viewing and changing grouping dimensions.

Viewing and Working with the Chart Data

When the Cost Analysis page first loads, the default view is to show a grouping of services for the This Month time period, grouped by Service. The Cost Analysis chart is organized in terms of time (UTC) on the X-axis, and the cost amount on the Y-axis. When viewing a chart, you can hover the mouse over a data point in the chart to see more information about it. The tooltip shows the cost value summary for the particular Y-axis item at a particular time, whether you are viewing the chart as either a Bars (the default), Lines, or Stacked Lines chart.

To the right of the chart, the Legend box shows all the data by default, and each item is color-coded. You can click the eye icon next to any of the Legend items to toggle the chart data on or off. For example, when viewing a chart with various services and their costs, the Legend box includes all the impacted services related to the query. Toggling one or more of the services shows or hides them dynamically from the chart output. Toggling the Legend data, however, does not change the data shown in the table view, or what is downloaded.

When viewing a chart, you can also add filters or grouping dimensions (or both), to view the cost data according to one or more filters, or in terms of both filters and a single grouping dimension.

A tabular view of the chart is also provided under the chart, which is updated as you apply different time period, filtering, and grouping dimension options. When viewing the table data, you can click the column header to sort in ascending or descending order.

Note

Data can take up to 48 hours to appear in Cost Analysis.

Filters

See the following for instructions on how to add, edit, and remove filters, as well filter logic.

To add filters
  1. Open the navigation menu. Go to Account Management and click Cost Analysis.
  2. From Time Period (UTC), select a time period.
  3. From Show, select whether you want to view Cost or Usage.
  4. Choose from three chart types, whether Bars (the default), Lines, or Stacked Lines.
  5. From Filters, select a filter. A dialog specific to the chosen filter is displayed. For example, if you chose Service, select a service from the drop-down menu. You can add multiple services if preferred, or click the X icon to remove service filters. Click Select when you are finished selecting filtering criteria.
  6. Click Apply to apply the changes and reload the chart and table with the selected filters.
To edit a filter
  1. To edit the filter after it has already been applied to the chart, click the filter. The filter's dialog box is displayed.
  2. From the filter dialog drop-down menu, select one or more filters, and click Select.
  3. Click Apply to apply the changes and reload the chart and table with the selected filters.
To remove a filter
  1. To remove the filter after it has been applied to the chart, click Clear All Filters, or click the filter's X icon under Filters.
  2. Click Apply to apply the changes and reload the chart and table without the selected filters.

Filter Logic

Filters are ORed within each specific filter, and ANDed between filters. For example, a filter for Service = Compute, Block Storage, Object Storage, Database, and Tag = Tag Key "MyKey" displays data that is for (Compute OR Block Storage OR Object Storage OR Database) AND Tag Key "MyKey".

The Tag filter, however, is a unique case. You can add multiple Tag filters, which function as a joined OR.

Grouping Dimensions

See the following for instructions on how to view and change grouping dimensions. Grouping dimensions change the way data is aggregated, but does not change the sum. If a resource does not have a value for a particular field, a "no value" column is displayed, which reflects the sum of those resources. Specifically, products which are Gen-1 often do not have an Availability Domain, Compartment, or Resource ID.

To view grouping dimensions
  1. Open the navigation menu. Go to Account Management and click Cost Analysis.
  2. From Time Period (UTC), select a time period.
  3. From Show, select whether you want to view Cost or Usage.
  4. Choose from three chart types, whether Bars (the default), Lines, or Stacked Lines.
  5. From Grouping Dimensions, select the preferred grouping dimension. If Compartment or Tag is chosen, additional Compartment or Tag selection fields appear.
  6. Click Apply to apply the changes and reload the chart and table with the selected grouping dimension.
To change a grouping dimension
  1. To change the grouping dimension, select it from Grouping Dimensions.
  2. Click Apply to apply the changes and reload the chart and table with the new grouping dimension.

Download Your Data

Click the Download button to download a CSV file of the data, or a PNG file of the chart. Downloading generates a file that corresponds to the chart or table on the Cost Analysis page, inclusive of applied filters, sorting, and grouping dimensions.

Using the Usage API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the following operations to manage usage:
The Usage API allows retrieval of usage and cost data. You can:
  • Query based on different granularity, for example, MONTHLY or DAILY.
  • Specify queryType, for example, COST, USAGE.
  • Filter and group by different dimension/tags, functioning like an SQL query.
Using granularity

The Usage API supports: MONTLY, DAILY, and HOURLY granularity. All startTime are inclusive, and endTime are exclusive, the same as a Java substring.

  • For HOURLY, only a maximum 36-hour time period is supported, with no more precision than an hour. This means no minutes or seconds in the input time.
  • For MONTHLY, only the first date of the month to another first date of the month is supported. For example, 2020-06-01T00:00:00Z, a maximum 12-month period.

  • For DAILY, no more precision than a day is supported, with a maximum 90-day period. You must enter this as 00:00:00. For example, 2020-06-01T00:00:00Z.

Using groupBy
In an API response, dimension is only shown in terms of groupBy. For example, if "service" isn't in groupBy, the "service" field in the response will be empty. In addition:
  • If a groupBy list is empty, "currency" will be added into groupBy.
  • If the queryType is "Usage", "unit" will be add into groupBy.
  • If the queryType is "COST" or "empty", "currency" will be add into groupBy.
  • computedAmount works as expected only when "currency" is in groupBy.
  • computedQuantity works as expected only when "unit" is in groupBy.
Using queryType

The API can query USAGE or COST. computedQuantity represents usage and computedAmount represents cost. For getting the expected usage, you need to set queryType to USAGE or add "unit" in groupByKey. This is due to the fact that usage is aggregated/grouped correctly when grouping by unit.

Using filtering

Nested filtering in API requests is supported. The list of filters are evaluated by the operator. In each filter, all dimensions and tags are evaluated by the operator. Simultaneous evaluation of the filter list and dimension/tags is not supported, which means dimensions or tags and the filter list can't be non-empty at the same time.

Supported operators are AND, OR. These two filters below are equal:

"filter": {
  "operator": "AND",
  "dimensions": [
    {
      "key": "service",
      "value": "compute"
    },
    {
      "key": "compartmentPath",
      "value": "abc/cde"
    }
  ],
  "tags": [
    {
      "namespace": "compute",
      "key": "created",
      "value": "string"
    }
  ],
  "filters": null
}
  
or 
 
"filter": {
    "operator": "AND",
    "dimensions": [],
    "tags": [],
    "filters": [{
            "operator": "AND",
            "dimensions": [{
                "key": "service",
                "value": "compute"
            }],
            "tags": null,
            "filters": null
        }, {
            "operator": "AND",
            "dimensions": [{
                "key": "compartmentPath",
                "value": "abc/cde"
            }],
            "tags": null,
            "filters": null
        },
        {
            "operator": "AND",
            "dimensions": null,
            "tags": [{
                "namespace": "compute",
                "key": "created",
                "value": "string"
            }],
            "filters": null
        }
    ]
}
Invalid example because dimensions and filters are non-empty at the same time:
"filter": {
    "operator": "AND",
    "dimensions": [{
                "key": "compartmentPath",
                "value": "abc/cde"
            }],
    "tags": [],
    "filters": [{
            "operator": "AND",
            "dimensions": [{
                "key": "service",
                "value": "compute"
            }],
            "tags": null,
            "filters": null
        },
        {
            "operator": "AND",
            "dimensions": null,
            "tags": [{
                "namespace": "compute",
                "key": "created",
                "value": "string"
            }],
            "filters": null
        }
    ]
}
Querying with tags

As mentioned previously, we only show the field in groupBy. So you need to add tag related fields in groupBy. For example:

"tagNamespace", "tagKey", "tagValue"

If you add tagKey, all items in the response will have a tagKey. tagKey also can be empty even if you add a tagKey. This is because some of your resources don't have a tagKey. We suggested adding all three of these in groupBy, so you can see a complete tag in the response:

"tagNamespace", "tagKey", "tagValue" 

If you want to filter by tag, you need to add the tag in the filter object. This can be filtered by any tagKey/Namespace/value combination of any tagKey/Namespace/value.

Valid groupBy example
"tagNamespace", "tagKey", "tagValue", "service", "skuName", "skuPartNumber", "unit",
"compartmentName", "compartmentPath", "compartmentId", "platform", "region", "logicalAd",
"resourceId", "tenantId", "tenantName"
"tenantId" and "tenantName" are not currently supported.
Valid filter dimension example
"service", "skuName", "skuPartNumber", "unit", "compartmentName", "compartmentPath", "compartmentId", 
"platform", "region", "logicalAd", "resourceId", "tenantId", "tenantName"
This is case-sensitive. "tenantId" and "tenantName" are not currently supported.
How to groupBy compartment?

groupBy compartment-related keys ("compartmentName", "compartmentPath", "compartmentId") are different than the other groupBy keys.

To get an expected result, you must request with compartmentDepth. compartmentDepth is >=1 and <=6.

groupBy compartment means all compartments usage or costs with a higher depth will be aggregated to the compartment with the given depth. For example:

           Root             1

        B          C        2

    D    E                  3

 F                          4

If the depth is 1, it means all usage or costs are grouped to the root compartment.

If the depth is 2, it means all compartments with depth 2 will contain the usage or costs with all its children. In the response, the root will contain its own usage, B will aggregate (B, D, E, F), and C will contain C.

Why are some fields in a response empty?

The fields will show up only when the fields are in groupBy. Not all fields in the response are currently available. Only the fields mentioned in Valid groupBy example are supported.

What is nextPageToken?

This can be set as null. Currently not supported.

Example request body

The best way to understand how the API works is checking how the Console uses the API. You can find the request body in the web browser's debug mode.

{
  "tenantId": "ocid1.tenancy.oc1..<unique_ID>",
  "timeUsageStarted": "2020-04-01T00:00:00.000Z",
  "timeUsageEnded": "2020-07-01T00:00:00.000Z",
  "granularity": "MONTHLY",
  "queryType": "COST",
  "groupBy": [
    "tagNamespace",
    "tagKey",
    "tagValue",
    "service",
    "compartmentPath"
  ],
  "compartmentDepth": 2,
  "filter": null
}

After you make a request without any filter, you can see what the dimension/tags' value can be. Subequently, you can make a request with a filter and a correct dimension value.

{
  "tenantId": "ocid1.tenancy.oc1..<unique_ID>",
  "timeUsageStarted": "2020-04-01T00:00:00.000Z",
  "timeUsageEnded": "2020-07-01T00:00:00.000Z",
  "granularity": "MONTHLY",
  "groupBy": ["tagNamespace","tagKey","tagValue", "service", "compartmentPath"],
  "compartmentDepth": 2,
  "filter": {
    "operator": "AND",
    "dimensions": [],
    "tags": [],
    "filters": [{
      "operator": "AND",
      "dimensions": [{
        "key": "service",
        "value": "compute"
      }],
      "tags": null,
      "filters": null
    }, {
      "operator": "AND",
      "dimensions": [{
        "key": "compartmentPath",
        "value": "abc/cde"
      }],
      "tags": null,
      "filters": null
    },
      {
        "operator": "AND",
        "dimensions": null,
        "tags": [{
          "namespace": "compute",
          "key": "created",
          "value": "string"
        }],
        "filters": null
      }
    ]
  }
}
Using customized scripts, CLI, and SDK

If you write a customized script, Oracle does not support or assist with debugging your script. Only the CLI, SDK, and Terraform are supported. See 3. Create and Configure a Copy of oci-curl for more information on using customized scripts, and Command Line Interface (CLI) for more information. For example:

oci raw-request --http-method POST --target-uri https://usageapi.us-ashburn-1.oci.oraclecloud.com/20200107/usage 
--request-body file:///<system_path>SimpleRequestSummarizedUsagesDetails.json 
--config-file ~/Downloads/clitest.conf
SimpleRequestSummarizedUsagesDetails.json:
{
  "tenantId": "ocid1.tenancy.oc1..<unique_ID>",
  "timeUsageStarted": "2020-03-19T17:00:00.000000-07:00",
  "timeUsageEnded": "2020-03-21T00:00:00Z",
  "granularity": "DAILY",
  "groupBy": [],
  "compartmentDepth": null,
  "filter": null,
  "nextPageToken": "string"
}
clitest.conf:
[DEFAULT]
user=ocid1.user.oc1..<unique_ID>
fingerprint=<MAC_ID>
key_file=<system_path>/oci_api_key.pem
#tenancy=ocid1.tenancy.oc1..<unique_ID>
tenancy=ocid1.tenancy.oc1..<unique_ID>
region=us-ashburn-1
Also see the Oracle Cloud Infrastructure SDK at https://github.com/oracle/oci-java-sdk , https://github.com/oracle/oci-python-sdk.