Analytics & Telemetry

Relevant source files

The following files were used as context for generating this wiki page:

• internal/analytics/tracker.go
• internal/analytics/client.go
• cmd/analytics.go
• cmd/root.go
• internal/agent/agent.go
• CONTRIBUTING.md

The tusk-drift-cli includes an analytics system to collect anonymous usage data. This data helps the development team understand how the CLI is used, identify common errors, and prioritize improvements. The system is designed to be privacy-conscious and is fully controllable by the user, with multiple ways to disable it.

The core functionality is built around a Tracker that wraps a Client for sending events. This system is integrated into the command lifecycle and is also used for detailed event tracking in features like the AI Setup Agent.

Architecture Overview

The analytics system is composed of a few key components that work together to capture and send events. A Tracker is created for each command execution, which then uses a shared Client to send data to the backend.

The following diagram illustrates the high-level data flow from a user command to the analytics backend.

Components

Component	File	Description
Tracker	internal/analytics/tracker.go	Manages analytics for a single command execution. It captures the command name, flags, start time, and the final result (success or error).
Client	internal/analytics/client.go	A wrapper around the Segment analytics client. It handles user identification (anonymous and authenticated), event queuing, and sending data to the Segment API.
analytics command	cmd/analytics.go	A Cobra command that provides subcommands (status, enable, disable) for users to manage their analytics settings.

Sources: internal/analytics/tracker.go:13-19, internal/analytics/client.go:17-22, cmd/analytics.go:11-15

Command Tracking Lifecycle

Analytics tracking is initiated at the start of any command execution and completes after the command has finished. The Tracker is responsible for measuring the duration and capturing the outcome.

This sequence diagram shows the lifecycle of tracking a single command.

Collected Command Data

For each command execution, the drift_cli:command_executed event is sent with the following properties:

Property	Type	Description
command	string	The full path of the executed command (e.g., "run", "analytics status").
flags	[]string	A list of flags used with the command (e.g., ["--debug"]).
success	bool	true if the command completed without error, false otherwise.
exit_code	int	0 for success, 1 for failure.
duration_ms	int64	The total execution time of the command in milliseconds.
error_type	string	(Optional) A categorized string representing the type of error if one occurred.

Sources: internal/analytics/tracker.go:55-64

Custom Event Tracking

Beyond tracking command execution, the Tracker can be used to send custom events. This is heavily utilized by the AI Setup Agent to provide detailed telemetry on its progress and outcomes.

AI Setup Agent Example

The Agent in internal/agent/agent.go initializes a tracker and sends events at key moments in the setup lifecycle.

Example events tracked by the agent:

• drift_cli:setup_agent:started
• drift_cli:setup_agent:phase_completed
• drift_cli:setup_agent:phase_failed
• drift_cli:setup_agent:interrupted
• drift_cli:setup_agent:aborted
• drift_cli:setup_agent:local_completed
• drift_cli:setup_agent:cloud_started
• drift_cli:setup_agent:cloud_completed

A session_id is generated for each agent run to correlate all related events.

Sources: internal/agent/agent.go:102-109, internal/agent/agent.go:115-130, internal/agent/agent.go:296-310

User Identification

The system supports both anonymous and identified users.

• Anonymous ID: A unique device ID (AnonymousID) is generated and stored in the CLI configuration file. This is used by default.
• User ID: After a user logs in, the Alias method is called to associate the anonymous ID with their authenticated UserID. Subsequent events are then linked to the user's account.

Sources: internal/analytics/tracker.go:85-91, internal/analytics/client.go:61-69, cmd/analytics.go:94-98

Configuration and Control

Users have full control over analytics through the tusk analytics command and other mechanisms.

Analytics Commands

The CLI provides the following commands to manage settings:

Command	Description
tusk analytics status	Shows the current analytics status, device ID, and linked account (if any).
tusk analytics enable	Enables usage analytics by setting AnalyticsEnabled: true in the config.
tusk analytics disable	Disables usage analytics by setting AnalyticsEnabled: false in the config.

Sources: cmd/analytics.go:17-61

Disabling Analytics

Analytics can be disabled in several ways, checked in a specific order of precedence.

The logic for determining if analytics are enabled is encapsulated in cliconfig.IsAnalyticsEnabled().

The following table summarizes all conditions that disable analytics:

Condition	Mechanism	Source
Environment Variable	TUSK_ANALYTICS_DISABLED is set to any value.	cmd/analytics.go:81
CI Environment	The CI environment variable is true.	cmd/analytics.go:83
Developer Mode	The is_tusk_developer flag is set to true in the CLI config file.	CONTRIBUTING.md:104-105, cmd/analytics.go:85
User Preference	The user has run tusk analytics disable.	cmd/analytics.go:48-61, cmd/analytics.go:87

Summary

The analytics and telemetry system in tusk-drift-cli is a straightforward but powerful tool for gathering usage statistics. It is designed with user privacy and control as primary considerations, offering transparent and easy-to-use mechanisms for opting out. Its integration with core features like the AI Setup Agent allows for rich, contextual data that helps drive product development.