telemetry

package
v1.11.0 Latest Latest
Warning

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

 Go to latest Published: Jun 26, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	EventCommandInvoked   = "Command Invoked"
	EventCommandCompleted = "Command Completed"

	EventAuthStarted   = "CLI Auth Started"
	EventAuthCompleted = "CLI Auth Completed"
	EventAuthFailed    = "CLI Auth Failed"
	EventAuthAborted   = "CLI Auth Aborted"
	EventAuthLogout    = "CLI Auth Logout"

	EventApplicationCreateStarted       = "CLI Application Create Started"
	EventApplicationCreateAcceptedTerms = "CLI Application Create Accepted Terms"
	EventApplicationCreateDeclinedTerms = "CLI Application Create Declined Terms"
	EventApplicationCreateCompleted     = "CLI Application Create Completed"
	EventApplicationCreateFailed        = "CLI Application Create Failed"
	EventApplicationCreateAborted       = "CLI Application Create Aborted"

	EventApplicationPlanChangeStarted       = "CLI Application Plan Change Started"
	EventApplicationPlanChangeAcceptedTerms = "CLI Application Plan Change Accepted Terms"
	EventApplicationPlanChangeDeclinedTerms = "CLI Application Plan Change Declined Terms"
	EventApplicationPlanChangeCompleted     = "CLI Application Plan Change Completed"
	EventApplicationPlanChangeFailed        = "CLI Application Plan Change Failed"
	EventApplicationPlanChangeAborted       = "CLI Application Plan Change Aborted"
)

Event names. New flow events follow the `CLI <Command> <Step>` convention; the command lifecycle events stay unprefixed for consistency with the historical "Command Invoked".

View Source 
const (
	AppName = "cli"
)

Variables

This section is empty.

Functions

func ErrorClass added in v1.11.0 

func ErrorClass(err error) string

ErrorClass returns the type of the first informative error of the chain, skipping the anonymous wrappers created by fmt.Errorf. It never returns an error message, which could contain user data.

func TrackEvent added in v1.11.0 

func TrackEvent(ctx context.Context, event Event)

TrackEvent sends the event through the context's telemetry client, silently doing nothing when no client is present.

func WithEventMetadata 

func WithEventMetadata(ctx context.Context, metadata *CLIAnalyticsEventMetadata) context.Context

WithEventMetadata returns a new copy of context.Context with the provided CLIAnalyticsEventMetadata

func WithTelemetryClient 

func WithTelemetryClient(ctx context.Context, client TelemetryClient) context.Context

WithTelemetryClient returns a new copy of context.Context with the provided telemetryClient

Types

type AbortReason added in v1.11.0 

type AbortReason string

AbortReason tells why the user stopped a flow. 

const (
	AbortReasonDeclinedTerms   AbortReason = "declined_terms"
	AbortReasonCancelled       AbortReason = "cancelled"
	AbortReasonBillingRequired AbortReason = "billing_required"
	AbortReasonAlreadyOnPlan   AbortReason = "already_on_plan"
	AbortReasonNoCandidates    AbortReason = "no_candidates"
)

type AnalyticsTelemetryClient 

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

func (*AnalyticsTelemetryClient) Close 

func (a *AnalyticsTelemetryClient) Close()

Close closes the client, waiting for all pending events to be sent.

func (*AnalyticsTelemetryClient) Identify 

func (a *AnalyticsTelemetryClient) Identify(ctx context.Context) error

Identify tracks the user with the provided properties

func (*AnalyticsTelemetryClient) Track 

func (a *AnalyticsTelemetryClient) Track(
	ctx context.Context,
	event string,
	properties map[string]any,
) error

Track tracks the event with the provided custom properties, merged with the base properties of the invocation

type AnalyticsTelemetryLogger 

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

func (AnalyticsTelemetryLogger) Errorf 

func (l AnalyticsTelemetryLogger) Errorf(format string, args ...interface{})

func (AnalyticsTelemetryLogger) Logf 

func (l AnalyticsTelemetryLogger) Logf(format string, args ...interface{})

type CLIAnalyticsEventMetadata 

type CLIAnalyticsEventMetadata struct {
	AnonymousID              string   // the anonymous id is the hash of the mac address of the machine
	UserID                   string   // the authenticated user's id from the OAuth token; empty when logged out
	Email                    string   // the authenticated user's email, when available
	Name                     string   // the authenticated user's name, when available
	InvocationID             string   // the invocation id is unique to each context object and represents all events coming from one command
	ConfiguredApplicationsNb int      // the number of configured applications
	AppID                    string   // the app id with which the command was called
	CommandPath              string   // the command path is the full path of the command
	CommandFlags             []string // the command flags is the full list of flags passed to the command
	CLIVersion               string   // the version of the CLI
	OS                       string   // the OS of the system
}

func GetEventMetadata 

func GetEventMetadata(ctx context.Context) *CLIAnalyticsEventMetadata

GetEventMetadata returns the CLIAnalyticsEventMetadata from the provided context

func NewEventMetadata 

func NewEventMetadata() *CLIAnalyticsEventMetadata

NewEventMetadata initializes an instance of CLIAnalyticsEventContext

func (*CLIAnalyticsEventMetadata) SetAppID 

func (e *CLIAnalyticsEventMetadata) SetAppID(appID string)

SetAppID sets the AppID on the CLIAnalyticsEventContext object

func (*CLIAnalyticsEventMetadata) SetCobraCommandContext 

func (e *CLIAnalyticsEventMetadata) SetCobraCommandContext(cmd *cobra.Command)

SetCobraCommandContext sets the telemetry values for the command being executed.

func (*CLIAnalyticsEventMetadata) SetCommandPath 

func (e *CLIAnalyticsEventMetadata) SetCommandPath(commandPath string)

SetCommandPath sets the commandPath on the CLIAnalyticsEventContext object

func (*CLIAnalyticsEventMetadata) SetConfiguredApplicationsNb 

func (e *CLIAnalyticsEventMetadata) SetConfiguredApplicationsNb(nb int)

SetConfiguredApplicationsNb sets the configuredApplicationsNb on the CLIAnalyticsEventContext object

func (*CLIAnalyticsEventMetadata) SetUser added in v1.11.0 

func (e *CLIAnalyticsEventMetadata) SetUser(userID, email, name string)

SetUser sets the authenticated user identity on the CLIAnalyticsEventContext object

type Direction added in v1.11.0 

type Direction string

Direction is the direction of a plan change. 

const (
	DirectionUpgrade   Direction = "upgrade"
	DirectionDowngrade Direction = "downgrade"
)

type Event added in v1.11.0 

type Event struct {
	Name       string
	Properties map[string]any
}

Event is a fully assembled telemetry event, ready to be tracked.

func ApplicationCreateAborted added in v1.11.0 

func ApplicationCreateAborted(tracker *FlowTracker, reason AbortReason) Event

ApplicationCreateAborted is emitted when the user stopped the creation flow, with the step they stopped at and the reason why.

func ApplicationCreateAcceptedTerms added in v1.11.0 

func ApplicationCreateAcceptedTerms(plan string) Event

ApplicationCreateAcceptedTerms is emitted when the user accepted the terms of the selected plan.

func ApplicationCreateCompleted added in v1.11.0 

func ApplicationCreateCompleted(region, plan string, tracker *FlowTracker) Event

ApplicationCreateCompleted is emitted when the application was created, with the region and plan the user chose.

func ApplicationCreateDeclinedTerms added in v1.11.0 

func ApplicationCreateDeclinedTerms(plan string) Event

ApplicationCreateDeclinedTerms is emitted when the user declined the terms of the selected plan.

func ApplicationCreateFailed added in v1.11.0 

func ApplicationCreateFailed(tracker *FlowTracker, err error) Event

ApplicationCreateFailed is emitted when the creation flow failed, with the step it failed at.

func ApplicationCreateStarted added in v1.11.0 

func ApplicationCreateStarted() Event

ApplicationCreateStarted is emitted when the application creation flow begins (dry runs are not tracked).

func ApplicationPlanChangeAborted added in v1.11.0 

func ApplicationPlanChangeAborted(
	direction Direction,
	tracker *FlowTracker,
	reason AbortReason,
) Event

ApplicationPlanChangeAborted is emitted when the user stopped the plan change flow, with the step they stopped at and the reason why.

func ApplicationPlanChangeAcceptedTerms added in v1.11.0 

func ApplicationPlanChangeAcceptedTerms(direction Direction, plan string) Event

ApplicationPlanChangeAcceptedTerms is emitted when the user accepted the terms of the target plan.

func ApplicationPlanChangeCompleted added in v1.11.0 

func ApplicationPlanChangeCompleted(
	direction Direction,
	fromPlan, toPlan string,
	tracker *FlowTracker,
) Event

ApplicationPlanChangeCompleted is emitted when the plan was changed.

func ApplicationPlanChangeDeclinedTerms added in v1.11.0 

func ApplicationPlanChangeDeclinedTerms(direction Direction, plan string) Event

ApplicationPlanChangeDeclinedTerms is emitted when the user declined the terms of the target plan.

func ApplicationPlanChangeFailed added in v1.11.0 

func ApplicationPlanChangeFailed(direction Direction, tracker *FlowTracker, err error) Event

ApplicationPlanChangeFailed is emitted when the plan change flow failed, with the step it failed at.

func ApplicationPlanChangeStarted added in v1.11.0 

func ApplicationPlanChangeStarted(direction Direction) Event

ApplicationPlanChangeStarted is emitted when the plan change flow begins (dry runs are not tracked).

func AuthAborted added in v1.11.0 

func AuthAborted(flow Flow, tracker *FlowTracker) Event

AuthAborted is emitted when the user cancelled the auth flow, with the step they stopped at.

func AuthCompleted added in v1.11.0 

func AuthCompleted(flow Flow, tracker *FlowTracker) Event

AuthCompleted is emitted when the profile is fully configured at the end of the auth flow.

func AuthFailed added in v1.11.0 

func AuthFailed(flow Flow, tracker *FlowTracker, err error) Event

AuthFailed is emitted when the auth flow failed, with the step it failed at.

func AuthLogout added in v1.11.0 

func AuthLogout() Event

AuthLogout is emitted when the user signs out. It must be tracked before the local state is cleared, while the user identifier is still attached to the telemetry metadata; no Identify follows, since Segment's identity graph has no concept of un-identifying.

func AuthStarted added in v1.11.0 

func AuthStarted(flow Flow, noBrowser bool) Event

AuthStarted is emitted when the browser-based OAuth flow begins.

type Flow added in v1.11.0 

type Flow string

Flow is the kind of auth flow the user is going through. 

const (
	FlowLogin  Flow = "login"
	FlowSignup Flow = "signup"
	FlowLogout Flow = "logout"
)

type FlowTracker added in v1.11.0 

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

FlowTracker carries the state of one interactive flow: the step the user is currently in and the flow start time, to compute durations. All its methods are safe on a nil tracker, so helpers shared by several flows can take an optional tracker.

func NewFlowTracker added in v1.11.0 

func NewFlowTracker() *FlowTracker

func (*FlowTracker) DurationMS added in v1.11.0 

func (f *FlowTracker) DurationMS() int64

DurationMS returns the time elapsed since the flow started, in milliseconds.

func (*FlowTracker) SetStep added in v1.11.0 

func (f *FlowTracker) SetStep(step Step)

SetStep records the step the flow is entering.

func (*FlowTracker) Step added in v1.11.0 

func (f *FlowTracker) Step() Step

Step returns the step the flow is currently in.

type NoOpTelemetryClient 

type NoOpTelemetryClient struct{}

func (*NoOpTelemetryClient) Close 

func (a *NoOpTelemetryClient) Close()

func (*NoOpTelemetryClient) Identify 

func (a *NoOpTelemetryClient) Identify(ctx context.Context) error

func (*NoOpTelemetryClient) Track 

func (a *NoOpTelemetryClient) Track(
	ctx context.Context,
	event string,
	properties map[string]any,
) error

type Step added in v1.11.0 

type Step string

Step locates where the user is inside an interactive flow, so aborts and failures can tell where the user stopped. 

const (
	// Auth flow steps.
	StepBrowserWait      Step = "browser_wait"
	StepCodeExchange     Step = "code_exchange"
	StepAppsFetch        Step = "apps_fetch"
	StepAppSelect        Step = "app_select"
	StepAppCreate        Step = "app_create"
	StepProfileConfigure Step = "profile_configure"

	// Application create and plan change flow steps.
	StepAuth      Step = "auth"
	StepName      Step = "name"
	StepPlan      Step = "plan"
	StepTerms     Step = "terms"
	StepRegion    Step = "region"
	StepAPICall   Step = "api_call"
	StepAPIKey    Step = "api_key"
	StepApplyPlan Step = "apply_plan"
)

type TelemetryClient 

type TelemetryClient interface {
	Identify(ctx context.Context) error
	Track(ctx context.Context, event string, properties map[string]any) error
	Close()
}

func GetTelemetryClient 

func GetTelemetryClient(ctx context.Context) TelemetryClient

GetTelemetryClient returns the CLIAnalyticsEventMetadata from the provided context

func NewAnalyticsTelemetryClient 

func NewAnalyticsTelemetryClient(debug bool) (TelemetryClient, error)

Source Files

View all Source files

Directories

Path Synopsis
Package telemetrytest provides test doubles for the telemetry package.
 Package telemetrytest provides test doubles for the telemetry package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.