Add analytics tracking (#87)

Author: nathanjcochran

CLAUDE.md

@@ -192,6 +192,72 @@ After making changes to commands, tools, configuration, or flags, always check a
 
 Keep these files in sync with the actual implementation. When adding a new flag, config option, or command, update all relevant documentation files.
 
+### Analytics Tracking
+
+Tiger CLI tracks usage analytics to help improve the product. Analytics are automatically tracked using middleware - you typically don't need to add tracking code manually when adding new commands or MCP tools.
+
+#### Automatic Tracking via Middleware
+
+**CLI Commands** - All commands are automatically wrapped with analytics middleware in `internal/tiger/cmd/root.go:134`
+
+This middleware:
+- Automatically tracks all CLI commands with event name like `"Run tiger service create"`
+- Captures elapsed time for each command
+- Tracks all user-provided flags (excluding sensitive ones like passwords and keys)
+- Records success/failure status and error messages
+- Uses `analytics.TryInit()` to gracefully handle cases where credentials aren't available
+
+**MCP Tools** - All MCP tool calls are automatically tracked via middleware in `internal/tiger/mcp/server.go:102`
+
+This middleware:
+- Automatically tracks all MCP tool calls with event name like `"Call service_create tool"`
+- Extracts and tracks tool arguments (excluding sensitive fields like passwords, queries, parameters)
+- Records success/failure status and error messages
+- Also tracks resource reads and prompt requests
+
+#### Event Naming Conventions
+
+The middleware follows these automatic naming conventions:
+
+**CLI Commands:** `"Run tiger <command> <subcommand>"`
+- Example: `"Run tiger service create"`, `"Run tiger db connection-string"`
+
+**MCP Tools:** `"Call <tool_name> tool"`
+- Example: `"Call service_create tool"`, `"Call db_execute_query tool"`
+
+**MCP Resources:** `"Read proxied resource"`
+- Includes the `resource_uri` property
+
+**MCP Prompts:** `"Get <prompt_name> prompt"`
+- Example: `"Get setup_hypertable prompt"`, `"Get migrate_to_hypertables prompt"`
+
+#### Excluding Sensitive Data
+
+The middleware automatically excludes sensitive fields using a centralized ignore list in `internal/tiger/analytics/analytics.go`.
+
+**Current ignore list:**
+- `password` - User passwords
+- `new_password` - New passwords for updates
+- `public_key` - API public keys
+- `secret_key` - API secret keys
+- `project_id` - Project identifiers
+- `query` - SQL queries (may contain sensitive data)
+- `parameters` - SQL parameters (may contain sensitive data)
+
+**IMPORTANT:** When adding new commands or MCP tools, review whether they introduce new sensitive flags, input parameters, or positional arguments:
+
+1. **For sensitive flags or MCP tool parameters:** Add the field name to the `ignore` list in `internal/tiger/analytics/analytics.go`
+   - Note: Flag names with dashes (like `public-key`) should be added with underscores (`public_key`) to the ignore list
+
+2. **For positional arguments:** Currently, all positional arguments are tracked automatically. If a command is added that accepts sensitive data as a positional argument (not as a flag), you must either:
+   - Refactor to use a flag instead
+   - Add filtering logic in `wrapCommandsWithAnalytics()` in `internal/tiger/cmd/root.go` to sanitize or omit the args from tracking
+
+**Common sensitive fields to watch for:**
+- Credentials: API keys, tokens, passwords, secret keys
+- User data: SQL queries, connection strings, personal information
+- Security-related: Private keys, certificates, encryption keys
+
 ## Architecture Overview
 
 Tiger CLI is a Go-based command-line interface for managing Tiger, the modern database cloud. The architecture follows standard Go CLI patterns using Cobra and Viper.

internal/tiger/analytics/analytics.go

@@ -0,0 +1,269 @@
+package analytics
+
+import (
+	"context"
+	"os"
+	"runtime"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/spf13/pflag"
+	"github.com/timescale/tiger-cli/internal/tiger/api"
+	"github.com/timescale/tiger-cli/internal/tiger/config"
+	"github.com/timescale/tiger-cli/internal/tiger/logging"
+	"go.uber.org/zap"
+)
+
+// A list of properties that should never be recorded in analytics events.
+// Used to filter flags and MCP tool call parameters from automatic tracking.
+// Note that dashes in flag names are converted to underscores before being
+// checked against this list.
+var ignore = []string{
+	"public_key",
+	"secret_key",
+	"project_id",
+	"password",
+	"new_password",
+	"query",
+	"parameters",
+}
+
+type Analytics struct {
+	config    *config.Config
+	projectID string
+	client    *api.ClientWithResponses
+}
+
+// New initializes a new [Analytics] instance.
+func New(cfg *config.Config, client *api.ClientWithResponses, projectID string) *Analytics {
+	return &Analytics{
+		config:    cfg,
+		projectID: projectID,
+		client:    client,
+	}
+}
+
+// TryInit tries to load credentials to initialize an [Analytics]
+// instance.  It returns an instance with a nil client if credentials do not
+// exist or it otherwise fails to create a new client. This function is
+// intended to be used when the caller does not otherwise need an API client to
+// function, but would use one if available to track analytics events.
+// Otherwise, call NewAnalytics directly.
+func TryInit(cfg *config.Config) *Analytics {
+	apiKey, projectID, err := config.GetCredentials()
+	if err != nil {
+		return New(cfg, nil, "")
+	}
+
+	client, err := api.NewTigerClient(cfg, apiKey)
+	if err != nil {
+		return New(cfg, nil, projectID)
+	}
+
+	return New(cfg, client, projectID)
+}
+
+// Option is a function that modifies analytics event properties. Options are
+// passed to Track and Identify methods to customize the data sent with events.
+type Option func(properties map[string]any)
+
+// Property creates an Option that adds a single key-value pair to the event
+// properties. This is useful for adding custom analytics data that isn't
+// covered by other Option functions.
+func Property(key string, value any) Option {
+	return func(properties map[string]any) {
+		properties[key] = value
+	}
+}
+
+// Map creates an Option that adds all key-value pairs from a map to the event
+// properties. Keys specified in the ignore list are skipped.
+//
+// This is useful for including arbitrary map data (like MCP tool arguments) in
+// analytics events without manually specifying each field.
+func Map(m map[string]any) Option {
+	return func(properties map[string]any) {
+		for key, value := range m {
+			if slices.Contains(ignore, key) {
+				continue
+			}
+			properties[key] = value
+		}
+	}
+}
+
+// flagNameReplacer converts flag names from kebab-case to snake_case for
+// consistent property naming in analytics events.
+var flagNameReplacer = strings.NewReplacer("-", "_")
+
+// FlagSet creates an Option that adds all flags that were explicitly set by
+// the user (via Visit). Flag names are converted from kebab-case to snake_case
+// (e.g., "no-wait" becomes "no_wait"). Flags in the ignore list are skipped.
+//
+// This is useful for tracking which flags users actually use when running commands.
+func FlagSet(flagSet *pflag.FlagSet) Option {
+	return func(properties map[string]any) {
+		flagSet.Visit(func(flag *pflag.Flag) {
+			key := flagNameReplacer.Replace(flag.Name)
+			if slices.Contains(ignore, key) {
+				return
+			}
+			properties[key] = flag.Value.String()
+		})
+	}
+}
+
+// Error creates an Option that adds success and error information to event
+// properties. If err is nil, sets success: true. If err is not nil, sets
+// success: false and includes the error message.
+//
+// This is commonly used at the end of command execution to track whether
+// operations succeeded or failed, and what errors occurred.
+func Error(err error) Option {
+	return func(properties map[string]any) {
+		if err != nil {
+			properties["success"] = false
+			properties["error"] = err.Error()
+		} else {
+			properties["success"] = true
+		}
+	}
+}
+
+// Identify associates the provided properties with the user for the sake of
+// analytics. It automatically includes common properties like ProjectID. The
+// identification is only sent if the client is initialized and analytics are
+// enabled in the config, otherwise it is skipped.
+func (a *Analytics) Identify(event string, options ...Option) {
+	// Create properties map with default/common properties
+	properties := map[string]any{}
+	if a.projectID != "" {
+		properties["project_id"] = a.projectID
+	}
+
+	// Merge in user-provided properties (they can override common properties if needed)
+	for _, option := range options {
+		option(properties)
+	}
+
+	logger := logging.GetLogger().With(
+		zap.Any("properties", properties),
+	)
+
+	// Check if analytics is disabled
+	if !a.enabled() {
+		logger.Debug("Analytics identify skipped (analytics disabled)")
+		return
+	}
+
+	// Check for cases where the client was not initialized
+	// (e.g. because API credentials are not available)
+	if a.client == nil {
+		logger.Debug("Analytics identify skipped (client not initialized)")
+		return
+	}
+
+	// Set a 5 second timeout for tracking analytics events. We intentionally
+	// use context.Background() here so we can track events even if a command
+	// times out or is canceled.
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	// Send the event
+	resp, err := a.client.PostAnalyticsIdentifyWithResponse(ctx, api.PostAnalyticsIdentifyJSONRequestBody{
+		Properties: &properties,
+	})
+	if err != nil {
+		// Log error but don't fail the operation - analytics should never block user actions
+		logger.Debug("Failed to send analytics identify", zap.Error(err))
+		return
+	}
+
+	if resp.JSON200 == nil || resp.JSON200.Status == nil {
+		logger.Debug("Failed to retrieve response from analytics endpoint")
+		return
+	}
+
+	logger.Debug("Analytics identify sent", zap.String("status", *resp.JSON200.Status))
+}
+
+// Track sends an analytics event with the provided event name and properties.
+// It automatically includes common properties like ProjectID, OS, and
+// architecture. Events are only sent if the client is initialized and
+// analytics are enabled in the config, otherwise they are skipped.
+func (a *Analytics) Track(event string, options ...Option) {
+	// Create properties map with default/common properties
+	properties := map[string]any{
+		"source":  "cli",
+		"version": config.Version,
+		"os":      runtime.GOOS,
+		"arch":    runtime.GOARCH,
+	}
+	if a.projectID != "" {
+		properties["project_id"] = a.projectID
+	}
+
+	// Merge in user-provided properties (they can override common properties if needed)
+	for _, option := range options {
+		option(properties)
+	}
+
+	logger := logging.GetLogger().With(
+		zap.String("event", event),
+		zap.Any("properties", properties),
+	)
+
+	// Check if analytics is disabled
+	if !a.enabled() {
+		logger.Debug("Analytics event skipped (analytics disabled)")
+		return
+	}
+
+	// Check for cases where the client was not initialized
+	// (e.g. because API credentials are not available)
+	if a.client == nil {
+		logger.Debug("Analytics event skipped (client not initialized)")
+		return
+	}
+
+	// Set a 5 second timeout for tracking analytics events. We intentionally
+	// use context.Background() here so we can track events even if a command
+	// times out or is canceled.
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	// Send the event
+	resp, err := a.client.PostAnalyticsTrackWithResponse(ctx, api.PostAnalyticsTrackJSONRequestBody{
+		Event:      event,
+		Properties: &properties,
+	})
+	if err != nil {
+		// Log error but don't fail the operation - analytics should never block user actions
+		logger.Debug("Failed to send analytics event", zap.Error(err))
+		return
+	}
+
+	if resp.JSON200 == nil || resp.JSON200.Status == nil {
+		logger.Debug("Failed to retrieve response from analytics endpoint")
+		return
+	}
+
+	logger.Debug("Analytics event sent", zap.String("status", *resp.JSON200.Status))
+}
+
+func (a *Analytics) enabled() bool {
+	if envVarIsTrue("DO_NOT_TRACK") ||
+		envVarIsTrue("NO_TELEMETRY") ||
+		envVarIsTrue("DISABLE_TELEMETRY") {
+		return false
+	}
+
+	return a.config.Analytics
+}
+
+func envVarIsTrue(envVar string) bool {
+	b, _ := strconv.ParseBool(os.Getenv(envVar))
+	return b
+}