ksurveyclient

README

Kopano Survey Client for Go

This module implements a client to submit survey data via HTTPS to a remote service.

By default, data is transmitted to the stats service operated by Kopano at https://stats.kopano.io/api/stats/v1/submit. Stats are transmitted upon initialization and afterwards in a one hour interval.

Configuration

The survey clients operation is controlled by several environment variables.

KOPANO_SURVEYCLIENT_URL
KOPANO_SURVEYCLIENT_START_DELAY
KOPANO_SURVEYCLIENT_ERROR_DELAY
KOPANO_SURVEYCLIENT_INTERVAL
KOPANO_SURVEYCLIENT_INSECURE
KOPANO_SURVEYCLIENT_ENABLED
KOPANO_SURVEYCLIENT_AUTOSURVEY

The meaning should be self explaining. To disable all survey operation, set KOPANO_SURVEYCLIENT_ENABLED to false or no. To disable the automatic start of a default survey client, set KOPANO_SURVEYCLIENT_AUTOSURVEY to false or no.

Integration

The API of this module is loosely modeled after prometheus/client_golang/prometheus and offers various levels of integration. Easiest is to import the autosurvey submodule to enable automatic gathering and submitting of the default collectors on application start by calling autosurvey.MustStart.

import (
	"stash.kopano.io/kgol/ksurveyclient-go/autosurvey"
)

func init() {
	autosurvey.MustStart(ctx, "", "")
}

Documentation

Index

• Variables
• func HashGUIDv1(rawGUID []byte) []byte
• func MustRegister(cs ...Collector)
• func Register(c Collector) error
• func StartKSurveyClient(ctx context.Context, config *Config, registry *Registry) error
• type Collector
  • func NewBasicCollector() Collector
  • func NewProgramCollector(name string, version string, guid []byte) Collector
• type Config
  • func (c *Config) Clone() *Config
• type ConstMap
  • func MustNewConstMap(name string, fields map[string]interface{}) ConstMap
  • func NewConstMap(name string, fields map[string]interface{}) (ConstMap, error)
• type Metric
• type MetricData
• type MetricSet
  • func (ms *MetricSet) MarshalJSON() ([]byte, error)
• type Registry
  • func NewRegistry() *Registry
  • func (reg *Registry) Gather() (*MetricSet, error)
  • func (reg *Registry) MustRegister(cs ...Collector)
  • func (reg *Registry) Register(c Collector) error

Variables

var (
	DefaultProgramName    = "unknown"
	DefaultProgramVersion = "0.0.0-unknown"
	DefaultProgramGUID    = []byte("")
)

Default proram name and version number which are being used when not provided directly or empty. It is exposed here so it can be overriden.

var DefaultConfig = &Config{
	URL:        "https://stats.kopano.io/api/stats/v1/submit",
	StartDelay: 60,
	ErrorDelay: 60,
	Interval:   3600,
	Insecure:   false,
	UserAgent:  "ksurveyclient-go/1.0",
}

DefaultConfig hols the service client default configuration.

var DefaultLogger logger = &noopLogger{}

DefaultLogger is the logger used by this library if no other is explicitly specified.

var SurveyClientEnabled = true

SurveyClientEnabled directly controls if surveys are sent. When false, all survice clients do nothing.

Functions

func HashGUIDv1

func HashGUIDv1(rawGUID []byte) []byte

HashGUIDv1 takes the provided GUID and returns its hash.

func MustRegister

func MustRegister(cs ...Collector)

MustRegister registers the provided Collectors with the default Registry and panics if any error occurs.

func Register

func Register(c Collector) error

Register registers the provided Collector with the default Registry.

func StartKSurveyClient

func StartKSurveyClient(ctx context.Context, config *Config, registry *Registry) error

StartKSurveyClient starts a new survey client using the provided Context and the provid Config.

Types

type Collector

type Collector interface {
	Collect(ch chan<- Metric)
}

Collector is the interface implemented by anything that can be used to collect survey Metrics.

func NewBasicCollector

func NewBasicCollector() Collector

NewBasicCollector creates a new Collector which collects basic information.

func NewProgramCollector

func NewProgramCollector(name string, version string, guid []byte) Collector

NewProgramCollector creates a Collector which collects program information.

type Config

type Config struct {
	URL        string
	StartDelay uint64
	ErrorDelay uint64
	Interval   uint64
	Insecure   bool
	UserAgent  string

	Logger     logger
	HTTPClient *http.Client
}

Config defines the settings for the service client.

func (*Config) Clone

func (c *Config) Clone() *Config

Clone returns a copy of the associated Config.

type ConstMap

type ConstMap interface {
	Metric
	Collector
}

ConstMap is a used to hold a constant set of key values.

func MustNewConstMap

func MustNewConstMap(name string, fields map[string]interface{}) ConstMap

MustNewConstMap creates a ConstMap with the provided name and field data and panics of an error occurs.

func NewConstMap

func NewConstMap(name string, fields map[string]interface{}) (ConstMap, error)

NewConstMap creates a ConstMap with the provided name and field data.

type Metric

type Metric interface {
	// Write encodes the Metric into MetricData.
	Write(*MetricData) error
}

Metric is the interface implemented by anything that can be used to provide survey Metrics.

type MetricData

type MetricData struct {
	Name   string
	Fields map[string]interface{}
}

MetricData holds the collected data with its name and fields.

type MetricSet

type MetricSet struct {
	Content []*MetricData
}

A MetricSet holds the collected MetricData.

func (*MetricSet) MarshalJSON

func (ms *MetricSet) MarshalJSON() ([]byte, error)

MarshalJSON serializes the associated MetricSet collected data to JSON.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

A Registry holds registered Collectors and collects their Metrics.

var DefaultRegistry *Registry

DefaultRegistry is a Registry which is used by default.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new Registry.

func (*Registry) Gather

func (reg *Registry) Gather() (*MetricSet, error)

Gather calls the Collect method of the registered Collectors and then gathers the collected metrics into a MetricSet.

func (*Registry) MustRegister

func (reg *Registry) MustRegister(cs ...Collector)

MustRegister registers the provided Collectors with the accociated Registry and panics if any error occurs.

func (*Registry) Register

func (reg *Registry) Register(c Collector) error

Register registers the provided Collector with the associated Registry.