Allocation Telemetry

The CloudZero Allocation Telemetry API allows you to send allocation data related to your system's operations. You can read more about Allocation data in the Split Shared Costs Using Allocation Dimensions section of the documentation.

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

👍

CloudZero Allocation Legacy Endpoint

https://api.cloudzero.com/unit-cost/v1/telemetry/allocation/{stream_name}

{stream_name}: is the user defined name to associate with this Allocation stream.

Please Note: This endpoint continues to be supported, but has been deprecated. Please use the new endpoint whenever possible.

👍

CloudZero Allocation Operational Endpoints

The CloudZero Allocation Operational Endpoints allow for increased scope of operational control over your allocation telemetry streams by providing replace and delete functionality.

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

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

• sum - This endpoint is equivalent to the legacy https://api.cloudzero.com/unit-cost/v1/telemetry/allocation/{stream_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 and granularity are minimally required).

  Please Note: This action is a soft delete, so 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 allocation telemetry record describes some possible system activity by your customer, Hooli, where your production billing feature processed 250M records for this customer throughout the day of January 25th, 2020.

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

{
  "records": [
    {
    	"timestamp": "2020-01-25T00:00:00Z",
    	"granularity": "DAILY",
    	"filter": {
      	"custom:feature": [
        	"billing"
      	],
      	"tag:environment": [
          "prod"
        ],
        "tag:owner": [
          "frank",
          "sandy"
        ]
    	},
    	"element-name": "<HOOLI-CUSTOMER-ID>",
    	"value": "250000000"
    }
  ]
}

Replace

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

{
  "records": [
    {
    	"timestamp": "2020-01-25T00:00:00Z",
    	"granularity": "DAILY",
    	"filter": {
      	"custom:feature": [
        	"billing"
      	],
      	"tag:environment": [
          "prod"
        ],
        "tag:owner": [
          "frank",
          "sandy"
        ]
    	},
    	"element-name": "<HOOLI-CUSTOMER-ID>",
    	"value": "150000000"
    }
  ]
}

Delete

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

{
  "records": [
    {
    	"timestamp": "2020-01-25T00:00:00Z",
    	"granularity": "DAILY",
    	"filter": {
      	"custom:feature": [
        	"billing"
      	],
      	"tag:environment": [
          "prod"
        ],
        "tag:owner": [
          "frank",
          "sandy"
        ]
    	},
    	"element-name": "<HOOLI-CUSTOMER-ID>"
    }
  ]
}

Limits

• You may only associate 5 filter dimensions in a single stream.
• All records within a given telemetry stream must filter on the same set of dimensions.
• Filtering can specify multiple values for a dimension; a given telemetry record can specify at most 20 values for each filtered dimension.
• Filtering on multiple dimensions combine via a logical "and"; filtering on multiple values for a given dimension combine via a logical "or"
  • For example: { "account": ["1", "2"], "service": ["A"] } will match those cost records having service = "A" AND either account = "1" OR account = "2"