metrics

Documentation

Index

• Constants
• Variables
• func GetCommand(args []string) string
• func HasQuietFlag(args []string) bool
• type AnalyticsRequest
• type Client
  • func NewClient(reporter Reporter) Client
  • func NewDefaultClient() Client
• type CmdResult
• type CommandUsage
  • func NewCommandUsage(cmd CmdResult) *CommandUsage
• type DockerCLIEvent
  • func NewDockerCLIEvent(cmd CmdResult) *DockerCLIEvent
• type FailureCategory
  • func FailureCategoryFromExitCode(exitCode int) FailureCategory
• type HTTPReporter
  • func NewHTTPReporter(client *http.Client) HTTPReporter
  • func (l HTTPReporter) Event(cmd DockerCLIEvent)
  • func (l HTTPReporter) Heartbeat(cmd CommandUsage)
• type MuxReporter
  • func NewMuxReporter(reporters ...Reporter) MuxReporter
  • func (m MuxReporter) Event(cmd DockerCLIEvent)
  • func (m MuxReporter) Heartbeat(cmd CommandUsage)
• type Reporter
• type WriterReporter
  • func NewWriterReporter(w io.Writer) WriterReporter
  • func (w WriterReporter) Event(cmd DockerCLIEvent)
  • func (w WriterReporter) Heartbeat(cmd CommandUsage)

Constants

const (
	// APISource is sent for API metrics
	APISource = "api"
	// SuccessStatus command success
	SuccessStatus = "success"
	// FailureStatus command failure
	FailureStatus = "failure"
	// ComposeParseFailureStatus failure while parsing compose file
	ComposeParseFailureStatus = "failure-compose-parse"
	// FileNotFoundFailureStatus failure getting compose file
	FileNotFoundFailureStatus = "failure-file-not-found"
	// CommandSyntaxFailureStatus failure reading command
	CommandSyntaxFailureStatus = "failure-cmd-syntax"
	// BuildFailureStatus failure building imge
	BuildFailureStatus = "failure-build"
	// PullFailureStatus failure pulling imge
	PullFailureStatus = "failure-pull"
	// CanceledStatus command canceled
	CanceledStatus = "canceled"
)

const EnvVarDebugMetricsPath = "DOCKER_METRICS_DEBUG_LOG"

EnvVarDebugMetricsPath is an optional environment variable used to debug metrics by triggering all events to also be written as JSON lines to the specified file path.

const Timeout = 50 * time.Millisecond

Timeout is the maximum amount of time we'll wait for metrics sending to be acknowledged before giving up.

Variables

var (
	// FileNotFoundFailure failure for compose file not found
	FileNotFoundFailure = FailureCategory{MetricsStatus: FileNotFoundFailureStatus, ExitCode: 14}
	// ComposeParseFailure failure for composefile parse error
	ComposeParseFailure = FailureCategory{MetricsStatus: ComposeParseFailureStatus, ExitCode: 15}
	// CommandSyntaxFailure failure for command line syntax
	CommandSyntaxFailure = FailureCategory{MetricsStatus: CommandSyntaxFailureStatus, ExitCode: 16}
	// BuildFailure failure while building images.
	BuildFailure = FailureCategory{MetricsStatus: BuildFailureStatus, ExitCode: 17}
	// PullFailure failure while pulling image
	PullFailure = FailureCategory{MetricsStatus: PullFailureStatus, ExitCode: 18}
)

var CLISource = "cli"

CLISource is sent for cli metrics

Functions

func GetCommand

func GetCommand(args []string) string

GetCommand get the invoked command

func HasQuietFlag

func HasQuietFlag(args []string) bool

HasQuietFlag returns true if one of the arguments is `--quiet` or `-q`

Types

type AnalyticsRequest

type AnalyticsRequest struct {
	Event string      `json:"event"`
	Body  interface{} `json:"body"`
}

type Client

type Client interface {
	// WithCliVersionFunc sets the docker cli version func
	// that returns the docker cli version (com.docker.cli)
	WithCliVersionFunc(f func() string)
	// SendUsage sends the command to Docker Desktop.
	//
	// Note that metric collection is best-effort, so any errors are ignored.
	SendUsage(CommandUsage)
	// Track creates an event for a command execution and reports it.
	Track(CmdResult)
}

Client sends metrics to Docker Desktop

func NewClient

func NewClient(reporter Reporter) Client

NewClient returns a new metrics client that will send metrics using the provided Reporter instance.

func NewDefaultClient

func NewDefaultClient() Client

NewDefaultClient returns a new metrics client that will send metrics using the default Reporter configuration, which reports via HTTP, and, optionally, to a local file for debugging. (No format guarantees are made!)

type CmdResult

type CmdResult struct {
	// ContextType is `moby` for Docker or the name of a cloud provider.
	ContextType string
	// Args minus the process name (argv[0] aka `docker`).
	Args []string
	// Status based on exit code as a descriptive value.
	//
	// Deprecated: used for usage, events rely exclusively on exit code.
	Status string
	// ExitCode is 0 on success; otherwise, failure.
	ExitCode int
	// Start time of the process (UTC).
	Start time.Time
	// Duration of process execution.
	Duration time.Duration
}

CmdResult provides details about process execution.

type CommandUsage

type CommandUsage struct {
	Command string `json:"command"`
	Context string `json:"context"`
	Source  string `json:"source"`
	Status  string `json:"status"`
}

CommandUsage reports a CLI invocation for aggregation.

func NewCommandUsage

func NewCommandUsage(cmd CmdResult) *CommandUsage

type DockerCLIEvent

type DockerCLIEvent struct {
	Command      string    `json:"command,omitempty"`
	Subcommand   string    `json:"subcommand,omitempty"`
	Usage        bool      `json:"usage,omitempty"`
	ExitCode     int32     `json:"exit_code"`
	StartTime    time.Time `json:"start_time"`
	DurationSecs float64   `json:"duration_secs,omitempty"`
}

DockerCLIEvent represents an invocation of `docker` from the the CLI.

func NewDockerCLIEvent

func NewDockerCLIEvent(cmd CmdResult) *DockerCLIEvent

NewDockerCLIEvent inspects the command line string and returns a stripped down version suitable for reporting.

The parser will only use known values for command/subcommand from a hardcoded built-in set for safety. It also does not attempt to perfectly accurately reflect how arg parsing works in a real program, instead favoring a fairly simple approach that's still reasonably robust.

If the command does not map to a known Docker (or first-party plugin) command, `nil` will be returned. Similarly, if no subcommand for the built-in/plugin can be determined, it will be empty.

type FailureCategory

type FailureCategory struct {
	MetricsStatus string
	ExitCode      int
}

FailureCategory struct regrouping metrics failure status and specific exit code

func FailureCategoryFromExitCode

func FailureCategoryFromExitCode(exitCode int) FailureCategory

FailureCategoryFromExitCode retrieve FailureCategory based on command exit code

type HTTPReporter

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

HTTPReporter reports metric events to an HTTP endpoint.

func NewHTTPReporter

func NewHTTPReporter(client *http.Client) HTTPReporter

NewHTTPReporter creates a new reporter that will report metric events using the provided HTTP client.

func (HTTPReporter) Event

func (l HTTPReporter) Event(cmd DockerCLIEvent)

Event reports an analytics action.

func (HTTPReporter) Heartbeat

func (l HTTPReporter) Heartbeat(cmd CommandUsage)

Heartbeat reports a metric for aggregation.

type MuxReporter

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

MuxReporter wraps multiple reporter instances and reports metrics to each instance on invocation.

func NewMuxReporter

func NewMuxReporter(reporters ...Reporter) MuxReporter

NewMuxReporter creates a reporter that will report metrics to each of the provided reporter instances.

func (MuxReporter) Event

func (m MuxReporter) Event(cmd DockerCLIEvent)

Event reports an analytics action.

func (MuxReporter) Heartbeat

func (m MuxReporter) Heartbeat(cmd CommandUsage)

Heartbeat reports a metric for aggregation.

type Reporter

type Reporter interface {
	// Heartbeat reports a metric for aggregation.
	Heartbeat(cmd CommandUsage)

	// Event reports an analytics action.
	Event(cmd DockerCLIEvent)
}

Reporter reports metric events generated by the client.

type WriterReporter

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

WriterReporter reports metrics as JSON lines to the provided writer.

func NewWriterReporter

func NewWriterReporter(w io.Writer) WriterReporter

NewWriterReporter creates a new reporter that will write metrics to the provided writer as JSON lines.

func (WriterReporter) Event

func (w WriterReporter) Event(cmd DockerCLIEvent)

Event reports an analytics action.

func (WriterReporter) Heartbeat

func (w WriterReporter) Heartbeat(cmd CommandUsage)

Heartbeat reports a metric for aggregation.