event

README

Masa Protocol Event Tracking Package

A Go package for tracking and sending analytics events.

Features

• In-memory event storage
• Configurable event sending to external API
• Thread-safe operations
• Comprehensive logging with logrus
• Convenience methods for common event types

Usage

import "github.com/masa-finance/masa-oracle/pkg/event"

// Create a new event tracker with default config
tracker := event.NewEventTracker(nil)

// Track a custom event
tracker.TrackEvent("custom_event", map[string]interface{}{"key": "value"})

// Use convenience method to track and send a login event
client := event.NewEventClient("https://api.example.com", logger, 10*time.Second)
err := tracker.TrackUserLogin("user123", client)
if err != nil {
    log.Fatal(err)
}

// Retrieve all tracked events
events := tracker.GetEvents()

// Clear all tracked events
tracker.ClearEvents()

Event Library

The package provides a set of predefined events for common scenarios:

Work Distribution

func (a *EventTracker) TrackWorkDistribution(workType data_types.WorkerType, remoteWorker bool, peerId string, client *EventClient) error

Tracks the distribution of work to a worker. Event data includes:

• peer_id: String containing the peer ID
• work_type: The WorkerType as a string
• remote_worker: Boolean indicating if it's a remote worker

Work Completion

func (a *EventTracker) TrackWorkCompletion(workType data_types.WorkerType, success bool, peerId string, client *EventClient) error

Records the completion of a work item. Event data includes:

• peer_id: String containing the peer ID
• work_type: The WorkerType as a string
• success: Boolean indicating if the work was successful

Worker Failure

func (a *EventTracker) TrackWorkerFailure(workType data_types.WorkerType, errorMessage string, peerId string, client *EventClient) error

Records a failure that occurred during work execution. Event data includes:

• peer_id: String containing the peer ID
• work_type: The WorkerType as a string
• error: String containing the error message

Contributing

Contributions are welcome! Please submit a pull request or create an issue for any bugs or feature requests.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Documentation

Index

• Constants
• type Config
  • func DefaultConfig() *Config
• type Event
• type EventClient
  • func NewEventClient(baseURL string, logger *logrus.Logger, timeout time.Duration) *EventClient
  • func (c *EventClient) SendEvent(event Event) error
• type EventTracker
  • func NewEventTracker(config *Config) *EventTracker
  • func (a *EventTracker) ClearEvents()
  • func (a *EventTracker) GetEvents() []Event
  • func (a *EventTracker) TrackAndSendEvent(event Event, client *EventClient) error
  • func (a *EventTracker) TrackEvent(event Event)
  • func (a *EventTracker) TrackLocalWorkerFallback(workType data_types.WorkerType, reason string, peerId string)
  • func (a *EventTracker) TrackRemoteWorkerConnection(workType data_types.WorkerType, peerId string)
  • func (a *EventTracker) TrackStreamCreation(workType data_types.WorkerType, peerId string, protocol string)
  • func (a *EventTracker) TrackWorkCompletion(workType data_types.WorkerType, success bool, recordCount int, peerId string)
  • func (a *EventTracker) TrackWorkDistribution(workType data_types.WorkerType, remoteWorker bool, peerId string)
  • func (a *EventTracker) TrackWorkExecutionStart(workType data_types.WorkerType, remoteWorker bool, peerId string)
  • func (a *EventTracker) TrackWorkExecutionTimeout(workType data_types.WorkerType, timeoutDuration time.Duration, peerId string)
  • func (a *EventTracker) TrackWorkRequest(workType data_types.WorkerType, peerId, payload string)
  • func (a *EventTracker) TrackWorkRequestSerialization(workType data_types.WorkerType, dataSize int, peerId string)
  • func (a *EventTracker) TrackWorkResponseDeserialization(workType data_types.WorkerType, success bool, peerId string)
  • func (a *EventTracker) TrackWorkerFailure(workType data_types.WorkerType, errorMessage string, peerId string)

Constants

const (
	// APIVersion is the version of the analytics API
	APIVersion = "v1"

	// DefaultBaseURL is the default URL for the external API
	DefaultBaseURL = "https://test.protocol-api.masa.ai"

	// DefaultHTTPTimeout is the default timeout for HTTP requests
	DefaultHTTPTimeout = 10 * time.Second

	// MaxEventsInMemory is the maximum number of events to keep in memory
	MaxEventsInMemory = 1000
)

const (
	WorkRequest                 = "work_request"
	WorkCompletion              = "work_completion"
	WorkFailure                 = "worker_failure"
	WorkDistribution            = "work_distribution"
	WorkExecutionStart          = "work_execution_start"
	WorkExecutionTimeout        = "work_execution_timeout"
	RemoteWorkerConnection      = "remote_work_connection"
	StreamCreation              = "stream_creation"
	WorkRequestSerialization    = "work_request_serialized"
	WorkResponseDeserialization = "work_response_serialized"
	LocalWorkerFallback         = "local_work_executed"
)

Types

type Config

type Config struct {
	BaseURL     string
	HTTPTimeout time.Duration
	LogLevel    string
}

Config holds the configuration for the analytics package

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns the default configuration

type Event

type Event struct {
	Name         string                `json:"name"`
	PeerID       string                `json:"peer_id"`
	Payload      string                `json:"payload"`
	DataSource   string                `json:"data_source"`
	WorkType     data_types.WorkerType `json:"work_type"`
	RemoteWorker bool                  `json:"remote_worker"`
	Success      bool                  `json:"success"`
	RecordCount  int                   `json:"record_count"`
	Error        string                `json:"error"`
}

type EventClient

type EventClient struct {
	BaseURL    string
	HTTPClient *http.Client
	Logger     *logrus.Logger
}

func NewEventClient

func NewEventClient(baseURL string, logger *logrus.Logger, timeout time.Duration) *EventClient

func (*EventClient) SendEvent

func (c *EventClient) SendEvent(event Event) error

type EventTracker

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

func NewEventTracker

func NewEventTracker(config *Config) *EventTracker

func (*EventTracker) ClearEvents

func (a *EventTracker) ClearEvents()

func (*EventTracker) GetEvents

func (a *EventTracker) GetEvents() []Event

func (*EventTracker) TrackAndSendEvent

func (a *EventTracker) TrackAndSendEvent(event Event, client *EventClient) error

func (*EventTracker) TrackEvent

func (a *EventTracker) TrackEvent(event Event)

func (*EventTracker) TrackLocalWorkerFallback

func (a *EventTracker) TrackLocalWorkerFallback(workType data_types.WorkerType, reason string, peerId string)

TrackLocalWorkerFallback records when the system falls back to using a local worker.

Parameters: - reason: The reason for the fallback - peerId: String containing the peer ID

func (*EventTracker) TrackRemoteWorkerConnection

func (a *EventTracker) TrackRemoteWorkerConnection(workType data_types.WorkerType, peerId string)

TrackRemoteWorkerConnection records when a connection is established with a remote worker.

Parameters: - peerId: String containing the peer ID

func (*EventTracker) TrackStreamCreation

func (a *EventTracker) TrackStreamCreation(workType data_types.WorkerType, peerId string, protocol string)

TrackStreamCreation records when a new stream is created for communication with a remote worker.

Parameters: - peerId: String containing the peer ID - protocol: The protocol used for the stream

func (*EventTracker) TrackWorkCompletion

func (a *EventTracker) TrackWorkCompletion(workType data_types.WorkerType, success bool, recordCount int, peerId string)

TrackWorkCompletion records the completion of a work item.

Parameters: - success: Boolean indicating if the work was completed successfully - peerId: String containing the peer ID

func (*EventTracker) TrackWorkDistribution

func (a *EventTracker) TrackWorkDistribution(workType data_types.WorkerType, remoteWorker bool, peerId string)

TrackWorkDistribution records the distribution of work to a worker.

Parameters: - remoteWorker: Boolean indicating if the work is sent to a remote worker (true) or executed locally (false) - peerId: String containing the peer ID

func (*EventTracker) TrackWorkExecutionStart

func (a *EventTracker) TrackWorkExecutionStart(workType data_types.WorkerType, remoteWorker bool, peerId string)

TrackWorkExecutionStart records the start of work execution.

Parameters: - remoteWorker: Boolean indicating if the work is executed by a remote worker (true) or locally (false) - peerId: String containing the peer ID

func (*EventTracker) TrackWorkExecutionTimeout

func (a *EventTracker) TrackWorkExecutionTimeout(workType data_types.WorkerType, timeoutDuration time.Duration, peerId string)

TrackWorkExecutionTimeout records when work execution times out.

Parameters: - timeoutDuration: The duration of the timeout - peerId: String containing the peer ID

func (*EventTracker) TrackWorkRequest

func (a *EventTracker) TrackWorkRequest(workType data_types.WorkerType, peerId, payload string)

TrackWorkRequest records when a work request is initiated.

Parameters: - workType: String indicating the type of work being requested (e.g., "SearchTweetsRecent") - peerId: String containing the peer ID (or client IP in this case)

func (*EventTracker) TrackWorkRequestSerialization

func (a *EventTracker) TrackWorkRequestSerialization(workType data_types.WorkerType, dataSize int, peerId string)

TrackWorkRequestSerialization records when a work request is serialized for transmission.

Parameters: - dataSize: The size of the serialized data - peerId: String containing the peer ID

func (*EventTracker) TrackWorkResponseDeserialization

func (a *EventTracker) TrackWorkResponseDeserialization(workType data_types.WorkerType, success bool, peerId string)

TrackWorkResponseDeserialization records when a work response is deserialized after reception.

Parameters: - success: Boolean indicating if the deserialization was successful - peerId: String containing the peer ID

func (*EventTracker) TrackWorkerFailure

func (a *EventTracker) TrackWorkerFailure(workType data_types.WorkerType, errorMessage string, peerId string)

TrackWorkerFailure records a failure that occurred during work execution.

Parameters: - errorMessage: A string describing the error that occurred - peerId: String containing the peer ID