Sending Measurements
Use the measurements API to feed usage data.
General Usage: Programmatic
Measurements are the basic datapoints sent to Octane by your application that are used to calculate usage statistics.
A measurement is:
- a single value,
- associated with a specific meter, and
- representing a given point in time.
Usage
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.
A note on sending measurements
When our API receives a measurement, it adds it to a processing queue and immediately returns a success 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.
Example
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.
import octane
octane.api_key = "<YOUR_API_KEY>"
octane.Measurement.create(
meter_name="num_api_requests",
value=1,
customer_name="jsmith",
# Should match the labels specified while creating the meter
labels={"machine_id": "123"},
)
# Sending a 'reset_total' measurement in case some previous
# incremental measurements might have been missed.
octane.Measurement.create(
meter_name="num_api_requests",
value=10,
customer_name="jsmith",
labels={"machine_id": "123"},
reset_total=True,
)
import Octane from "octane-node";
const octane = new Octane("<YOUR_API_KEY>");
octane.measurements.create({
meterName: "num_api_requests",
value: 1,
customerName: "jsmith",
// Should match the labels specified while creating the meter
labels: {"machine_id": "123"}
});
// Sending a 'reset_total' measurement in case some previous
// incremental measurements might have been missed.
octane.measurements.create({
meterName: "num_api_requests",
value: 10,
customerName: "jsmith",
labels: {"machine_id": "123"},
resetTotal: true
});
package main
import "github.com/getoctane/octane-go"
func main() {
client := octane.NewClient("<YOUR_API_KEY>")
args := octane.Measurement{
MeterName: "num_api_requests",
Value: 1,
CustomerName: "jsmith",
// Should match the labels specified while creating the meter
Labels: map[string]string{
"machine_id": "123",
},
}
_, _, err := client.Measurements.Create(args)
if err != nil {
panic(err)
}
// Sending a 'reset_total' measurement in case some previous
// incremental measurements might have been missed.
args = octane.Measurement{
MeterName: "num_api_requests",
Value: 10,
CustomerName: "jsmith",
Labels: map[string]string{
"machine_id": "123",
},
ResetTotal: true,
}
_, _, err = client.Measurements.Create(args)
if err != nil {
panic(err)
}
}
Definition
| Field Name | Description | Type | Required |
|---|---|---|---|
| meter | Name of the meter the measurement is for. | String | Required |
| value | Measurement value | Float | Required |
| time | Time of the measurement | String | Required |
| customer_name | The name of the customer associated with this measurement | String | Optional. Required if there is no label that matches a customer either. |
| labels | A set of labels and their corresponding values. | Dict[String, String] | Optional |
| reset_total | Only applies for incremental meters. If true then resets the total value (within the system) to this value. Useful to correct missed incremental measurements. | Bool | Optional |
Updated 12 months ago