telemetry

Documentation

Overview

Package telemetry allows you to add telemetry to your plugins. For Rudder, you can set the data plane URL and the write key on build time, to allow having different keys for production and development. If you are working on a Mattermost project, the data plane URL is already set. In order to default to the development key we have to set an environment variable during build time. Copy the following lines in build/custom.mk to setup that variable.

ifndef MM_RUDDER_WRITE_KEY
  MM_RUDDER_WRITE_KEY = 1d5bMvdrfWClLxgK1FvV3s4U1tg
endif

To use this environment variable to set the key in the plugin, you have to add this line after the previous ones.

LDFLAGS += -X "github.com/mattermost/mattermost-plugin-api/experimental/telemetry.rudderWriteKey=$(MM_RUDDER_WRITE_KEY)"

MM_RUDDER_WRITE_KEY environment variable must be set also during CI to the production write key ("1dP7Oi78p0PK1brYLsfslgnbD1I"). If you want to use your own data plane URL, add also this line and make sure the MM_RUDDER_DATA_PLANE_URL environment variable is set.

LDFLAGS += -X "github.com/mattermost/mattermost-plugin-api/experimental/telemetry.rudderDataPlaneURL=$(MM_RUDDER_DATA_PLANE_URL)"

In order to use telemetry you should:

1. Add the new fields to the plugin type Plugin struct { plugin.MattermostPlugin ... telemetryClient telemetry.Client tracker telemetry.Tracker }
2. Start the telemetry client on plugin activate func (p *Plugin) OnActivate() error { p.telemetryClient, err = telemetry.NewRudderClient() if err != nil { p.API.LogWarn("telemetry client not started", "error", err.Error()) } }
3. Init and update the tracker on configuration change func (p *Plugin) OnConfigurationChange() error { ... p.tracker = telemetry.NewTracker(p.telemetryClient, p.API.GetDiagnosticId(), p.API.GetServerVersion(), manifest.Id, manifest.Version, "pluginName", enableDiagnostics, logger) return nil }
4. Close the client on plugin deactivate func (p *Plugin) OnDeactivate() error { if p.telemetryClient != nil { err := p.telemetryClient.Close() if err != nil { p.API.LogWarn("OnDeactivate: failed to close telemetryClient", "error", err.Error()) } } return nil }

Index

• type Client
  • func NewRudderClient() (Client, error)
  • func NewRudderClientWithCredentials(writeKey, dataPlaneURL string) (Client, error)
• type Track
• type Tracker
  • func NewTracker(c Client, ...) Tracker

Types

type Client

type Client interface {
	// Enqueue adds a tracker event (Track) to be registered
	Enqueue(t Track) error
	// Close closes the client connection, flushing any event left on the queue
	Close() error
}

Client defines a telemetry client

func NewRudderClient

func NewRudderClient() (Client, error)

NewRudderClient creates a new telemetry client with Rudder using the default configuration.

func NewRudderClientWithCredentials

func NewRudderClientWithCredentials(writeKey, dataPlaneURL string) (Client, error)

NewRudderClientWithCredentials lets you create a Rudder client with your own credentials.

type Track

type Track struct {
	UserID     string
	Event      string
	Properties map[string]interface{}
}

Track defines an event ready for the client to process

type Tracker

type Tracker interface {
	// TrackEvent registers an event through the configured telemetry client
	TrackEvent(event string, properties map[string]interface{}) error
	// TrackUserEvent registers an event through the configured telemetry client associated to a user
	TrackUserEvent(event string, userID string, properties map[string]interface{}) error
}

Tracker defines a telemetry tracker

func NewTracker

func NewTracker(
	c Client,
	diagnosticID,
	serverVersion,
	pluginID,
	pluginVersion,
	telemetryShortName string,
	enableDiagnostics bool,
) Tracker

NewTracker creates a default Tracker - c Client: A telemetry client. If nil, the tracker will not track any event. - diagnosticID: Server unique ID used for telemetry. - severVersion: Mattermost server version. - pluginID: The plugin ID. - pluginVersion: The plugin version. - telemetryShortName: Short name for the plugin to use in telemetry. Used to avoid dot separated names like `com.company.pluginName`. If a empty string is provided, it will use the pluginID. - enableDiagnostics: Whether the system has enabled sending telemetry data. If false, the tracker will not track any event. - l Logger: A logger to log any error related with the telemetry tracking.