bug

Documentation

Overview

Package bug provides utilities for reporting internal bugs, and being notified when they occur.

Philosophically, because gopls runs as a sidecar process that the user does not directly control, sometimes it keeps going on broken invariants rather than panicking. In those cases, bug reports provide a mechanism to alert developers and capture relevant metadata.

Index

• Variables
• func Errorf(format string, args ...interface{}) error
• func Handle(h func(Bug))
• func Report(description string)
• func Reportf(format string, args ...interface{})
• type Bug
  • func List() []Bug

Variables

var BugReportCount = counter.NewStack("gopls/bug", 16)

BugReportCount is a telemetry counter that tracks # of bug reports.

var PanicOnBugs = false

PanicOnBugs controls whether to panic when bugs are reported.

It may be set to true during testing.

TODO(adonovan): should we make the default true, and suppress it only in the product (gopls/main.go)?

Functions

func Errorf

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

Errorf calls fmt.Errorf for the given arguments, and reports the resulting error message as a bug.

func Handle

func Handle(h func(Bug))

Handle adds a handler function that will be called with the next bug to occur on the server. The handler only ever receives one bug. It is called synchronously, and should return in a timely manner.

func Report

func Report(description string)

Report records a new bug encountered on the server. It uses reflection to report the position of the immediate caller.

func Reportf

func Reportf(format string, args ...interface{})

Reportf reports a formatted bug message.

Types

type Bug

type Bug struct {
	File        string    // file containing the call to bug.Report
	Line        int       // line containing the call to bug.Report
	Description string    // description of the bug
	Key         string    // key identifying the bug (file:line if available)
	Stack       string    // call stack
	AtTime      time.Time // time the bug was reported
}

A Bug represents an unexpected event or broken invariant. They are used for capturing metadata that helps us understand the event.

Bugs are JSON-serializable.

func List

func List() []Bug

List returns a slice of bug exemplars -- the first bugs to occur at each callsite.