Idempotency

Understanding idempotency for Octane Measurements

📘

Advanced Topic

It is recommended that you read Sending Measurements and Measurement Labels before proceeding.

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

Definition and Use Case

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.

# Received on 01/01/2020
octane.Measurement.create(
  meter_name="num_api_requests",
  value=1,
  customer_name="jsmith",
  labels={"machine_id": "123"},
  time="2020-01-01T00:00:00"
)

# Received on 01/02/2020
octane.Measurement.create(
  meter_name="num_api_requests",
  value=5,
  customer_name="jsmith",
  labels={"machine_id": "123"},
  time="2020-01-01T00:00:00"
)

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.

Guaranteeing Idempotency

There are use-cases where the timestamp, meter and customer 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 a primary label to your meter that would help uniquely identify these measurements. We have seen examples of primary labels that include unique keys as labels in order to avoid overrides (example: adding request_id as a primary label if your meter is API Requests).

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

# Received on 01/01/2020
octane.Measurement.create(
  meter_name="num_api_requests",
  value=1,
  customer_name="jsmith",
  labels={"request_id": "a3e32e-223e2e-123kjn-1234e"},
  time="2020-01-01T00:00:00"
)

# Received on 01/02/2020
octane.Measurement.create(
  meter_name="num_api_requests",
  value=5,
  customer_name="jsmith",
  labels={"request_id": "c23edn-23enkd-5rfn3-24jn23"},
  time="2020-01-01T00:00:00"
)

Did this page help you?