Skip to main content

Per Unit Costs

A unit is any metric that your business tracks, such as users, requests, transactions, customers, vendors, and so on. Unit costs can help you analyze the cost of goods sold (COGS). You can add unit costs as a visualization on Cost Reports to visualize your cloud infrastructure costs on a per unit basis. Business metrics are the units of data from your business that are aggregated and combined with costs to produce per unit costs on Cost Reports. By importing these business metrics into Vantage, you can track unit costs, like cost per daily active user, COGS per customer, cost per million API requests, etc.

In the visual example below, the business metric Per Requests per Second is visualized in the graph as a red line alongside daily costs. You can use this visualization to understand how changes in the request metric contribute to changes in your costs.

Per Unit Costs displayed as a trend line on the graph in a Cost Report

Import Business Metrics

Business metrics can be imported from other systems directly into Vantage and analyzed alongside cost data. You can create automatic import integrations with Amazon CloudWatch, manually import these metrics from a CSV file, or automatically upload metrics via the Vantage API.

note

The following steps are for importing via CloudWatch or a CSV file. If you want to automatically import metrics, see Import via the Vantage API.

  1. From the top navigation, click Financial Planning.
  2. On the left navigation, click Business Metrics. All existing business metrics are displayed. You can edit or delete business metrics from this screen.
  3. From the top right of the screen, click New Business Metric.
  4. Enter a business metric Title and click Create Business Metric.
  5. The Business Metrics screen is displayed:

Import from a CSV File

You can upload a CSV file that uses the following two-column format. This CSV file can replace existing data or be used to import new data. You can supply up to six months of metrics.

The date column must be in YYYY-MM-DD format. The amount column must be a number.

date,amount
2024-01-09,295
2024-01-16,909
2024-01-23,934
2024-01-30,772
2024-02-06,770
2024-02-13,170
2024-02-20,819
2024-02-27,307
...

Click Upload a CSV. Select the CSV file and upload. After the file is imported, a dropdown menu for each month is displayed. For months with imported metrics, the date and associated metric number are displayed. Months with no metrics are blank.

Click to view visual example
The Imported Costs section with costs displayed for a month

To add additional metrics or change the value of a metric, update your source CSV file. Then, click Edit and upload the edited file. The new or updated metric is displayed in the table. See the Assign Business Metrics to Cost Reports section for the next steps.

Import from CloudWatch

To import business metrics from Amazon CloudWatch you need a specific metric name and AWS account, as described below.

note

If Vantage does not have a Cross-Account IAM Role associated with your AWS account, you need to create one. See the AWS integration documentation for details.

  1. From the Import Business Metrics section, click Import via CloudWatch.
  2. For AWS Account, select the connected AWS account you want to import metrics from.
  3. Select an AWS Region.
  4. Enter a Namespace. A complete list of available namespaces can be found in the AWS documentation for AWS services that publish CloudWatch Metrics. Namespaces start with AWS/ followed by the service name (e.g., AWS/EC2).
  5. Enter a Metric name. Each AWS service has metrics that it sends to CloudWatch. Available metrics can be found in CloudWatch or the AWS documentation.
    tip

    The AWS documentation includes a list of available metrics for services. For example, you can view EC2 instance metrics. An example metric to track in this instance is CPUUtilization. For Amazon RDS, an example metric to track is WriteIOPS or ReadIOPS.

  6. For Dimensions, enter a Name and Value. Dimensions are used to pull specific statistical data for a metric. For example, enter InstanceId with a value of i-1234567890abcdef0. Each CloudWatch metric has a set of dimensions you can select. Click + Add a Dimension to add more than one dimension.
  7. For each import, you must specify the Aggregation function to be used because metrics will be aggregated to the day. Select either Sum, Average, Maximum, or Minimum.
  8. Click Import Data.
    Click to view visual example
    The CloudWatch metrics import screen with data added to each field

Metrics will be imported for the last six months. The metrics will be automatically synced, daily, along with cost data from other integrations. See the Assign Business Metrics to Cost Reports section for the next steps.

Import via the Vantage API

You can import business metrics to Vantage, from other applications, with the Vantage API. Use the /business_metrics endpoint to view, create, update, and delete business metrics.

info

The basic steps for using this endpoint are provided below. See the API documentation for details on parameters, sample requests, and sample responses.

Prerequisites

Ensure you have a valid Read/Write Vantage API token.

Create a Business Metric

The following example shows how to create a business metric by sending a POST request to the /business_metrics endpoint.

curl --request POST \
--url https://api.vantage.sh/v2/business_metrics \
--header 'accept: application/json' \
--header 'authorization: Bearer <AUTH_TOKEN>' \
--header 'content-type: application/json' \
--data '
{
"title": "API Requests",
"cost_report_tokens_with_metadata": [
{
"unit_scale": "per_unit",
"cost_report_token": "rprt_12abc345def678gh"
}
],
"values": [
{
"date": "2024-02-01",
"amount": 1512
},
{
"date": "2024-02-02",
"amount": 1816
},
{
"date": "2024-02-03",
"amount": 1236
}
]
}
'
  • title is a string that represents the business metric title (e.g., Requests or CPUUtilization).
  • cost_report_tokens_with_metadata is an array of objects that represents one or more Cost Reports you want the business metric to be added to.
    • cost_report_token is the unique token for the Cost Report.
      tip

      You can access cost_report_tokens via the /cost_reports endpoint.

    • The unit_scale determines the scale of the business metric's values within the Cost Report. It has a default value of per_unit. Other options include per_hundred, per_thousand, per_million, and per_billion.
  • values is an array of objects that comprises the date and amount key/value pairs associated with each business metric data point.
    • date needs to be in YYYY-MM-DD format.
    • amount needs to be a number.

The following JSON is returned in a successful 201 response, which includes the unique business metric token. Dates in the response are displayed in ISO 8601 format.

{
"token": "bsnss_mtrc_ab12345cde67fg8",
"title": "API Requests",
"created_by_token": "usr_0a123456789abcde",
"cost_report_tokens_with_metadata": [
{
"cost_report_token": "rprt_12abc345def678gh",
"unit_scale": "per_unit"
}
],
"values": [
{ "date": "2024-02-01T00:00:00Z", "amount": "1512.0" },
{ "date": "2024-02-02T00:00:00Z", "amount": "1816.0" },
{ "date": "2024-02-03T00:00:00Z", "amount": "1236.0" }
]
}

Update a Business Metric

If you need to update or add additional data to a business metric, send a PUT request to the /business_metrics/{business_metric_token} endpoint. In the below example, an additional month of data is added to the business metric that was previously created. The request url includes the unique business metric token, received in the response from the POST call, to update the data.

curl --request PUT \
--url https://api.vantage.sh/v2/business_metrics/bsnss_mtrc_ab12345cde67fg8 \
--header 'accept: application/json' \
--header 'authorization: Bearer <AUTH_TOKEN>' \
--header 'content-type: application/json' \
--data '
{
"values": [
{"date": "2024-03-01", "amount": 1743},
{"date": "2024-03-02", "amount": 1356},
{"date": "2024-03-03", "amount": 1563}
]
}
'

The following JSON is returned in a successful 201 response.

{
"token": "bsnss_mtrc_ab12345cde67fg8",
"title": "API Requests",
"created_by_token": "usr_0a123456789abcde",
"cost_report_tokens_with_metadata": [
{
"cost_report_token": "rprt_12abc345def678gh",
"unit_scale": "per_unit"
}
],
"values": [
{ "date": "2024-02-01T00:00:00Z", "amount": "1512.0" },
{ "date": "2024-02-02T00:00:00Z", "amount": "1816.0" },
{ "date": "2024-02-03T00:00:00Z", "amount": "1236.0" },
{ "date": "2024-03-01T00:00:00Z", "amount": "1743.0" },
{ "date": "2024-03-02T00:00:00Z", "amount": "1356.0" },
{ "date": "2024-03-03T00:00:00Z", "amount": "1563.0" }
]
}

You can also upload data via a CSV. Send a PUT request to the /business_metrics/{business_metric_token}/values.csv endpoint using the business metric’s token. Specify a path to the CSV in the csv parameter.

curl --request PUT \
--url https://api.vantage.sh/v2/business_metrics/bsnss_mtrc_ab12345cde67fg8/values.csv \
--header 'accept: application/json' \
--header 'authorization: Bearer <AUTH_TOKEN>' \
--header 'content-type: multipart/form-data' \
--form 'csv=@<PATH_TO_CSV>'

Additional API Actions

To get all business metrics your API token has access to, send a GET request to the endpoint.

curl --request GET \
--url https://api.vantage.sh/v2/business_metrics \
--header 'accept: application/json' \
--header 'authorization: Bearer <AUTH_TOKEN>'

You can also specify a specific business metric token in the url to get data for only one business metric.

curl --request GET \
--url https://api.vantage.sh/v2/business_metrics/bsnss_mtrc_ab12345cde67fg8 \
--header 'accept: application/json' \
--header 'authorization: Bearer <AUTH_TOKEN>'

If you want to remove values for certain dates, you can pass an empty value as the amount for that date. Send a PUT request to the /business_metrics/{business_metric_token} endpoint using the business metric’s token. In the below example, an existing amount is removed for March 10th.

curl --request PUT \
--url https://api.vantage.sh/v2/business_metrics/bsnss_mtrc_ab12345cde67fg8 \
--header 'accept: application/json' \
--header 'authorization: Bearer <AUTH_TOKEN>' \
--header 'content-type: application/json' \
--data '
{
"values": [
{
"date": "2024-03-10T00:00:00Z",
"amount": null
}
]
}
'

If you want to completely delete a business metric, send a DELETE request to the /business_metrics endpoint, and specify the token for the business metric you want to delete in the url.

curl --request DELETE \
--url https://api.vantage.sh/v2/business_metrics/bsnss_mtrc_ab12345cde67fg8 \
--header 'accept: application/json' \
--header 'authorization: Bearer <AUTH_TOKEN>'
danger

Keep in mind that the DELETE action is a permanent action, and you will no longer have access to that business metric or see it displayed on corresponding reports.

Assign Business Metrics to Cost Reports

Assign metric to cost report

Once your import is complete you can assign metrics to one or more Cost Reports. You can also assign as many different business metrics to a Cost Report as you want.

  1. Under Assigned Cost Reports, click + Add a Report.
  2. In the Report dropdown menu, search for and select a Cost Report.
  3. For Unit Scale, select either Per Unit, Per Hundred, Per Thousand, Per Million, or Per Billion. The scale is used to divide the business metric before calculating the cost per unit. Use this scale to create a per-unit cost, such as Cost per Thousand Requests. If you select Per Unit, no division occurs, and the actual metric number will be used within the Cost Report.
  4. Click Save. The metric is displayed on the corresponding Cost Report based on the selected scale.

View Per Unit Costs on Cost Reports

Per Unit Costs displayed on a Cost Report

To inspect your unit costs, navigate to the assigned Cost Report. The average unit cost for the date range selected is displayed at the top of the screen.

tip

To see the cost per unit line, ensure your view is set to daily, weekly, or monthly.

Hover over a data point to see the cost per unit for that day, week, or month. If you add multiple business metrics to the same Cost Report, each business metric is displayed as a separate line, as shown in the example above.