telemetry

package
v1.9.3-0...-199195a Latest Latest
Warning

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

 Go to latest Published: Mar 21, 2026 License: MIT Imports: 12 Imported by: 0

README

telemetry

import "github.com/tagoro9/fotingo/internal/telemetry"

Package telemetry provides privacy-safe analytics instrumentation for the CLI.

It centralizes event schema enforcement, event emission, and integration-call instrumentation so command packages can emit telemetry without handling transport and redaction details directly.

Index

Constants

const (
    // EventCommandStarted is emitted when command execution begins.
    EventCommandStarted = "fotingo.command.started"
    // EventCommandCompleted is emitted after command completion with duration/exit code.
    EventCommandCompleted = "fotingo.command.completed"
    // EventCommandError is emitted for handled command failures.
    EventCommandError = "fotingo.command.error"
    // EventCommandCrashed is emitted when execution recovers from a panic.
    EventCommandCrashed = "fotingo.command.crashed"
    // EventIntegrationCall is emitted for instrumented GitHub/Jira HTTP calls.
    EventIntegrationCall = "fotingo.integration.call"
    // EventUpdateBannerShown is emitted when the startup update banner is shown.
    EventUpdateBannerShown = "fotingo.ui.update_banner.shown"
)


const (
    // EventSchemaVersion tracks the global telemetry schema contract version.
    EventSchemaVersion = "1.0.0"
)

Variables

EventRegistry defines stable telemetry event names and their owning domains.

var EventRegistry = map[string]string{
    EventCommandStarted:    "command",
    EventCommandCompleted:  "command",
    EventCommandError:      "command",
    EventCommandCrashed:    "command",
    EventIntegrationCall:   "integration",
    EventUpdateBannerShown: "ui",
}

func ClearActiveCommand

func ClearActiveCommand()

ClearActiveCommand clears active command context for integration event correlation.

func Configure

func Configure(cfg Config) error

Configure initializes telemetry runtime. It is safe to call multiple times.

func IsDefaultBackendConfigured

func IsDefaultBackendConfigured() bool

IsDefaultBackendConfigured reports whether the process default telemetry backend is configured.

func ResetForTesting

func ResetForTesting()

ResetForTesting resets telemetry runtime state for tests.

func SetDefaultBackendConfiguredForTesting

func SetDefaultBackendConfiguredForTesting(configured bool) func()

SetDefaultBackendConfiguredForTesting forces IsDefaultBackendConfigured for tests.

func SetRecorderForTesting

func SetRecorderForTesting(r recorder, build BuildInfo, distinctID string)

SetRecorderForTesting replaces the telemetry recorder for tests.

func Shutdown

func Shutdown()

Shutdown closes telemetry delivery resources.

func StatusCodeBucket

func StatusCodeBucket(statusCode int) string

StatusCodeBucket maps an HTTP status code into a stable bucket label.

func TrackCommandCompleted

func TrackCommandCompleted(ctx CommandContext, completion CommandCompletion)

TrackCommandCompleted emits command-completed telemetry.

func TrackCommandCrashed

func TrackCommandCrashed(ctx CommandContext, crash CommandCrash)

TrackCommandCrashed emits command-crashed telemetry.

func TrackCommandError

func TrackCommandError(ctx CommandContext, commandError CommandError)

TrackCommandError emits command-error telemetry.

func TrackCommandStarted

func TrackCommandStarted(ctx CommandContext)

TrackCommandStarted emits a command-start event and stores active command context.

func TrackIntegrationCall

func TrackIntegrationCall(call IntegrationCall)

TrackIntegrationCall emits normalized external-service call telemetry.

func TrackUpdateBannerShown

func TrackUpdateBannerShown(event UpdateBannerEvent)

TrackUpdateBannerShown emits update-banner impression telemetry.

func WrapHTTPTransport

func WrapHTTPTransport(service string, base http.RoundTripper, resolver OperationResolver) http.RoundTripper

WrapHTTPTransport instruments an HTTP transport and emits integration-call telemetry.

Service packages are responsible for supplying a low-cardinality operation resolver (with allowlisted operations and "other" fallback).

type BuildInfo

BuildInfo describes the binary metadata included in telemetry events.

type BuildInfo struct {
    Version  string
    Platform string
    OS       string
    Arch     string
}

type CommandCompletion

CommandCompletion captures completion outcome data.

type CommandCompletion struct {
    Duration time.Duration
    ExitCode int
}

type CommandContext

CommandContext captures safe command metadata.

type CommandContext struct {
    CommandName          string
    CommandPath          string
    CommandSchemaVersion string
    Persona              string
    InvocationMode       string
    GlobalFlags          map[string]bool
    HasBranchOverride    bool
    OptionFlags          map[string]bool
    OptionCounts         map[string]int
    OptionEnums          map[string]string
}

type CommandCrash

CommandCrash captures panic/crash telemetry details.

type CommandCrash struct {
    Duration         time.Duration
    ExitCode         int
    PanicType        string
    CrashFingerprint string
    TopFrame         string
}

type CommandError

CommandError captures error telemetry details.

type CommandError struct {
    Duration         time.Duration
    ExitCode         int
    ErrorFamily      string
    ErrorFingerprint string
}

type Config

Config controls telemetry runtime initialization.

type Config struct {
    Enabled         bool
    DistinctID      string
    BuildInfo       BuildInfo
    ShutdownTimeout time.Duration
    // contains filtered or unexported fields
}

type IntegrationCall

IntegrationCall captures normalized integration call metrics.

type IntegrationCall struct {
    Service          string
    Operation        string
    Duration         time.Duration
    Success          bool
    RetryCount       int
    CacheHit         bool
    StatusCodeBucket string
}

type OperationResolver

OperationResolver maps an outbound HTTP request to a stable logical operation name.

type OperationResolver func(*http.Request) string

type UpdateBannerEvent

UpdateBannerEvent captures startup update-banner telemetry.

type UpdateBannerEvent struct {
    CurrentVersion string
    LatestVersion  string
    Trigger        string
    Persona        string
    InvocationMode string
}

Generated by gomarkdoc

Documentation

Overview

Package telemetry provides privacy-safe analytics instrumentation for the CLI.

It centralizes event schema enforcement, event emission, and integration-call instrumentation so command packages can emit telemetry without handling transport and redaction details directly.

Index

Constants

View Source 
const (
	// EventCommandStarted is emitted when command execution begins.
	EventCommandStarted = "fotingo.command.started"
	// EventCommandCompleted is emitted after command completion with duration/exit code.
	EventCommandCompleted = "fotingo.command.completed"
	// EventCommandError is emitted for handled command failures.
	EventCommandError = "fotingo.command.error"
	// EventCommandCrashed is emitted when execution recovers from a panic.
	EventCommandCrashed = "fotingo.command.crashed"
	// EventIntegrationCall is emitted for instrumented GitHub/Jira HTTP calls.
	EventIntegrationCall = "fotingo.integration.call"
	// EventUpdateBannerShown is emitted when the startup update banner is shown.
	EventUpdateBannerShown = "fotingo.ui.update_banner.shown"
)
View Source 
const (
	// EventSchemaVersion tracks the global telemetry schema contract version.
	EventSchemaVersion = "1.0.0"
)

Variables

View Source 
var EventRegistry = map[string]string{
	EventCommandStarted:    "command",
	EventCommandCompleted:  "command",
	EventCommandError:      "command",
	EventCommandCrashed:    "command",
	EventIntegrationCall:   "integration",
	EventUpdateBannerShown: "ui",
}

EventRegistry defines stable telemetry event names and their owning domains.

Functions

func ClearActiveCommand 

func ClearActiveCommand()

ClearActiveCommand clears active command context for integration event correlation.

func Configure 

func Configure(cfg Config) error

Configure initializes telemetry runtime. It is safe to call multiple times.

func IsDefaultBackendConfigured 

func IsDefaultBackendConfigured() bool

IsDefaultBackendConfigured reports whether the process default telemetry backend is configured.

func ResetForTesting 

func ResetForTesting()

ResetForTesting resets telemetry runtime state for tests.

func SetDefaultBackendConfiguredForTesting 

func SetDefaultBackendConfiguredForTesting(configured bool) func()

SetDefaultBackendConfiguredForTesting forces IsDefaultBackendConfigured for tests.

func SetRecorderForTesting 

func SetRecorderForTesting(r recorder, build BuildInfo, distinctID string)

SetRecorderForTesting replaces the telemetry recorder for tests.

func Shutdown 

func Shutdown()

Shutdown closes telemetry delivery resources.

func StatusCodeBucket 

func StatusCodeBucket(statusCode int) string

StatusCodeBucket maps an HTTP status code into a stable bucket label.

func TrackCommandCompleted 

func TrackCommandCompleted(ctx CommandContext, completion CommandCompletion)

TrackCommandCompleted emits command-completed telemetry.

func TrackCommandCrashed 

func TrackCommandCrashed(ctx CommandContext, crash CommandCrash)

TrackCommandCrashed emits command-crashed telemetry.

func TrackCommandError 

func TrackCommandError(ctx CommandContext, commandError CommandError)

TrackCommandError emits command-error telemetry.

func TrackCommandStarted 

func TrackCommandStarted(ctx CommandContext)

TrackCommandStarted emits a command-start event and stores active command context.

func TrackIntegrationCall 

func TrackIntegrationCall(call IntegrationCall)

TrackIntegrationCall emits normalized external-service call telemetry.

func TrackUpdateBannerShown 

func TrackUpdateBannerShown(event UpdateBannerEvent)

TrackUpdateBannerShown emits update-banner impression telemetry.

func WrapHTTPTransport 

func WrapHTTPTransport(service string, base http.RoundTripper, resolver OperationResolver) http.RoundTripper

WrapHTTPTransport instruments an HTTP transport and emits integration-call telemetry.

Service packages are responsible for supplying a low-cardinality operation resolver (with allowlisted operations and "other" fallback).

Types

type BuildInfo 

type BuildInfo struct {
	Version  string
	Platform string
	OS       string
	Arch     string
}

BuildInfo describes the binary metadata included in telemetry events.

type CommandCompletion 

type CommandCompletion struct {
	Duration time.Duration
	ExitCode int
}

CommandCompletion captures completion outcome data.

type CommandContext 

type CommandContext struct {
	CommandName          string
	CommandPath          string
	CommandSchemaVersion string
	Persona              string
	InvocationMode       string
	GlobalFlags          map[string]bool
	HasBranchOverride    bool
	OptionFlags          map[string]bool
	OptionCounts         map[string]int
	OptionEnums          map[string]string
}

CommandContext captures safe command metadata.

type CommandCrash 

type CommandCrash struct {
	Duration         time.Duration
	ExitCode         int
	PanicType        string
	CrashFingerprint string
	TopFrame         string
}

CommandCrash captures panic/crash telemetry details.

type CommandError 

type CommandError struct {
	Duration         time.Duration
	ExitCode         int
	ErrorFamily      string
	ErrorFingerprint string
}

CommandError captures error telemetry details.

type Config 

type Config struct {
	Enabled         bool
	DistinctID      string
	BuildInfo       BuildInfo
	ShutdownTimeout time.Duration
	// contains filtered or unexported fields
}

Config controls telemetry runtime initialization.

type IntegrationCall 

type IntegrationCall struct {
	Service          string
	Operation        string
	Duration         time.Duration
	Success          bool
	RetryCount       int
	CacheHit         bool
	StatusCodeBucket string
}

IntegrationCall captures normalized integration call metrics.

type OperationResolver 

type OperationResolver func(*http.Request) string

OperationResolver maps an outbound HTTP request to a stable logical operation name.

type UpdateBannerEvent 

type UpdateBannerEvent struct {
	CurrentVersion string
	LatestVersion  string
	Trigger        string
	Persona        string
	InvocationMode string
}

UpdateBannerEvent captures startup update-banner telemetry.

Source Files

View all Source files

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.