Links

Github
Releases

Quick Start

go get github.com/amberflo/metering-go/[email protected]

Ingesting meters

See API Reference
Guide

package main

import (
    "fmt"
    "time"

    "github.com/amberflo/metering-go/v2"
    "github.com/xtgo/uuid"
)

//obtain your Amberflo API Key
var apiKey = "my-api-key"

func main() {
    //Optional ingest options
    //Frequency at which queued data will be sent to API. Default is 1 second.
    intervalSeconds := 30 * time.Second
    //Number of messages posted to the API. Default is 100.
    batchSize := 5
    //Debug mode logging. Default is false.
    debug := true

    //Instantiate a new metering client
    meteringClient := metering.NewMeteringClient(
        apiKey,
        metering.WithBatchSize(batchSize),
        metering.WithIntervalSeconds(intervalSeconds),
        metering.WithDebug(debug),
    )

    customerId := "dell-10"

    //Define dimesions for your meters. Dimensions can be used as filters.
    dimensions := make(map[string]string)
    dimensions["region"] = "Midwest"
    dimensions["customerType"] = "Tech"

    for i := 0; i < 50; i++ {
        utcMillis := time.Now().UnixNano() / int64(time.Millisecond)
        //Queue meter messages for ingestion.
        //Queue will be flushed asyncrhonously when Metering.BatchSize is exceeded
        //or periodically at Metering.IntervalSeconds

        //unique ID is optional, but setting it
        //helps with de-dupe and revoking an ingested meter
        uniqueId := uuid.NewRandom().String()
        meteringError := meteringClient.Meter(&metering.MeterMessage{
            UniqueId:          uniqueId,
            MeterApiName:      "ApiCalls-From-Go",
            CustomerId:        customerId,
            MeterValue:        float64(i) + 234.0,
            MeterTimeInMillis: utcMillis,
            Dimensions:        dimensions,
        })
        if meteringError != nil {
            fmt.Println("Metering error: ", meteringError)
        }
        time.Sleep(500 * time.Millisecond)
    }

    //Perform graceful shutdown
    //Flush all messages in the queue, stop the timer,
    //close all channels, and shutdown the client
    meteringClient.Shutdown()
}

📘

Cancel an ingested meter

A meter can be cancelled by resending the same ingestion event and setting metering.CancelMeter dimension to "true". See code below.

dimensions[metering.CancelMeter] = "true"   

//cancel an ingested meter
meteringError := Metering.Meter(&metering.MeterMessage{
  UniqueId:          uniqueId,
  MeterApiName:      "ApiCalls-From-Go",
  CustomerId:        customerId,
  MeterValue:        meterValue,
  MeterTimeInMillis: utcMillis,
  Dimensions:        dimensions,
})

Query usage

See API Reference

package main

import (
    "encoding/json"
    "fmt"

    "github.com/amberflo/metering-go/v2"
)

//obtain your Amberflo API Key
var apiKey = "my-api-key"

func main() {
    customerId := "dell-8"

    //initialize the usage client
    usageClient := metering.NewUsageClient(
        apiKey,
        // metering.WithCustomLogger(customerLogger),
    )

    //set the start time of the time range in Epoch seconds
    startTimeInSeconds := (time.Now().UnixNano() / int64(time.Second)) - (24 * 60 * 60)
    timeRange := &metering.TimeRange{
        StartTimeInSeconds: startTimeInSeconds,
    }

    //specify the limit and sort order
    take := &metering.Take{
        Limit:       10,
        IsAscending: true,
    }

    // Example 1: group by customers for a specific meter and all customers
    // setup usage query params
    // visit following link for description of payload:
    // https://amberflo.readme.io/reference#usage
    usageResult, err := usageClient.GetUsage(&metering.UsagePayload{
        MeterApiName:         "ApiCalls-From-Go",
        Aggregation:          metering.Sum,
        TimeGroupingInterval: metering.Day,
        GroupBy:              []string{"customerId"},
        TimeRange:            timeRange,
    })
    fmt.Println("Usage by meterApiName in json format")
    printUsageData(*usageResult, err)

    //Example 2: filter for a meter for specific customer
    //setup usage query params
    filter := make(map[string][]string)
    filter["customerId"] = []string{customerId}

    usageResult, err = usageClient.GetUsage(&metering.UsagePayload{
        MeterApiName:         "ApiCalls-From-Go",
        Aggregation:          metering.Sum,
        TimeGroupingInterval: metering.Day,
        GroupBy:              []string{"customerId"},
        TimeRange:            timeRange,
        Filter:               filter,
    })
    fmt.Println("Usage for meter for specific customer in json format")
    printUsageData(*usageResult, err)
}

func printUsageData(usageResult metering.DetailedMeterAggregation, err error) {
    if err != nil {
        fmt.Println("Usage error: ", err)
        return
    }

    jsonString, err := json.MarshalIndent(usageResult, "", "  ")
    if err != nil {
        fmt.Println("Usage error: ", err)
        return
    }

    fmt.Println(string(jsonString))
}

Manage customers

See API Reference

package main

import (
    "fmt"

    "github.com/amberflo/metering-go/v2"
)

//obtain your Amberflo API Key
var apiKey = "my-api-key"

func main() {
    customerId := "dell-8"
    //Automatically create customer in Stripe
    //and add stripeId to traits
    createCustomerInStripe := true

    //initialize the customer client
    customerClient := metering.NewCustomerClient(
        apiKey,
        //metering.WithCustomLogger(customerLogger),
    )

    //check if customer exists
    customer, err := customerClient.GetCustomer(customerId)
    if err != nil {
        fmt.Println("Error getting customer details: ", err)
    }

    //setup customer
    if customer != nil {
        //customer exists
        //update properties
        customer.CustomerName = "Dell 2"
    } else {
        //setup new customer
        //Traits are optional. Traits can be used as filters or aggregation buckets.
        traits := make(map[string]string)
        traits["region"] = "us-west"
        traits["customerType"] = "Tech"

        //In case createCustomerInStripe is false, set the trait for stripeId
        //traits[metering.StripeTraitKey] = "cus_LVxxpBQvyN3V49"

        //Set the AWS marketplace ID trait
        //traits[metering.AwsMarketPlaceTraitKey] = "aws_marketplace_id"

        customer = &metering.Customer{
            CustomerId:    customerId,
            CustomerName:  "Dell",
            CustomerEmail: "[email protected]",
            Traits:        traits,
            Enabled:       true,
        }
    }

    customer, err = customerClient.AddorUpdateCustomer(customer, createCustomerInStripe)
    if err != nil {
        fmt.Println("Error creating customer details: ", err)
    }

    customerStatus := fmt.Sprintf("Stripe id for customer: %s", customer.Traits[metering.StripeTraitKey])
    fmt.Println(customerStatus)
}

Custom logger

By default, metering-go uses the default GO logger. You can inject your own logger by implementing the following interface Logger:

type Logger interface {
    Log(v ...interface{})
    Logf(format string, v ...interface{})
}

Define the custom logger:

package main

import (
    "fmt"
    "os"

    "github.com/rs/zerolog"
)

type CustomLogger struct {
    logger *zerolog.Logger
}

func NewCustomLogger() *CustomLogger {
    logLevel := zerolog.DebugLevel
    zerolog.SetGlobalLevel(logLevel)
    logger := zerolog.New(os.Stdout).With().Timestamp().Logger()
    return &CustomLogger{logger: &logger}
}

func (l *CustomLogger) Log(args ...interface{}) {
    msg := fmt.Sprintln(args...)
    l.logger.Debug().Msg(msg)
}

func (l *CustomLogger) Logf(format string, args ...interface{}) {
    l.logger.Debug().Msgf(format, args...)
}

Instantiate metering client with custom logger:

package main

import (
    "github.com/amberflo/metering-go/v2"
)

//obtain your Amberflo API Key
var apiKey = "my-api-key"

func main() {
    customerLogger := NewCustomLogger()

    //Instantiate a new metering client with custom logger
    meteringClient := metering.NewMeteringClient(
        apiKey,
        metering.WithLogger(customerLogger),
    )

    //initialize the usage client with custom logger
    usageClient := metering.NewUsageClient(
        apiKey,
        metering.WithCustomLogger(customerLogger),
    )

    //initialize the usage cost client with custom logger
    usageCostClient := metering.NewUsageCostClient(
        apiKey,
        metering.WithCustomLogger(customerLogger),
    )
}

Query usage cost with paging

See API Reference

package main

import (
    "encoding/json"
    "fmt"

    "github.com/amberflo/metering-go/v2"
)

//obtain your Amberflo API Key
var apiKey = "my-api-key"

func main() {
    customerId := "dell-8"

    //initialize the usage cost client
    usageCostClient := metering.NewUsageCostClient(
        apiKey,
        // metering.WithCustomLogger(customerLogger),
    )

    //set the start time of the time range in Epoch seconds
    startTimeInSeconds := (time.Now().UnixNano() / int64(time.Second)) - (24 * 60 * 60)
    timeRange := &metering.TimeRange{
        StartTimeInSeconds: startTimeInSeconds,
    }

    // paging
    pageIndex := int64(1)
    page := &metering.Page{
        Number: pageIndex,
        Size:   2,
    }

    // Example 1: group by product plan
    // setup usage cost query params
    // visit following link for description of payload:
    // https://docs.amberflo.io/reference/post_payments-cost-usage-cost
    for pageIndex < 5 {
        usageCostResultForPage, err := usageCostClient.GetUsageCost(&metering.UsageCostsKey{
            TimeGroupingInterval: metering.Day,
            GroupBy:              []string{"product_plan_id"},
            TimeRange:            timeRange,
            Page:                 page,
        })

        fmt.Println("Usage Cost Result for page: ", pageIndex)
        printUsageCostData(*usageCostResultForPage, err)

        //increment the page number
        pageIndex = pageIndex + 1
        //obtain total pages from result and stop if limit reached
        if usageCostResultForPage.PageInfo.TotalPages < pageIndex {
            break
        }

        page.Number = pageIndex
        //a token from a previous query page result to track pages and improve performance
        pageToken := usageCostResultForPage.PageInfo.PageToken
        page.Token = pageToken
    }
}

func printUsageCostData(usageCostResult metering.UsageCosts, err error) {
    if err != nil {
        fmt.Println("Usage cost error: ", err)
        return
    }

    jsonString, err := json.MarshalIndent(usageCostResult, "", "  ")
    if err != nil {
        fmt.Println("Usage cost error: ", err)
        return
    }

    fmt.Println(string(jsonString))
}

Pricing plans

See API Reference

package main

import (
    "encoding/json"
    "fmt"

    "github.com/amberflo/metering-go/v2"
)

//obtain your Amberflo API Key
var apiKey = "my-api-key"

func main() {   
    customerId := "dell-8"

    //Assign pricing plan to customer
    productPlanId := "8e880691-1ae8-493b-b0a7-12a71e5dfcca"
    customerPricingClient := metering.NewCustomerPricingPlanClient(apiKey)
    customerPricingPlan, err := customerPricingClient.AddOrUpdate(&metering.CustomerProductPlan{
        ProductPlanId:      productPlanId,
        CustomerId:         customerId,
        StartTimeInSeconds: (time.Now().UnixNano() / int64(time.Second)),
    })

    if err != nil {
        fmt.Println("Error assigning customer plan: ", err)
    }
    pricingStatus := fmt.Sprintf("Customer pricing plan %s assigned to customer %s", customerPricingPlan.ProductPlanId, customerId)
    fmt.Println(pricingStatus)
}

Prepaid Client

See API Reference

package main

import (
    "fmt"
    "time"

    "github.com/amberflo/metering-go/v2"
    "github.com/xtgo/uuid"
)

//obtain your Amberflo API Key
var apiKey = "my-api-key"

func main() {
    customerId := "dell-1800"

    startTimeInSeconds := (time.Now().UnixNano() / int64(time.Second)) - (1 * 24 * 60 * 60)

    //*****************************************
    //*****************************************
    //Prepaid SDK
    //initialize the prepaidClient 
    prepaidClient := metering.NewPrepaidClient(
        apiKey, 
        //use a custom logger
        //metering.WithCustomLogger(customerLogger), for custom logger
    )

    recurrenceFrequency := &metering.BillingPeriod{
        Interval:       metering.DAY,
        IntervalsCount: 1,
    }

    prepaidOrder := &metering.CustomerPrepaid{
        Id:                  uuid.NewRandom().String(),
        CustomerId:          customerId,
        ExternalPayment:     true,
        StartTimeInSeconds:  startTimeInSeconds,
        PrepaidPrice:        123,
        PrepaidOfferVersion: -1,
        RecurrenceFrequency: recurrenceFrequency,
    }

    // Create a prepaid order
    prepaidOrder, err := prepaidClient.CreatePrepaidOrder(prepaidOrder)
    if err != nil {
        fmt.Println("Prepaid API error: ", err)
        return
    }

    // Get a list of all active prepaid orders
    prepaidOrders, err := prepaidClient.GetActivePrepaidOrders(customerId)
    if err != nil {
        fmt.Println("Prepaid API error: ", err)
        return
    }

    // Update the external payment status of a prepaid order
    externalPrepaidPaymentStatus := &metering.ExternalPrepaidPaymentStatus{
        PaymentStatus:        metering.SETTLED,
        SystemName:           "Stripe",
        PaymentId:            "payment-id-1",
        PaymentTimeInSeconds: (time.Now().UnixNano() / int64(time.Second)),
        PrepaidUri:           prepaidOrder.FirstInvoiceUri,
    }
    externalPrepaidPaymentStatus, err = prepaidClient.UpdateExternalPrepaidStatus(externalPrepaidPaymentStatus)

    // Delete a prepaid order
    err = prepaidClient.DeletePrepaidOrder(prepaidOrder.Id, customerId)
    if err != nil {
        fmt.Println("Prepaid API error: ", err)
        return
    }

}

Signals

See API Reference
Guide

package main

import (
    "encoding/json"
    "fmt"

    "github.com/amberflo/metering-go/v2"
)

//obtain your Amberflo API Key
var apiKey = "my-api-key"

func main() {
    signalsClient := metering.NewSignalsClient(
        apiKey,
        //use a custom logger
        //metering.WithCustomLogger(customLogger), 
    )

    invoiceAlert := &metering.Notification{
        Name:               "invoice-tracker-alert",
        NotificationType:   metering.Invoice,
        Email:              []string{"[email protected]"},
        ThresholdValue:     "200",
        CustomerFilterMode: metering.PerCustomer,
        Enabled:            true,
    }

    //Create a new signal
    invoiceAlert, err := signalsClient.CreateSignal(invoiceAlert)
    if err != nil {
        fmt.Println("API error: ", err)
        return
    }

    //update an existing signal
    invoiceAlert.ThresholdValue = "150"
    invoiceAlert.Enabled = false //disable a signal without deleting
    invoiceAlert, err = signalsClient.UpdateSignal(invoiceAlert)
    if err != nil {
        fmt.Println("API error: ", err)
        return
    }

    //get an existing signal
    invoiceAlert, err = signalsClient.GetSignal(invoiceAlert.Id)
    if err != nil {
        fmt.Println("API error: ", err)
        return
    }

    //delete a signal
    invoiceAlert, err = signalsClient.DeleteSignal(invoiceAlert.Id)
    if err != nil {
        fmt.Println("API error: ", err)
        return
    }
    fmt.Println("signal with following id deleted: ", invoiceAlert.Id)
}

Batching Records

Amberflo.io libraries are built to support high throughput environments. That means you can safely send hundreds of meter records per second. For example, you can chose to deploy it on a web server that is serving hundreds of requests per second.

However, every call does not result in a HTTP request, but is queued in memory instead. Messages are batched and flushed in the background, allowing for much faster operation. The size of batch and rate of flush can be customized.

Defaults: The library will flush every 100 messages (configuration parameter: BatchSize ) or
if 1 second has passed since the last flush (configuration parameter: IntervalSeconds)
There is a maximum of 500KB per batch request and 32KB per call.

Flush on demand (Blocking call)

You can flush on demand. For example, at the end of your program, you’ll want to flush to make sure there’s nothing left in the queue. Just call the flush method:

metering.Flush()

Please note: Calling this method will block the calling thread until there are no messages left in the queue. So, you’ll want to use it as part of your cleanup scripts and avoid using it as part of the request lifecycle.