Idempotency

📘

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 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.

📘

Any subsequent measurements sent with the same ID will overwrite the value of the previous measurement(s).

🚧

Changing the time of a measurement is not supported. Only the value can be updated.

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

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

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