telemetry

package
v0.1.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2024 License: Apache-2.0 Imports: 6 Imported by: 5

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/server/public/pluginapi/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_DATAPLANE_URL environment variable is set.

LDFLAGS += -X "github.com/mattermost/mattermost/server/public/pluginapi/experimental/telemetry.rudderDataPlaneURL=$(MM_RUDDER_DATAPLANE_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 and tracker 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())
	}
	...
	p.tracker = telemetry.NewTracker(
		p.telemetryClient,
		p.API.GetDiagnosticId(),
		p.API.GetServerVersion(),
		Manifest.Id,
		Manifest.Version,
		"plugin_short_namame",
		telemetry.NewTrackerConfig(p.API.GetConfig()),
		logger.New(p.API)
	)
}

3. Trigger tracker changes when configuration changes

func (p *Plugin) OnConfigurationChange() error {
	...
	if p.tracker != nil {
		p.tracker.ReloadConfig(telemetry.NewTrackerConfig(p.API.GetConfig()))
	}
	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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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{}
	InstallationID string
}

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
	// Reload Config re-evaluates tracker config to determine if tracking behavior should change
	ReloadConfig(config TrackerConfig)
}

Tracker defines a telemetry tracker

func NewTracker

func NewTracker(
	c Client,
	diagnosticID,
	serverVersion,
	pluginID,
	pluginVersion,
	telemetryShortName string,
	config TrackerConfig,
	l logger.Logger,
) 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. - config: Whether the system has enabled sending telemetry data. If false, the tracker will not track any event. - l Logger: A logger to debug event tracking and some important changes (it won't log if nil is passed as logger).

type TrackerConfig

type TrackerConfig struct {
	EnabledTracking bool
	EnabledLogging  bool
}

func NewTrackerConfig

func NewTrackerConfig(config *model.Config) TrackerConfig

NewTrackerConfig returns a new trackerConfig from the current values of the model.Config.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL