Custom Costs

Cloud Cost Management is not supported for this site.

Join the Beta!

Custom Cost is in public beta.

Overview

Custom Costs allow you to upload any cost data source to Datadog, so that you can understand the total cost of your services.

Custom Costs accepts costs in pre-defined file structures (CSV or JSON). These files are aligned with the FinOps FOCUS specification, and you can upload multiple files in either format. For example, you can upload a mix of CSV or JSON files as desired with 1+ line items (rows for CSV or objects for JSON).

All line items must meet the following requirements and include the properties below:

  • All column names (CSV), property names (JSON), and values are UTF-8 encoded.
  • All required column names (CSV) or property names (JSON) are PascalCased. For example, you must use "ProviderName", not "providername" or "ProviderNAME".
  • All column names (CSV) and values or property names (JSON) and values have a maximum of 1,000 characters.
  • NULL or blank ("") parameter values are not accepted.
  • All of the data is viewed as UTC.

Setup

To use Custom Costs in Datadog, you must configure Cloud Cost Management for either AWS, Azure, or Google Cloud.

Collect the required fields

ParameterDescriptionValid exampleInvalid exampleAdditional Requirements
ProviderNameThe service being consumed.Snowflake"" or NULL
ChargeDescriptionIdentifies what aspect of a service is being charged.Database Costs"" or NULL
ChargePeriodStartStart day of a charge.2023-09-012023-01-01 12:34:56Formatted YYYY-MM-DD, where ChargePeriodStart <= ChargePeriodEnd.
ChargePeriodEndLast day of a charge.2023-09-3001/01/2023Formatted YYYY-MM-DD.
BilledCostThe amount being charged.10.00NaNNumber-based decimal.
BillingCurrencyCurrency of billed cost.USDEURMust be USD.

Create a CSV or JSON file with required fields

You can upload multiple CSV and JSON files, in either or both formats. Ensure that you don’t upload the same file twice, since the cost will appear as doubled in the product.

The required fields must appear as columns in your CSV in the order listed above. You need to use a comma (,) as a separator for your CSV.

Example of a valid CSV:

ProviderNameChargeDescriptionChargePeriodStartChargePeriodEndBilledCostBillingCurrency
GitHubUser Costs2023-01-012023-01-31300.00USD

Example of an invalid CSV (ChargePeriodStart is listed before ChargeDescription):

ProviderNameChargePeriodStartChargeDescriptionChargePeriodEndBilledCostBillingCurrency
GitHub2023-01-01User Costs2023-01-31300.00USD

The required fields must appear within all objects of a JSON file adhering to the ECMA-404 standard and all objects must be encapsulated by an array.

Example of a valid JSON file:

[
    {
        "ProviderName": "Zoom",
        "ChargeDescription": "Video Usage",
        "ChargePeriodStart": "2023-01-01",
        "ChargePeriodEnd": "2023-12-31",
        "BilledCost": 100.00,
        "BillingCurrency": "USD"
    }
]

Example of an invalid JSON file:

[
    {
        "providername": "Zoom",
        "chargedescription": "Video Usage",
        "chargeperiodstart": "2023-01-01",
        "chargeperiodend": "2023-12-31",
        "billedcost": 100.00,
        "billingcurrency": "USD"
    }
]

Add optional tags

You can optionally add any number of tags to CSV or JSON files to allocate costs after the required fields as additional columns.

For a CSV file, add a column per tag.

Example of a valid CSV file:

ProviderNameChargePeriodStartChargeDescriptionChargePeriodEndBilledCostBillingCurrencyteamservice
GitHub2023-01-01User Costs2023-01-31300.00USDwebops

In this example, the team and service columns are added after the BillingCurrency column, and appears as tags on this cost.

For a JSON file, add a Tags object property to encapsulate any desired tags associated to this cost.

Example of a valid JSON file:

[
    {
        "ProviderName": "Zoom",
        "ChargeDescription": "Video Usage",
        "ChargePeriodStart": "2023-01-01",
        "ChargePeriodEnd": "2023-12-31",
        "BilledCost": 100.00,
        "BillingCurrency": "USD",
        "Tags": {
            "team": "web",
            "service": "ops"
        }
    }
]

In this example, an additional Tags object property has been added with two key-value pairs to allocate team and service tags to this cost.

Configure Custom Costs

After your data is formatted to the requirements above, upload your CSV and JSON files to Cloud Cost Management on the Custom Costs Uploaded Files page or programmatically by using the API.

Navigate to Cloud Costs > Settings > Uploaded Files and click + Upload Costs.

Upload a CSV or JSON file to Datadog

To send a file, use the PUT api/v2/cost/custom_costs API endpoint.

Example with cURL:

curl -L -X PUT "api.datadoghq.com/api/v2/cost/custom_costs/" \
-H "Content-Type: multipart/form-data" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-F "file=${file};type=text/json"

Use the PUT api/v2/cost/custom_costs endpoint to send the content of the file with the API .

curl -L -X PUT "api.datadoghq.com/api/v2/cost/custom_costs/" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d '${file_content}'

Cost data appears after 24 hours.

Cost metric types

You can visualize your ingested data using the following cost types:

Cost TypeDescription
custom.cost.amortizedTotal cost of resources accrued over an interval.
custom.cost.basisTotal cost of resources allocated at the time of usage over an interval.

All costs submitted to Custom Costs appear in these metrics. For example, if a $4 purchase was made on September 1, over the September 1-4 period, the following costs are attributed to each metric:

Dayscustom.cost.basiscustom.cost.amortized
September 1$4$1
September 2-$1
September 3-$1
September 4-$1

Use Custom Costs data

You can view custom costs data on the Cloud Costs Analytics page, the Cloud Costs Tag Explorer, and in dashboards, notebooks, or monitors. You can also combine Custom Cost metrics with other cloud cost metrics or observability metrics.

Further reading