Creating Meters

Learn what meters are and how to define them.

📘

General Usage: Portal

A meter defines a feature of your system that you want to measure. It sets the expectations of the measurements including what the values represent and what labels are required.

Motivation

Usage based billing per customer starts by metering applications and infrastructure. Meters can range from CPU usage to number of trees planted. It is important to maintain clear definitions and expectations of our measurements so that they are well understood and can be used accurately in analysis and price plans.

Usage

After creating a meter in Octane, you can send measurements corresponding to the meter from anywhere using Octane's REST API directly or client SDKs.

Creating meters through the portal

Definition

Field Name

Description

Type

Required

name

The meter identifier. Must be unique. Should be a dev-friendly string.
NOTE: This is shown as 'ID' in the portal.

String

Required

display_name

The name used in the UI.
NOTE: This is shown as 'Name' in the portal.

String

Optional

description

A description of the meter. Defaults to empty string.

String

Optional

unit_name

The unit associated with the meter. Defaults to unit-less (e.g., a simple count).

Enum

Optional

is_incremental

Whether the values specify an increment to the total or overwrite the existing total (see Incremental Values ). Defaults to True.

Boolean

Optional

meter_type

The meter type (i.e., 'GAUGE' or 'COUNTER'). Defaults to 'counter'.

Enum

Optional

expected_labels

A list of labels expected to be provided with every measurement for the label. Default to empty list.

List

Optional

primary_labels

A list of labels that identify a unique stream of measurements (see Independent Streams). All primary_labels should also be included as expected_labels. Defaults to empty list.

List

Optional

Creating meters programmatically

🚧

Meters should generally be created through the portal

Example 1

We start with an example for tracking the number of API requests. First, we define a "num_api_requests" meter. We specify it as an incremental counter, meaning each measurement will identify the additional number of requests made to the API (learn more here). Additionally, we specify that the labels provided with each measurement are expected to contain at least a "customer_id" field.

import octane
octane.api_key = "<YOUR_API_KEY>"

octane.Meter.create(
  name="num_api_requests",
  description="Number of API requests to the system",
  meter_type="COUNTER",
  is_incremental=True,
  primary_labels=["customer_id"],
  expected_labels=["customer_id"]
)
import Octane from "octane-node";
const octane = new Octane("<YOUR_API_KEY>");

octane.meters.create({
    name: "num_api_requests",
    description: "Number of API requests to the system",
    meterType: "COUNTER",
    isIncremental: true,
    primaryLabels: ["customer_id"],
    expectedLabels: ["customer_id"]
});
package main

import "github.com/getoctane/octane-go"

func main() {
  client := octane.NewClient("<YOUR_API_KEY>")
  
  args := octane.MeterInputArgs{
    Name:           "num_api_requests",
    Description:    "Number of API requests to the system",
    MeterType:      "COUNTER",
    IsIncremental:  true,
    PrimaryLabels:  []string{"customer_id"},
    ExpectedLabels: []string{"customer_id"},
  }
  
  _, _, err := client.Meters.Create(args)
  if err != nil {
    panic(err)
  }
}

Example 2

In this example, we define a "storage" meter. We specify it as a gauge (learn more here), meaning that measurements represent a point-in-time value that can fluctuate. We also specify the unit, so that the value of measurements are understood to be in bytes. Finally, we specify that the primary label which will contain "customer_id" to map any measurement for this meter to a specific customer. We also specify an expected label - "machine_id", this can be used later for segregating usage into different streams (learn more here).

import octane
octane.api_key = "<YOUR_API_KEY>"

octane.Meter.create(
  name="storage",
  description="Size of files in bytes",
  meter_type="GAUGE",
  unit="byte",
  primary_labels=["customer_id"],
  expected_labels=["customer_id", "machine_id"]
)
import Octane from "octane-node";
const octane = new Octane("<YOUR_API_KEY>");

octane.meters.create({
    name: "storage",
    description: "Size of files in bytes",
    meterType: "GAUGE",
    unitName: "byte",
    primaryLabels: ["customer_id"],
    expectedLabels: ["customer_id", "machine_id"]
});
package main

import "github.com/getoctane/octane-go"

func main() {
  client := octane.NewClient("<YOUR_API_KEY>")
  
  args := octane.MeterInputArgs{
    Name:           "storage",
    Description:    "Size of files in bytes",
    MeterType:      "GAUGE",
    UnitName:       "byte",
    PrimaryLabels:  []string{"customer_id"},
    ExpectedLabels: []string{"customer_id", "machine_id"},
  }
  
  _, _, err := client.Meters.Create(args)
  if err != nil {
    panic(err)
  }
}

Did this page help you?