ntnn

README

These functions are helpers intended for debugging and testing.

They should not to be used in production code.

Documentation

Index

• Variables
• func Callers() []runtime.Frame
• func DumpProfile(profile, pathPrefix string)
• func DumpStackToFile(path, preStack, additionalInfo string)
• func DumpToFile(addr, out string)
• func Error(err error) bool
• func ErrorFn(fn func() error) bool
• func ErrorFnV[T any](t T, fn func(T) error) bool
• func Errorf(err error, format string, args ...any) bool
• func Get(ctx context.Context, url string) (*http.Response, error)
• func Head(ctx context.Context, url string) (*http.Response, error)
• func IgnoreError(err error)
• func Log(msg string)
• func LogCallers()
• func LogChanged(msg string)
• func Logf(format string, args ...any)
• func LogfChanged(format string, args ...any)
• func Panic(err error)
• func PanicFn(fn func() error)
• func Panicf(message string, err error)
• func PanicfFn(msg string, fn func() error)
• func Post(ctx context.Context, url, contentType string, body io.Reader) (*http.Response, error)
• func Stack() string
• func StartProfileServer(profile string) (string, func())
• func StartProfileServerAndStall(profile string)
• func UnusedPort() int
• func WithLabels(ctx context.Context, fn func(context.Context), labelPairs ...any)

Examples

• LogChanged

Variables

var (
	// Marker is the prefix used for log messages going to stdout.
	Marker = "###>"
	// EnableLogs allows to globally enable or disable logging.
	EnableLogs = true

	// LogToFile is the path to a file where logs will be written.
	// Mostly useful if the application being debugged is very noisy and
	// the interesting parts should be separated.
	LogToFile = ""
)

var DumpProfileTraceSeconds = "10"

DumpProfileTraceSeconds is the default number of seconds to collect when collecting the trace profile.

Functions

func Callers

func Callers() []runtime.Frame

Callers returns all frames from the call this function as collected by runtime.Callers and runtime.CallersFrames as a slice.

func DumpProfile

func DumpProfile(profile, pathPrefix string)

DumpToFile starts the pprof server, fetches the given profile and dumps it to the specified file.

func DumpStackToFile

func DumpStackToFile(path, preStack, additionalInfo string)

DumpStackToFile dumps the current stack trace to a file at the specified path.

preStack can be left empty. If it is not empty it will be dumped to the file before the current stack trace. Useful when tracing origins and uses of a private function or callback.

additionalInfo can be left empty. If it is not empty it will be written between the preStack and the current stack trace.

func DumpToFile

func DumpToFile(addr, out string)

DumpToFile fetches the content from the given address and writes it to the specified file.

func Error

func Error(err error) bool

Error returns false if the error is nil, otherwise it logs the error and returns true.

func ErrorFn

func ErrorFn(fn func() error) bool

ErrorFn executes the provided function and passes its error result to Error.

func ErrorFnV

func ErrorFnV[T any](t T, fn func(T) error) bool

ErrorFnV is like ErrorFn but for functions that expect exactly one argument.

func Errorf

func Errorf(err error, format string, args ...any) bool

Errorf returns false if the error is nil, otherwise it logs the provided format and arguments with the error appended and returns true.

func Get

func Get(ctx context.Context, url string) (*http.Response, error)

Get creates a context-aware request and submits it using the http.DefaultClient.

func Head

func Head(ctx context.Context, url string) (*http.Response, error)

Head creates a context-aware request and submits it using the http.DefaultClient.

func IgnoreError

func IgnoreError(err error)

IgnoreError configures which errors should be ignored.

func Log

func Log(msg string)

Log prints a message to stdout or to a file if LogToFile is set.

func LogCallers

func LogCallers()

LogCallers logs all frames from the call of this function as collected by runtime.Callers and runtime.CallersFrames using Log.

func LogChanged

func LogChanged(msg string)

LogChanged logs a message if the content has changed since the last invocation from the same source.

Example

// only prints one "first msg"
logger("first msg")
logger("first msg")
logger("first msg")
// prints "second msg"
logger("second msg")
// prints "first msg" again
logger("first msg")

Output:
###> first msg
###> second msg
###> first msg

func Logf

func Logf(format string, args ...any)

Logf prints a formatted message to stdout or to a file if LogToFile is set.

func LogfChanged

func LogfChanged(format string, args ...any)

LogfChanged logs a formatted message if the content has changed since the last invocation from the same source.

func Panic

func Panic(err error)

Panic does nothing if the error is nil, otherwise it logs the error and panics.

func PanicFn

func PanicFn(fn func() error)

PanicFn executes the provided function and passes its error result to Panic.

func Panicf

func Panicf(message string, err error)

Panicf does nothing if the error is nil, otherwise it logs the message and error.

func PanicfFn

func PanicfFn(msg string, fn func() error)

PanicfFn executes the provided function and passes its error result with the message to Panicf.

func Post

func Post(ctx context.Context, url, contentType string, body io.Reader) (*http.Response, error)

Post creates a context-aware request and submits it using the http.DefaultClient.

func Stack

func Stack() string

Stack returns the current stack trace as a string.

func StartProfileServer

func StartProfileServer(profile string) (string, func())

StartProfileServer starts the pprof server on an unused port and returns the address and a function to stop the server.

func StartProfileServerAndStall

func StartProfileServerAndStall(profile string)

StartProfileServerAndStall calls StartProfileServer, logs the address and stalls indefinitely.

func UnusedPort

func UnusedPort() int

UnusedPort returns a free TCP port on localhost.

func WithLabels

func WithLabels(
	ctx context.Context,
	fn func(context.Context),
	labelPairs ...any,
)

WithLabels is a convenience wrapper around pprof.Do, converting the label pairs to string, adding them to the context and executing the function.

If context is nil it defaults to context.Background().

The label pairs should be key-value pairs:

WithLabels(ctx, fn, "key1", "value1", "key2", "value2")