cyfe

README

cyfe-go

cyfe-go is a Go SDk for integrating with the Cyfe Push API as described in the docs. Configuration is handled through a file or through the environment.

Installation

Using your favorite dependency manager, make sure to add github.com/kvss/cyfe-go. For example, with dep,

dep ensure -add github.com/kvss/cyfe-go

Usage

Usage is fairly straight-forward. See Configuration for more information about setting up and configuring the SDK.

Important: No calls will actually be made unless you set CYFE_ENV to production. This is to prevent populating your widgets with data from things like unit tests or development environments.

Once configured, there are two primary APIs to interact with. Push is the primary function, allowing for customizing the metrics. JustPush uses only the defaults and exists to be a simpler call if no further customization is needed.

request, ret, err := JustPush("User Signup", "1")

options := PushOptions{
  ReplaceInstead:      true,
  Color:               "#000000",
  Type:                "Line",
  IsCumulative:        true,
  DisplayAverages:     true,
  OverwriteTotal:      true,
  OverwriteComparison: true,
  IsBad:               true,
  IsUpsideDownGraph:   true,
  UnsyncYAxis:         true,
  YAxisMin:            "-2",
  YAxisMax:            "10",
  YAxisShow:           true,
  ShowLabel:           true,
}
request, err := Prepare("User Signup", "10", "", "", &options)
result, err := Push(request)

Configuration

Cyfe requires a full API end point for each widget that is pushed to. Obviously, it could be a challenge to hard code all of these "tokens". So, essentially, we allow you to map metrics to tokens using a TOML file or the environment. We recommend TOML, since the environment does not allow things such as spaces in metric names whereas TOML does.

The order of loading is the TOML file first. Then the environment is read and will replace any duplicates found in the file. Therefore, a common practice would be to populate the TOML file and then replace any environment-specific points with the environment.

If a metric is used but no entry is found for the metric in either the environment or the file, the calls will fail. We don't know where to send the metric. Future versions may allow a default widget to be specified.

Environment Variables

• CYFE_ENV set to production to actually make calls

• CYFE_TIMEZONE the timezone used for default dates if no key is pushed; leave blank for UTC. Uses timezone database: CYFE_TIMEZONE=America/New_York. Any valid timezone from the go time docs is valid.

• CYFE_TOKEN_FILE the name (no path, no extension) of a toml configuration file of metric/chart token pairs (see sample.toml)

• CYFE_TOKEN_* after parsing the file (if provided), any CYFE_TOKEN_* environment variables will be parsed and added

Other Libraries

We use the following additional tools in this library, and thank the maintainers and contributors of those libraries:

• testify - Makes our unit tests more readable and management

• viper - Interacting with configurations files made better

Bugs

There is currently a bug in the Cyfe docs (as of 20180702). The docs mention that if onduplicate is set to replace, it would replace the data instead of accumulating. The behavior we are seeing is that passing anything for the field triggers the replacement, even if we send in a blank string.

Documentation

Overview

Package cyfe implements the basic Push API for Cyfe in Go according to https://www.cyfe.com/api It is important to remember that no calls will actually be made if CYFE_ENV is not set to production. See Push() for more information

Index

• func JustPush(metricLabel, metricValue string) (request *PushSendRequest, ret APIReturn, err error)
• type APIReturn
  • func Push(request *PushSendRequest) (ret APIReturn, err error)
• type PushOptions
• type PushSendRequest
  • func CreateDefaultSendRequest(metricLabel string) (send *PushSendRequest)
  • func Prepare(metricLabel, metricValue, keyLabel, keyValue string, options *PushOptions) (request *PushSendRequest, err error)

Functions

func JustPush

func JustPush(metricLabel, metricValue string) (request *PushSendRequest, ret APIReturn, err error)

JustPush is a simpler Push implementation which uses just the defaults. Useful if you don't like typing and just want to get a metric to the server

Types

type APIReturn

type APIReturn struct {
	StatusCode int    `json:"statusCode"`
	Status     string `json:"status"`
	Message    string `json:"message"`
}

APIReturn is the success return from a successful push

func Push

func Push(request *PushSendRequest) (ret APIReturn, err error)

Push actually makes the push request. NOTE: If the CYFE_ENV environment variable is not set to production, the request is NOT actually sent. This is to prevent accidentally sending metrics in test or development environments.

type PushOptions

type PushOptions struct {
	// ReplaceInstead toggles whether a new push adds to the value (false, default) or replaces the value (true)
	ReplaceInstead      bool
	Color               string
	Type                string
	IsCumulative        bool
	DisplayAverages     bool
	OverwriteTotal      bool
	OverwriteComparison bool
	// IsBad specifies if a higher value for this metric is "bad" (see reverse in docs)
	IsBad             bool
	IsUpsideDownGraph bool
	UnsyncYAxis       bool
	YAxisMin          string
	YAxisMax          string
	YAxisShow         bool
	ShowLabel         bool
	// Token is available to override a token read from the end point
	Token string
}

PushOptions are a set of options for a specific Push request. Sane defaults are used (hence why the names differ than in the Cyfe API docs) so that, for example, false equates to the default behavior for instantiation

type PushSendRequest

type PushSendRequest struct {
	Data         []map[string]string `json:"data,omitempty"`
	OnDuplicate  *map[string]string  `json:"onduplicate,omitempty"`
	Color        *map[string]string  `json:"color,omitempty"`
	Type         *map[string]string  `json:"type,omitempty"`
	Cumulative   *map[string]string  `json:"cumulative,omitempty"`
	Average      *map[string]string  `json:"average,omitempty"`
	Total        *map[string]string  `json:"total,omitempty"`
	Comparison   *map[string]string  `json:"comparison,omitempty"`
	Reverse      *map[string]string  `json:"reverse,omitempty"`
	ReverseGraph *map[string]string  `json:"reversegraph,omitempty"`
	YAxis        *map[string]string  `json:"yaxis,omitempty"`
	YAxisMin     *map[string]string  `json:"yaxismin,omitempty"`
	YAxisMax     *map[string]string  `json:"yaxismax,omitempty"`
	YAxisShow    *map[string]string  `json:"yaxisshow,omitempty"`
	LabelShow    *map[string]string  `json:"labelshow,omitempty"`
	ChartToken   string              `json:"-"`
}

PushSendRequest is the formatted request to be sent to the Cyfe server

func CreateDefaultSendRequest

func CreateDefaultSendRequest(metricLabel string) (send *PushSendRequest)

CreateDefaultSendRequest initializes sane defaults for the send request. Right now it does nothing, but could be a place to override basics if needed

func Prepare

func Prepare(metricLabel, metricValue, keyLabel, keyValue string, options *PushOptions) (request *PushSendRequest, err error)

Prepare prepares a metric to be sent by filling out all of the options and formatting the data. Currently, you can only push one metric per call. A future improvement would be to allow multiple metricLabel/metricValue pairs. If keyLabel is empty or keyLabel is date AND keyValue is empty, the keyLabel will be set to Date (intentional capitalization as per the docs) and the current UTC timestamp