GuidesAPI ReferenceAcademy
API Reference

Unit Metric Telemetry

The CloudZero Unit Metric Telemetry APIs allow you to send, edit and delete cost data related to your system's operations. You can read more about Unit Metric data in the Unit Cost Analytics section of the documentation.

General Telemetry API information and limitations can be found on the Telemetry section of this documentation.

👍

CloudZero Unit Metric Legacy Endpoint

https://api.cloudzero.com/unit-cost/v1/telemetry/metric/{metric_name}

{metric_name}: is the user defined name to associate with this Unit Metric.

👍

CloudZero Unit Metric Operational Endpoints

The CloudZero Unit Metric Operational Endpoints allow for increased scope of operational control over your unit metric telemetry streams by providing replace and delete functionality.

https://api.cloudzero.com/unit-cost/v1/telemetry/metric/{metric_name}/sum
https://api.cloudzero.com/unit-cost/v1/telemetry/metric/{metric_name}/replace
https://api.cloudzero.com/unit-cost/v1/telemetry/metric/{metric_name}/delete

{metric_name}: is the user defined name to associate with this Unit Metric. When using the sum and replace operations, if a stream with this name does not exist, it will be created.

  • sum - This endpoint is equivalent to the legacy https://api.cloudzero.com/unit-cost/v1/telemetry/metric/{metric_name} endpoint, but provides syntactic consistency.

  • replace - This endpoint will replace any data within the specified stream that matches the supplied properties (timestamp and granularity are minimally required).

  • delete - This endpoint will delete any data within the appropriate stream that matches the supplied properties (timestamp is minimally required).

    Please Note: This action is a soft delete. The data will still exist in our datastore, but will be hidden. If you need a more permanent deletion, please contact us.

Examples

Legacy & Sum

The following metric record specifies some system activity -- a count of audio streams on December 7, 2023, when 12,325 people listened to a particular sea star attempt to play mayonnaise as an instrument.

When sent to the legacy or sum endpoints, this record will be added to the existing data.

{
  "records": [
    {
      "timestamp": "2023-12-07T00:00:00",
      "value": "12345",
      "associated_cost": 
        {
          "custom:Client": "Patric Star",
          "custom:Product": "Mayonaise",
          "custom:Product Group": "Instruments"
        }
      }
   ]
}

Replace

The following unit metric record, when sent to the replace endpoint, replaces the above with a new value.

{
  "records": [
    {
      "timestamp": "2023-12-07T00:00:00",
      "value": "67890",
      "associated_cost": 
        {
          "custom:Client": "Patric Star",
          "custom:Product": "Mayonaise",
          "custom:Product Group": "Instruments"
        }
      }
   ]
}

Delete

The following unit metric, when sent to the delete endpoint, deletes the record entirely.

{
  "records": [
    {
      "timestamp": "2023-12-07T00:00:00",
      "associated_cost": 
        {
          "custom:Client": "Patric Star",
          "custom:Product": "Mayonaise",
          "custom:Product Group": "Instruments"
        }
      }
   ]
}

Fields

  • timestamp: ISO formatted date and time. Time can be included in this data, but will be ignored. All telemetry is at daily granularity. Time will be converted to UTC.

  • value : the metric to associate. This is a number - decimals are allowed but not required and do not include commas. Please Note: This field is not allowed on the delete operation.

    We support 15 significant digits for the value. i.e. value is rounded to the 15th significant digit.

  • associated_cost : (optional) a dictionary of CloudZero dimensions which further categorize the cost data such that the resulting unit metric can be filtered.

    • The keys and values in the associated_cost list must appear in this format: <Dimension Name>: <Dimension Value>

      • The <Dimension Name> is the human readable display name of your dimension. If the dimension you are referencing is custom (that is, not a dimension native to CloudZero), then it must include the custom: prefix.

        For example, if you made a custom dimension called My Awesome Dimension, then your <Dimension Name> would be custom:My Awesome Dimension.

        If the dimension you wanted to filter by is the CloudZero Region dimension, then your <Dimension Name> would simply be Region.

      • The <Dimension Value> must be a single value for the dimension. The value must be a string and it may not be a list.

Limits

  • Granularity is always daily. You may send data in at a higher granularity, but the data will be aggregated together to the day.

  • You may only associate 5 associated_cost dimensions with a Unit Metric.

    • All records within a stream must have the same set of dimensions defined in their associated cost parameter.

For additional examples and case studies, please see Unit Metric Case Studies