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 NameDescriptionTypeRequired
meterName of the meter the measurement is for.StringRequired
valueMeasurement valueFloatRequired
timeTime of the measurementStringRequired
customer_nameThe name of the customer associated with this measurementStringOptional. Required if there is no label that matches a customer either.
labelsA set of labels and their corresponding values.Dict[String, String]Optional
reset_totalOnly applies for incremental meters. If true then resets the total value (within the system) to this value. Useful to correct missed incremental measurements.BoolOptional

Next Steps