usage

README

KrakenD usage module

An anonymous software usage reporter with proof of work.

The KrakenD usage is designed to collect anonymous information from any software and push it to a server, but it was built for KrakenD. Read the blog post. You can use it with the following code in any app:

	if err := Report(
		ctx,
		Options{
			ClusterID:       "clusterId",
			ServerID:        "serverId",
			URL:             "https://my.usage.api.tld",
			Version:         "v1.2.3",
			ExtraPayload:    someExtraPayload,
			ReportLapse:     12 * time.Hour,
			UserAgent:       "foo bar",
			ReportEndpoint:  "/report",
			SessionEndpoint: "/session",
		},
		nil,
	); err != nil {
		t.Error(err)
		return
	}

From the options above, you must implement at least the ClusterID, ServerID, and URL. We recommend using an uuid randomly-generated for the IDs. All the options are documented here.

The processing server for this report is out of the project's scope, but you can get inspiration from the tests.

On KrakenD API gateway, the module is entirely disabled by setting an environment var USAGE_DISABLE=1, but you should decide your strategy to disable it in your application.

Note on v2

The v2 API is not compatible with the previous version, although is pretty similar. Please check the new interface for the required changes.

Documentation

Index

• Variables
• func Report(ctx context.Context, opt Options, c UsageClient) error
• type BasicClient
  • func (c *BasicClient) Send(ctx context.Context, path string, in, out interface{}) error
• type Client
  • func (c *Client) NewSession(ctx context.Context, in *SessionRequest) (*SessionReply, error)
  • func (c *Client) SendReport(ctx context.Context, in *ReportRequest) (*ReportReply, error)
• type HTTPClient
• type Minter
• type Options
• type ReportReply
• type ReportRequest
• type Reporter
  • func New(opt Options, c UsageClient) (*Reporter, error)
  • func (r *Reporter) Report(ctx context.Context)
  • func (r *Reporter) SingleReport(ctx context.Context) error
• type SessionReply
• type SessionRequest
• type UsageClient
• type UsageData
  • func (u *UsageData) Expired() bool
  • func (u *UsageData) Hash() (string, error)

Variables

var ReportExpiration = 60 * time.Second

Functions

func Report

func Report(ctx context.Context, opt Options, c UsageClient) error

Types

type BasicClient

type BasicClient struct {
	Client    *http.Client
	URL       string
	UserAgent string
}

func (*BasicClient) Send

func (c *BasicClient) Send(ctx context.Context, path string, in, out interface{}) error

type Client

type Client struct {
	HTTPClient
	SessionEndpoint string
	ReportEndpoint  string
}

func (*Client) NewSession

func (c *Client) NewSession(ctx context.Context, in *SessionRequest) (*SessionReply, error)

func (*Client) SendReport

func (c *Client) SendReport(ctx context.Context, in *ReportRequest) (*ReportReply, error)

type HTTPClient

type HTTPClient interface {
	Send(context.Context, string, interface{}, interface{}) error
}

type Minter

type Minter interface {
	Mint(string) (string, error)
}

type Options

type Options struct {
	// ClusterID identifies the cluster
	ClusterID string
	// ServerID identifies the instance
	ServerID string
	// URL is the base path of the remote service
	URL string
	// Version of the application reporting
	Version string
	// Minter is the default Minter injected into the Reporter
	Minter Minter
	// ExtraPayload is the extra information to send with the first report
	ExtraPayload []byte
	// HashBits are the number of bits of collision
	HashBits uint
	// SaltChars are the number of bytes of salt chars
	SaltChars uint
	//SessionEndpoint is the path of the session endpoint
	SessionEndpoint string
	// ReportEndpoint is the path of the report endpoint
	ReportEndpoint string
	// Timeout is the max duration of every request
	Timeout time.Duration
	// ReportLapse is the waiting time between reports
	ReportLapse time.Duration
	// UserAgent is the value of the user-agent header to send with the requests
	UserAgent string
	// Client is the http client to use. If nil, a new http client will be created
	Client *http.Client
}

type ReportReply

type ReportReply struct {
	Status  int    `json:"status"`
	Message string `json:"message,omitempty"`
}

type ReportRequest

type ReportRequest struct {
	Token string    `json:"token"`
	Pow   string    `json:"pow"`
	Data  UsageData `json:"data"`
}

type Reporter

type Reporter struct {
	Options
	Client UsageClient
	Start  time.Time
	Token  string
}

func New

func New(opt Options, c UsageClient) (*Reporter, error)

func (*Reporter) Report

func (r *Reporter) Report(ctx context.Context)

func (*Reporter) SingleReport

func (r *Reporter) SingleReport(ctx context.Context) error

type SessionReply

type SessionReply struct {
	Token string `json:"token"`
}

type SessionRequest

type SessionRequest struct {
	ClusterID string `json:"cluster_id"`
	ServerID  string `json:"server_id"`
}

type UsageClient

type UsageClient interface {
	NewSession(context.Context, *SessionRequest) (*SessionReply, error)
	SendReport(context.Context, *ReportRequest) (*ReportReply, error)
}

type UsageData

type UsageData struct {
	Version   string `json:"version"`
	Arch      string `json:"arch"`
	OS        string `json:"os"`
	ClusterID string `json:"cluster_id"`
	ServerID  string `json:"server_id"`
	Uptime    int64  `json:"uptime"`
	Time      int64  `json:"time"`
	Extra     []byte `json:"extra,omitempty"`
}

func (*UsageData) Expired

func (u *UsageData) Expired() bool

func (*UsageData) Hash

func (u *UsageData) Hash() (string, error)