Sending Usage Measurements

Once you have a meter defined, you can send it measurements from anywhere using the REST API directly or any of Octane's SDKs. Measurements can be sent any time after they were taken, which can be useful for backfilling measurement information or uploading measurements taken offline.

The code snippet below demonstrates how you can create a measurement for a given meter.

First, we create a measurement for the num_of_api_requests meter. Given that this meter is incremental, we send a value of 1 to represent a single new api request received.

Later, if we realize that there might have been some incremental measurements we forgot to send, we can choose to reset the total instead of back-filling the missing values. We can reset the total to the current total value of 10 by setting the reset_total flag. After we've reset the meter's current value, we can resume sending incremental values.

If you are using event name to have multiple meters map to a single event, you should send your measurements with event_name specified instead of meter_name.

When our API receives a measurement, it adds it to a processing queue and immediately returns a success (200) response. This approach ensures that the process of recording a measurement has as little performance impact as possible. It also means that invalid measurements are detected after the API has responded. If an invalid measurement is detected, you will receive alerts through our Slack integration, or a support associate will contact you directly. Additionally, you can also view your invalid measurements and the reason for their invalidity through the UI as shown below.



Octane handles idempotency for measurements in a scalable and flexible way. Idempotency is used to ensure that multiple measurements do not override one another.

Two measurements that are received for the exact same meter and customer with the exact same timestamp (microsecond accuracy) and primary labels will override one another. The measurement that Octane receives later will take precedence and will override the previous one.

An example of two measurements that will override one another can be seen below.

As a result of the above the value for that time will be considered 5 since it was received later.

This mechanism of idempotency allows you to override measurements that you might have sent in the past. Combined with grace periods this enables a very powerful way of correcting measurements historically.

There are use-cases where the timestamp, meter and customer and label-set might not be enough to guarantee idempotency. This is applicable in high throughput distributed systems where multiple requests might happen within the same microsecond or clocks aren't synchronized.

In order to tackle this scenario you can simply add an ID to your measurement that uniquely identifies it for the set of labels. For example, you might consider setting request_id as the ID if your meter is API Requests. IDs must be unique within each (meter, customer, labels) tuple. This means that you can use the same ID to identify different measurements if they are for different meters or for different labels within the same meter.

In the example below the measurements will not override each other and will be counted as two separate values since they have different IDs.