telemetrydeck

README

TelemetryDeck SDK for Go

The development on this project has just started. Please don't expect anything to work until there are a few releases. Also please expect breaking API changes in every release until v1.0.0 is reached.

The Goal of this library is to facilitate sending telemetry data to the TelemetryDeck backend via the Ingest API v2.

Documentation

Overview

Package telemetrydeck

A library to send telemetry data to TelemetryDeck.

Usage synopsis

import "github.com/giantswarm/telemetrydeck-go" // imported as telemetrydeck

// Represents an event we want to track
type MySignal struct {
	// Some arbitrary string
	Command string
}

func myfunc() {
	// This is required!
	appID := os.Getenv("TELEMETRY_APP_ID")

	// This is recommended
	salt := os.Getenv("TELEMETRY_USER_HASH_SALT")

	// A unique user identifier, if desired
	email := ...

	// Create new client
	client, err := telemetrydeck.NewClient(appID).WithUserID(email).WithHashSalt(salt)
	if err != nil {
		panic(err)
	}

	// Define and transmit event to track
	signalPayload := map[string]interface{
		"command": "create",
	}
	signalType := "MyNamespace.mySignalType"
	err = client.SendSignal(context.Background(), signalType, signalPayload)
	if err != nil {
		panic(err)
	}
}

Index

• Variables
• func WithEndpoint(endpoint string) func(*Client)
• func WithHashSalt(salt string) func(*Client)
• func WithLogger(logger *log.Logger) func(*Client)
• func WithSessionID(sessionID string) func(*Client)
• func WithTestMode() func(*Client)
• func WithUserID(userID string) func(*Client)
• type Client
  • func NewClient(appID string, options ...func(*Client)) (*Client, error)
  • func (c *Client) SendSignal(ctx context.Context, signalType string, payload map[string]interface{}) error
  • func (c *Client) UserID() string
  • func (c *Client) UserIDHash() string
• type SignalBody

Examples

• NewClient

Variables

var (
	ErrNoAppID      = errors.New("no app ID specified")
	ErrNoSignalType = errors.New("no signal type specified")
)

Functions

func WithEndpoint

func WithEndpoint(endpoint string) func(*Client)

WithEndpoint allows to specify an alternative API endpoint. This is mainly useful for testing. To be used as an option parameter in the NewClient() func.

func WithHashSalt

func WithHashSalt(salt string) func(*Client)

WithHashSalt specifies a hash salt string (recommended).

This salt will be appended to the user identifier before it gets hashed and submitted to TelemetryDeck. This makes it a lot harder to de-anonymize user ID hashes, e.g. via some rainbow tables.

To be used as an option parameter in the NewClient() func.

func WithLogger

func WithLogger(logger *log.Logger) func(*Client)

WithLogger specifies a logger to use for logging errors caught during sending telemetry signals. If not given, these errors will be ignored.

To be used as an option parameter in the NewClient() func.

func WithSessionID

func WithSessionID(sessionID string) func(*Client)

WithSessionID specifies a session identifier. This should be the same value for the same session/user combination. If not given, a UUID will be generated at the creation of the client.

To be used as an option parameter in the NewClient() func.

func WithTestMode

func WithTestMode() func(*Client)

WithTestMode activates test mode.

When set, data will be sent with isTestMode=true, to avoid polluting production data. Also, errors will be logged that would otherwise be silently ignored.

To be used as an option parameter in the NewClient() func.

func WithUserID

func WithUserID(userID string) func(*Client)

WithUserID specifies a unique user identifier.

The identifier will be salted and hashed before submitting to the TelemetryDeck API.

If no unique user ID is specific, an identifier is generated.

To be used as an option parameter in the NewClient() func.

Types

type Client

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

Client represents a TelemetryDeck client, configured to represent one distinct user interacting with one distinct application.

func NewClient

func NewClient(appID string, options ...func(*Client)) (*Client, error)

NewClient instantiates a new client to send data to TelemetryDeck, and also starts a new session. The appID is the only required parameter. Any number of optional parameters can be passed using the With...() functions.

Example

client, err := NewClient("my-app-id", WithUserID("somebody@example.com"), WithHashSalt("mySalt"))
if err != nil {
	panic(err)
}

err = client.SendSignal(context.Background(), "mySignalType", map[string]interface{}{"command": "sample command"})
if err != nil {
	panic(err)
}

func (*Client) SendSignal

func (c *Client) SendSignal(ctx context.Context, signalType string, payload map[string]interface{}) error

SendSignal sends a signal to the TelemetryDeck backend.

The signalType is a string of your choice, identifying the type of the signal you are sending, e.g. "command". From the TelemetryDeck docs:

"While it is not enforced, we recommend structuring your signal names in namespaces separated by dots, with the signal type beginning with a lower case letter and any namespaced beginning with an uppercase letter."

The payload is a map of key-value pairs, containing the data you want to send.

Errors that occur during submission of the request to TelemetryDeck are not returned. Instead they are printed if the client has been configured with a logger (see WithLogger).

func (*Client) UserID

func (c *Client) UserID() string

Returns the user ID set in the client (unhashed).

func (*Client) UserIDHash

func (c *Client) UserIDHash() string

Returns the user ID hash set in the client.

type SignalBody

type SignalBody struct {
	AppID      string                 `json:"appID"`
	ClientUser string                 `json:"clientUser"`
	SessionID  string                 `json:"sessionID"`
	IsTestMode bool                   `json:"isTestMode"`
	Type       string                 `json:"type"`
	Payload    map[string]interface{} `json:"payload"`
}