profiling

package
v0.23.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 4, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package profiling provides integrated profiling capabilities for CargoShip performance analysis and optimization.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExitCodeFromRegressions added in v0.6.1 

func ExitCodeFromRegressions(regressions []Regression) int

ExitCodeFromRegressions returns appropriate exit code based on severity

func FormatRegressions added in v0.6.1 

func FormatRegressions(regressions []Regression) string

FormatRegressions formats regressions for display

func SaveBaseline added in v0.6.1 

func SaveBaseline(baseline *Baseline, path string) error

SaveBaseline saves baseline to a JSON file

func Track added in v0.6.1 

func Track(name string, fn func() error) error

Track wraps a function with timing and logging

func TrackResources added in v0.6.1 

func TrackResources(name string, fn func() error) error

TrackResources wraps a function with resource usage tracking

func TrackWithContext added in v0.6.1 

func TrackWithContext(ctx context.Context, name string, fn func(context.Context) error) error

TrackWithContext wraps a function with timing, logging, and context

Types

type Baseline added in v0.6.1 

type Baseline struct {
	// Version of the software
	Version string `json:"version"`

	// Timestamp when baseline was captured
	Timestamp time.Time `json:"timestamp"`

	// Environment information
	Environment EnvironmentInfo `json:"environment"`

	// Benchmarks maps benchmark name to metrics
	Benchmarks map[string]BenchmarkMetrics `json:"benchmarks"`
}

Baseline represents a performance baseline for regression detection

func LoadBaseline added in v0.6.1 

func LoadBaseline(path string) (*Baseline, error)

LoadBaseline loads baseline from a JSON file

func NewBaseline added in v0.6.1 

func NewBaseline(version string) *Baseline

NewBaseline creates a new baseline

func (*Baseline) AddBenchmark added in v0.6.1 

func (b *Baseline) AddBenchmark(name string, metrics BenchmarkMetrics)

AddBenchmark adds benchmark metrics to the baseline

type BenchmarkMetrics added in v0.6.1 

type BenchmarkMetrics struct {
	// NsPerOp nanoseconds per operation
	NsPerOp float64 `json:"ns_per_op"`

	// AllocedBytesPerOp bytes allocated per operation
	AllocedBytesPerOp float64 `json:"alloced_bytes_per_op"`

	// AllocsPerOp allocations per operation
	AllocsPerOp float64 `json:"allocs_per_op"`

	// MBPerSec throughput in MB/s (if applicable)
	MBPerSec float64 `json:"mb_per_sec,omitempty"`
}

BenchmarkMetrics contains performance metrics for a benchmark

type Config 

type Config struct {
	// OutputDir where profile files will be written
	OutputDir string

	// Profiles to collect
	Profiles []ProfileType

	// BlockRate for block profiling (default: 1)
	BlockRate int

	// MutexFraction for mutex profiling (default: 1)
	MutexFraction int
}

Config configures the profiler

func AllProfilesConfig 

func AllProfilesConfig() Config

AllProfilesConfig returns config for all profile types

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns a sensible default configuration

type EnvironmentInfo added in v0.6.1 

type EnvironmentInfo struct {
	// GoVersion Go runtime version
	GoVersion string `json:"go_version"`

	// OS operating system
	OS string `json:"os"`

	// Arch CPU architecture
	Arch string `json:"arch"`

	// NumCPU number of CPUs
	NumCPU int `json:"num_cpu"`

	// Hostname machine hostname
	Hostname string `json:"hostname"`
}

EnvironmentInfo captures system information

func CaptureEnvironment added in v0.6.1 

func CaptureEnvironment() EnvironmentInfo

CaptureEnvironment captures current environment information

type ProfileInfo 

type ProfileInfo struct {
	// Type of profile
	Type ProfileType

	// Filename where profile was written
	Filename string

	// Size in bytes
	Size int64
}

ProfileInfo contains information about a single profile

type ProfileResults 

type ProfileResults struct {
	// OutputDir where profiles were written
	OutputDir string

	// Duration of profiling session
	Duration time.Duration

	// Profiles that were collected
	Profiles []ProfileInfo

	// MemoryStats final memory statistics
	MemoryStats runtime.MemStats
}

ProfileResults contains the results of profiling

type ProfileType 

type ProfileType string

ProfileType represents the type of profile to collect 

const (
	// ProfileCPU collects CPU profiling data
	ProfileCPU ProfileType = "cpu"

	// ProfileMemory collects heap memory profiling data
	ProfileMemory ProfileType = "memory"

	// ProfileGoroutine collects goroutine profiling data
	ProfileGoroutine ProfileType = "goroutine"

	// ProfileBlock collects blocking profiling data
	ProfileBlock ProfileType = "block"

	// ProfileMutex collects mutex contention profiling data
	ProfileMutex ProfileType = "mutex"

	// ProfileTrace collects execution trace data
	ProfileTrace ProfileType = "trace"
)

type Profiler 

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

Profiler orchestrates profiling operations

func New 

func New(config Config) (*Profiler, error)

New creates a new profiler

func (*Profiler) GetResults 

func (p *Profiler) GetResults() (*ProfileResults, error)

GetResults returns profiling results

func (*Profiler) Start 

func (p *Profiler) Start() error

Start begins profiling

func (*Profiler) Stop 

func (p *Profiler) Stop() error

Stop stops profiling and writes results

type Regression added in v0.6.1 

type Regression struct {
	// BenchmarkName that regressed
	BenchmarkName string

	// Metric that regressed
	Metric string

	// BaselineValue previous value
	BaselineValue float64

	// CurrentValue new value
	CurrentValue float64

	// PercentChange percentage change
	PercentChange float64

	// Threshold that was exceeded
	Threshold float64

	// Severity of the regression
	Severity RegressionSeverity
}

Regression represents a detected performance regression

func DetectRegressions added in v0.6.1 

func DetectRegressions(baseline *Baseline, current *Baseline, thresholds RegressionThresholds) []Regression

DetectRegressions compares current metrics against baseline

type RegressionSeverity added in v0.6.1 

type RegressionSeverity string

RegressionSeverity indicates severity level 

const (
	SeverityLow      RegressionSeverity = "low"
	SeverityMedium   RegressionSeverity = "medium"
	SeverityHigh     RegressionSeverity = "high"
	SeverityCritical RegressionSeverity = "critical"
)

type RegressionThresholds added in v0.6.1 

type RegressionThresholds struct {
	// TimeThreshold acceptable time increase (e.g., 0.10 = +10%)
	TimeThreshold float64

	// MemoryThreshold acceptable memory increase (e.g., 0.15 = +15%)
	MemoryThreshold float64

	// AllocThreshold acceptable allocation increase (e.g., 0.20 = +20%)
	AllocThreshold float64

	// ThroughputThreshold acceptable throughput decrease (e.g., -0.05 = -5%)
	ThroughputThreshold float64
}

RegressionThresholds defines acceptable degradation

func DefaultThresholds added in v0.6.1 

func DefaultThresholds() RegressionThresholds

DefaultThresholds returns sensible default thresholds

type ResourceDelta added in v0.6.1 

type ResourceDelta struct {
	Duration       time.Duration
	GoroutineDiff  int
	AllocDiff      int64
	TotalAllocDiff uint64
	SysDiff        int64
	NumGCDiff      uint32
	PauseDiff      uint64
}

ResourceDelta calculates the difference between two snapshots

func (ResourceDelta) LogDelta added in v0.6.1 

func (d ResourceDelta) LogDelta(operation string)

LogDelta logs the resource delta

type ResourceSnapshot added in v0.6.1 

type ResourceSnapshot struct {
	Timestamp    time.Time
	Goroutines   int
	Alloc        uint64
	TotalAlloc   uint64
	Sys          uint64
	NumGC        uint32
	PauseTotalNs uint64
}

ResourceSnapshot captures current resource usage

func CaptureResourceSnapshot added in v0.6.1 

func CaptureResourceSnapshot() ResourceSnapshot

CaptureResourceSnapshot takes a snapshot of current resource usage

func (ResourceSnapshot) Delta added in v0.6.1 

func (before ResourceSnapshot) Delta(after ResourceSnapshot) ResourceDelta

Delta computes the delta between two resource snapshots

type RuntimeConfig added in v0.6.1 

type RuntimeConfig struct {
	// Addr is the address to listen on (e.g., "localhost:6060")
	Addr string

	// ReadTimeout for HTTP server
	ReadTimeout time.Duration

	// WriteTimeout for HTTP server
	WriteTimeout time.Duration
}

RuntimeConfig configures runtime profiling

func DefaultRuntimeConfig added in v0.6.1 

func DefaultRuntimeConfig() RuntimeConfig

DefaultRuntimeConfig returns sensible defaults

type RuntimeProfiler added in v0.6.1 

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

RuntimeProfiler provides HTTP endpoint for runtime profiling

func NewRuntimeProfiler added in v0.6.1 

func NewRuntimeProfiler(config RuntimeConfig) *RuntimeProfiler

NewRuntimeProfiler creates a new runtime profiler

func StartRuntimeProfiler added in v0.6.1 

func StartRuntimeProfiler(addr string) (*RuntimeProfiler, error)

StartRuntimeProfiler is a convenience function to start profiling in the background

func (*RuntimeProfiler) Addr added in v0.6.1 

func (rp *RuntimeProfiler) Addr() string

Addr returns the address the profiler is listening on

func (*RuntimeProfiler) Start added in v0.6.1 

func (rp *RuntimeProfiler) Start(ctx context.Context) error

Start begins serving pprof endpoints

func (*RuntimeProfiler) Stop added in v0.6.1 

func (rp *RuntimeProfiler) Stop() error

Stop gracefully shuts down the profiler

type Timer added in v0.6.1 

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

Timer tracks execution time for operations

func NewTimer added in v0.6.1 

func NewTimer(name string) *Timer

NewTimer creates a new timer for an operation

func (*Timer) Stop added in v0.6.1 

func (t *Timer) Stop() time.Duration

Stop stops the timer and logs the duration

func (*Timer) StopWithError added in v0.6.1 

func (t *Timer) StopWithError(err error) time.Duration

StopWithError stops the timer and logs with error

func (*Timer) WithLabel added in v0.6.1 

func (t *Timer) WithLabel(key string, value interface{}) *Timer

WithLabel adds a label to the timer

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.