flush

Documentation

Overview

Package flush provides zero-dependency runtime coverage collection for Go services.

It captures coverage data from running processes built with -cover flag, without requiring the process to stop.

Basic usage:

flush.Enable(flush.Config{
    ServiceName:  "my-service",
    BuildVersion: "abc1234",
    Interval:     30 * time.Second,
    Clear:        true,
})
defer flush.Stop()

For serverless environments (e.g., AWS Lambda) where periodic flushing is not possible, call Emit manually after each request:

flush.Emit()

The Storage interface abstracts the destination for coverage files. Built-in implementations include LocalStorage for local directories and WriterStorage for debugging. The objstore sub-package provides remote storage support for S3, GCS, and Azure Blob Storage.

Index

• func Emit() error
• func Enable(cfg Config)
• func HandleSignal(sigs ...os.Signal)
• func Stop() error
• type Config
• type LocalStorage
  • func (s LocalStorage) Store(_ context.Context, files []string, _ Metadata) error
• type Metadata
• type Storage
• type WriterStorage
  • func (s WriterStorage) Store(_ context.Context, files []string, meta Metadata) error

Functions

func Emit

func Emit() error

Emit performs an immediate coverage data flush.

func Enable

func Enable(cfg Config)

Enable activates coverage flushing with the given configuration. If the binary was not built with -cover, Enable is a no-op.

func HandleSignal

func HandleSignal(sigs ...os.Signal)

HandleSignal registers signal-based flush triggers. When any of the specified signals is received, a flush is performed. Calling HandleSignal again replaces the previous signal handler.

func Stop

func Stop() error

Stop performs a final flush and stops periodic flushing. It returns the error from the final flush, if any. It should be called via defer after Enable.

Types

type Config

type Config struct {
	// Storage is the destination for coverage data. If nil, LocalStorage using
	// GOCOVERDIR environment variable is used as a fallback.
	Storage Storage

	// ServiceName identifies the service producing coverage data.
	ServiceName string

	// BuildVersion is the build version or commit hash. Coverage data from
	// different build versions must not be merged (covmeta incompatibility).
	BuildVersion string

	// Interval sets the periodic flush interval. Zero disables periodic flush.
	Interval time.Duration

	// Clear resets coverage counters after each flush (atomic mode only).
	Clear bool

	// OnError is called when a background flush (periodic or signal-triggered)
	// fails. If nil, background flush errors are silently discarded.
	OnError func(error)
}

Config configures the coverage flush behavior.

type LocalStorage

type LocalStorage struct {
	Dir string
}

LocalStorage saves coverage files to a local directory in GOCOVERDIR-compatible layout.

func (LocalStorage) Store

func (s LocalStorage) Store(_ context.Context, files []string, _ Metadata) error

type Metadata

type Metadata struct {
	Timestamp    time.Time
	Hostname     string
	PodName      string // auto-populated from POD_NAME env var (k8s downward API)
	BuildVersion string // build version or commit hash (set via Config)
	ServiceName  string // service identifier (set via Config)
}

Metadata carries information associated with coverage data.

type Storage

type Storage interface {
	// Store saves coverage files (covmeta + covcounters) from a temporary directory.
	// files is a list of file paths within the temp directory.
	Store(ctx context.Context, files []string, meta Metadata) error
}

Storage abstracts the destination for coverage data files.

type WriterStorage

type WriterStorage struct {
	W io.Writer
}

WriterStorage writes coverage data as text profile format to the given writer. This is primarily for debugging purposes.

func (WriterStorage) Store

func (s WriterStorage) Store(_ context.Context, files []string, meta Metadata) error