billing

README

billing-client

A client library for sending usage data to the billing system.

Open sourced so it can be imported into our open-source projects.

Usage

dep ensure github.com/weaveworks/billing-client

then

import billing "github.com/weaveworks/billing-client"

func init() {
  billing.MustRegisterMetrics()
}

func main() {
  var cfg billing.Config
  cfg.RegisterFlags(flag.CommandLine)
  flag.Parse()

  client, err := billing.NewClient(cfg)
  defer client.Close()

  err = client.AddAmounts(
    uniqueKey, // Unique hash of the data, or a uuid here for deduping
    internalInstanceID,
    timestamp,
    billing.Amounts{
      billing.ContainerSeconds: 1234,
    },
    map[string]string{
      "metadata": "goes here"
    },
  )
}

Getting Help

If you have any questions about, feedback for or problems with billing-client:

• Invite yourself to the Weave Users Slack.
• Ask a question on the #general slack channel.
• File an issue.

Your feedback is always welcome!

Documentation

Index

• Variables
• func MustRegisterMetrics()
• type AmountType
• type Amounts
• type Client
  • func NewClient(cfg Config) (*Client, error)
  • func (c *Client) AddAmounts(uniqueKey, internalInstanceID string, timestamp time.Time, amounts Amounts, ...) error
  • func (c *Client) Close() error
• type Config
  • func (c *Config) RegisterFlags(f *flag.FlagSet)
• type Event

Variables

var (

	// EventsCounter is the count of billing events
	EventsCounter = prometheus.NewCounterVec(prometheus.CounterOpts{
		Namespace: "billing_client",
		Name:      "events_total",
		Help:      "Number and type of billing events",
	}, []string{"status", "amount_type"})
	// AmountsCounter is the total of the billing amounts
	AmountsCounter = prometheus.NewCounterVec(prometheus.CounterOpts{
		Namespace: "billing_client",
		Name:      "amounts_total",
		Help:      "Number and type of billing amounts",
	}, []string{"status", "amount_type"})
)

Functions

func MustRegisterMetrics

func MustRegisterMetrics()

MustRegisterMetrics is a convenience function for registering all the metrics from this package

Types

type AmountType

type AmountType string

AmountType is a type-cast of the enum for the diferent amount types

const (
	// ContainerSeconds is one of the billable metrics
	ContainerSeconds AmountType = "container-seconds"
	NodeSeconds      AmountType = "node-seconds"
	WeaveNetSeconds  AmountType = "weavenet-seconds"
	Samples          AmountType = "samples"
)

type Amounts

type Amounts map[AmountType]int64

Amounts is a map of amount billable metrics to their values

type Client

type Client struct {
	Config
	// contains filtered or unexported fields
}

Client is a billing client for sending usage information to the billing system.

func NewClient

func NewClient(cfg Config) (*Client, error)

NewClient creates a new billing client.

func (*Client) AddAmounts

func (c *Client) AddAmounts(uniqueKey, internalInstanceID string, timestamp time.Time, amounts Amounts, metadata map[string]string) error

AddAmounts writes unit increments into the billing system. If the call does not complete (due to a crash, etc), then data may or may not have been written successfully.

Requests with the same `uniqueKey` can be retried indefinitely until they succeed, and the results will be deduped.

`uniqueKey` must be set, and not blank. If in doubt, generate a uuid and set that as the uniqueKey. Consider that hashing the raw input data may not be good enough since identical data may be sent from the client multiple times.

`internalInstanceID`, is *not* the external instance ID (e.g. "fluffy-bunny-47"), it is the numeric internal instance ID (e.g. "1234").

`timestamp` is used to determine which time bucket the usage occurred in, it is included so that the result is independent of how long processing takes. Note, in the event of buffering this timestamp may *not* agree with when the charge will be billed to the customer.

`amounts` is a map with all the various amounts we wish to charge the user for.

`metadata` is a general dumping ground for other metadata you may wish to include for auditability. In general, be careful about the size of data put here. Prefer including a lookup address over whole data. For example, include a report id or s3 address instead of the information in the report.

func (*Client) Close

func (c *Client) Close() error

Close shuts down the client and attempts to flush remaining events.

type Config

type Config struct {
	MaxBufferedEvents int
	RetryDelay        time.Duration
	IngesterHostPort  string
}

Config is the config for a billing client

func (*Config) RegisterFlags

func (c *Config) RegisterFlags(f *flag.FlagSet)

RegisterFlags register the billing client flags with the main flag set

type Event

type Event struct {
	UniqueKey          string            `json:"unique_key" msg:"unique_key"`
	InternalInstanceID string            `json:"internal_instance_id" msg:"internal_instance_id"`
	OccurredAt         time.Time         `json:"occurred_at" msg:"occurred_at"`
	Amounts            Amounts           `json:"amounts" msg:"amounts"`
	Metadata           map[string]string `json:"metadata" msg:"metadata"`
}

Event is a record of some amount of billable usage for scope.