telemetry

Documentation

Overview

Package telemetry provides types and helpers for CLI telemetry.

Index

• Variables
• func Endpoint() url.URL
• func GenerateOrReadSignature(cpsigfile, anasigfile string) (string, bool)
• func GenerateSignature() string
• func ReadSignature(p string) string
• func SendMessage(msg *Message, p SendMessageParams) <-chan error
• type AuthType
  • func DetectAuthTypeFromEnv(credpath string) AuthType
• type Message
• type MessageOpt
  • func AuthUser(authUser cloud.UUID) MessageOpt
  • func BoolFlag(name string, flag bool, ifCmds ...string) MessageOpt
  • func Command(cmd string) MessageOpt
  • func DetectFromEnv(credfile, cpsigfile, anasigfile string, plat ci.PlatformType, ...) MessageOpt
  • func OrgName(orgName string) MessageOpt
  • func OrgUUID(orgUUID cloud.UUID) MessageOpt
  • func StringFlag(name string, flag string, ifCmds ...string) MessageOpt
• type Record
  • func NewRecord() *Record
  • func (r *Record) Send(params SendMessageParams)
  • func (r *Record) Set(opts ...MessageOpt)
  • func (r *Record) WaitForSend() error
• type SendMessageParams

Variables

var DefaultRecord = NewRecord()

DefaultRecord is the global default record.

Functions

func Endpoint

func Endpoint() url.URL

Endpoint returns the real telemetry endpoint.

func GenerateOrReadSignature

func GenerateOrReadSignature(cpsigfile, anasigfile string) (string, bool)

GenerateOrReadSignature attempts to read the analytics signature. If not present, it will create a new one.

func GenerateSignature

func GenerateSignature() string

GenerateSignature generates a new random signature.

func ReadSignature

func ReadSignature(p string) string

ReadSignature parses a signature file. It works for checkpoint and analytics signatures as both use the same format.

func SendMessage

func SendMessage(msg *Message, p SendMessageParams) <-chan error

SendMessage sends an analytics message to the backend endpoint asynchronously. It returns a channel that will receive the result of the operation when it's done.

Types

type AuthType

type AuthType int

AuthType is the authentication method that was used.

const (
	// AuthNone represents no authentication.
	AuthNone AuthType = iota
	// AuthIDPGoogle represents Google IDP authentication.
	AuthIDPGoogle
	// AuthIDPGithub represents GitHub IDP authentication.
	AuthIDPGithub
	// AuthOIDCGithub represents GitHub OIDC authentication.
	AuthOIDCGithub
	// AuthOIDCGitlab represents GitLab OIDC authentication.
	AuthOIDCGitlab
	// AuthAPIKey represents API key authentication.
	AuthAPIKey
)

func DetectAuthTypeFromEnv

func DetectAuthTypeFromEnv(credpath string) AuthType

DetectAuthTypeFromEnv detects AuthType based on environment variables and credentials.

type Message

type Message struct {
	Platform ci.PlatformType `json:"platform,omitempty"`
	// PlatformUser is a platform-specific identifier.
	PlatformUser string `json:"platform_user,omitempty"`

	Auth AuthType `json:"auth,omitempty"`
	// AuthUser is the TMC user UUID.
	AuthUser string `json:"auth_user,omitempty"`

	Signature string `json:"signature,omitempty"`
	OrgName   string `json:"org_name,omitempty"`
	OrgUUID   string `json:"org_uuid,omitempty"`

	Arch string `json:"arch,omitempty"`
	OS   string `json:"os,omitempty"`

	// Command stores the invoked command.
	Command string `json:"command,omitempty"`

	// Details stores features or flags used by the command.
	Details []string `json:"details,omitempty"`
}

Message is the analytics data that will be collected.

type MessageOpt

type MessageOpt func(msg *Message)

MessageOpt is the option type for Set.

func AuthUser

func AuthUser(authUser cloud.UUID) MessageOpt

AuthUser sets the auth user.

func BoolFlag

func BoolFlag(name string, flag bool, ifCmds ...string) MessageOpt

BoolFlag sets the given detail name if flag is true. If ifCmds is not empty, the current command of the record must also match any of the given values.

func Command

func Command(cmd string) MessageOpt

Command sets the command name.

func DetectFromEnv

func DetectFromEnv(credfile, cpsigfile, anasigfile string, plat ci.PlatformType, repo *git.Repository) MessageOpt

DetectFromEnv detects platform, platform_user, auth type, signature, architecture and OS from the environment.

func OrgName

func OrgName(orgName string) MessageOpt

OrgName sets the organization name.

func OrgUUID

func OrgUUID(orgUUID cloud.UUID) MessageOpt

OrgUUID sets the organization uuid.

func StringFlag

func StringFlag(name string, flag string, ifCmds ...string) MessageOpt

StringFlag calls BoolFlag with flag = (stringFlag != "").

type Record

type Record struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Record is used to aggregate telemetry data over the runtime of the application.

func NewRecord

func NewRecord() *Record

NewRecord creates an empty record.

func (*Record) Send

func (r *Record) Send(params SendMessageParams)

Send sends a message for the current record state asynchronously. A record can only be sent once, subsequent calls will be ignored. The function is non-blocking, the result can be checked with WaitForSend().

func (*Record) Set

func (r *Record) Set(opts ...MessageOpt)

Set updates the telemetry data in the record. It is safe to be called concurrently.

func (*Record) WaitForSend

func (r *Record) WaitForSend() error

WaitForSend waits until Send is done, either successfully, or with error/timeout.

type SendMessageParams

type SendMessageParams struct {
	Endpoint *url.URL
	Client   *http.Client
	Version  string
	Timeout  time.Duration
}

SendMessageParams contains parameters for SendMessage.