stamets

README

STAMETS - STatic Analysis METricS

For programming language experts that rely on standard library static analyzers. Requires Go 1.20

Currently supports gathering metrics for:

• Package loading:
  • Replace all calls to Load in golang.org/x/tools/go/packages
• SSA construction:
  • Replace all calls to AllPackages in golang.org/x/tools/go/ssautil with stamets.AllPackages
• Standard Points-To Analysis (PTA).
  • Replace all calls to Analyze in golang.org/x/tools/go/pointer with stamets.Analyze
• Call graph metrics:
  • Provide GetCallGraphMetrics with a *callgraph.Graph value e.g., as produced by PTA

For wrappers around existing functions, the result is a metrics aggregator in the form of an appropriately typed Metrics structure. To extract the underlying result (and potential error), use the Unpack method.

Collected metrics

Gathered metrics include the following:

• Execution time
• PTA: Additional metrics are gathered for the sizes of points-to sets of the queries included in the PTA results. These include: P50, P90, P99, Maximum size, Predominant points-to set size (mode)
• Call graphs
  • Number of functions
  • Out-degree metrics: P50, P90, P99, Maximum, Predominant out-degree (mode)
  • In-degree metrics: P50, P90, P99, Maximum, Predominant in-degree (mode)

Functions without out-going calls still contribute to out-degree metrics with a single 0 value.

Example

Replacing a PTA Analyze call may be carried out as follows:

// Old:
// 1. Direct call to pointer.Analyze
ptaResults, err := pointer.Analyze(config)

// New:
import "github.com/vladsaiocuber/stamets"

...

// 1. Replace pointer.Analyze with stamets.Analyze
ptaMetrics := stamets.Analyze(config)
// 2. Unpack original results
ptaResults, err := ptaMetrics.Unpack()
// 3. (Optional) Print metrics to stdout
fmt.Println(ptaMetrics.String())

The call graph produced by PTA may have its metrics extracted as follows:

pta, err := stamets.Analyze(config).Unpack()
if err != nil {
    return
}

cgMetrics := stamets.GetCallGraphMetrics(pta.CallGraph)

Documentation

Index

• func TaskWithTimeout[T Metrics](timeout time.Duration, f func() T) (T, bool)
• type BaseMetrics
  • func AllPackages(pkgs []*packages.Package, mode ssa.BuilderMode) BaseMetrics[*ssa.Program]
  • func AllPackagesWithTimeout(t time.Duration, pkgs []*packages.Package, mode ssa.BuilderMode) (BaseMetrics[*ssa.Program], bool)
  • func PackagesLoad(config *packages.Config, query string) BaseMetrics[[]*packages.Package]
  • func PackagesLoadWithTimeout(t time.Duration, config *packages.Config, query string) (BaseMetrics[[]*packages.Package], bool)
  • func (m BaseMetrics[T]) Ok() bool
  • func (m BaseMetrics[T]) Unpack() (T, error)
  • func (m BaseMetrics[T]) UnpackAny() (any, error)
• type CallGraphMetrics
  • func AggregateCallGraphResults(dir string) []CallGraphMetrics
  • func GetCallGraphMetrics(cg *callgraph.Graph) CallGraphMetrics
  • func UnparseCallGraphMetricsFromReader(r io.Reader) []CallGraphMetrics
  • func (m CallGraphMetrics) CallGraphInDegreeMetrics() CallGraphMetrics
  • func (m CallGraphMetrics) CallGraphOutDegreeMetrics() CallGraphMetrics
  • func (m CallGraphMetrics) NumberOfFunctions() int
  • func (m CallGraphMetrics) String() string
• type Metrics
• type PTAMetrics
  • func AggregatePTAResults(dir string) []PTAMetrics
  • func Analyze(config *pointer.Config) PTAMetrics
  • func AnalyzeWithTimeout(t time.Duration, config *pointer.Config) (PTAMetrics, bool)
  • func UnparsePTAResultsFromReader(r io.Reader) []PTAMetrics
  • func (m PTAMetrics) PointsToSetMetrics() PTAMetrics
  • func (m PTAMetrics) String() string
• type Series
  • func MakeSeries[T any, U constraints.Ordered](get func(T) U, ts ...T) Series[U]
  • func (s Series[T]) Max() T
  • func (s Series[T]) Mode() T
  • func (s Series[T]) Order() []T
  • func (s Series[T]) P50() T
  • func (s Series[T]) P90() T
  • func (s Series[T]) P99() T

Functions

func TaskWithTimeout

func TaskWithTimeout[T Metrics](timeout time.Duration, f func() T) (T, bool)

TaskWithTimeout performs a task with collectible metrics in the alloted time limit. It returns the Metrics-wrapped result and 'true' if the operation was completed before the timeout, or the zero Metrics value and 'false' otherwise.

Types

type BaseMetrics

type BaseMetrics[T any] struct {
	// Time it took to perform task
	time.Duration

	Payload T
	// contains filtered or unexported fields
}

BaseMetrics provides a foundation for other metrics to build upon. Basic information include the duration to perform a task, whether the task produced an error, and the result produced by the task.

func AllPackages

func AllPackages(pkgs []*packages.Package, mode ssa.BuilderMode) BaseMetrics[*ssa.Program]

AllPackages builds a list of packages as an SSA program. It also invokes .Build() on the produced SSA program.

func AllPackagesWithTimeout

func AllPackagesWithTimeout(t time.Duration, pkgs []*packages.Package, mode ssa.BuilderMode) (BaseMetrics[*ssa.Program], bool)

AllPackagesWithTimeout builds a list of packages as an SSA program in the alloted time limit. It also invokes .Build() on the produced SSA program.

func PackagesLoad

func PackagesLoad(config *packages.Config, query string) BaseMetrics[[]*packages.Package]

PackagesLoad loads packages according to the specified configuration and further filters them with `query`. It performs additional filtering when the configuration includes test packages.

func PackagesLoadWithTimeout

func PackagesLoadWithTimeout(t time.Duration, config *packages.Config, query string) (BaseMetrics[[]*packages.Package], bool)

PackagesLoadWithTimeout loads packages according to the specified configuration within the alloted time limit, and further filters them with `query`. It performs additional filtering when the configuration includes test packages.

func (BaseMetrics[T]) Ok

func (m BaseMetrics[T]) Ok() bool

Ok checks whether the desired function failed to execute.

func (BaseMetrics[T]) Unpack

func (m BaseMetrics[T]) Unpack() (T, error)

Unpack extracts the payload wrapped in the metrics, and an error, if one was produced.

func (BaseMetrics[T]) UnpackAny

func (m BaseMetrics[T]) UnpackAny() (any, error)

UnpackAny extracts the payload wrapped in the metrics, and an error, if one was produced. UnpackAny allows the implementation of the Metrics interface.

type CallGraphMetrics

type CallGraphMetrics struct {
	BaseMetrics[*callgraph.Graph]

	Functions int

	// Call graph out degree metrics
	OutDegreeMax  int
	OutDegreeP50  int
	OutDegreeP90  int
	OutDegreeP99  int
	OutDegreeMode int

	// Call graph in degree metrics
	InDegreeMax  int
	InDegreeP50  int
	InDegreeP90  int
	InDegreeP99  int
	InDegreeMode int
}

CallGraphMetrics encodes metrics about call graphs e.g. as collected by a PTA/RTA analysis.

func AggregateCallGraphResults

func AggregateCallGraphResults(dir string) []CallGraphMetrics

AggregateCallGraphResults recursively walks a directory, reads every file, and then unparses and aggregates all potential call graph metrics in the contents.

func GetCallGraphMetrics

func GetCallGraphMetrics(cg *callgraph.Graph) CallGraphMetrics

GetCallGraphMetrics constructs metrics from a given call graph.

func UnparseCallGraphMetricsFromReader

func UnparseCallGraphMetricsFromReader(r io.Reader) []CallGraphMetrics

UnparseCallGraphMetricsFromReader reads the whole content of a reader and then unparses it line by line. Any reconstructed CallGraphMetrics values are aggregated and then returned in a slice.

func (CallGraphMetrics) CallGraphInDegreeMetrics

func (m CallGraphMetrics) CallGraphInDegreeMetrics() CallGraphMetrics

CallGraphOutdegreeMetrics computes in-degree metrics on the call graph.

func (CallGraphMetrics) CallGraphOutDegreeMetrics

func (m CallGraphMetrics) CallGraphOutDegreeMetrics() CallGraphMetrics

CallGraphOutDegreeMetrics computes out-degree metrics on the call graph. The out degree is computed per-call site. Every function without outgoing calls contributes with a 0 to the statistics.

func (CallGraphMetrics) NumberOfFunctions

func (m CallGraphMetrics) NumberOfFunctions() int

NumberOfFunctions produces the number of functions in the call-graph produced by the Points-To analysis.

func (CallGraphMetrics) String

func (m CallGraphMetrics) String() string

type Metrics

type Metrics interface {
	UnpackAny() (any, error)
	Ok() bool
}

type PTAMetrics

type PTAMetrics struct {
	BaseMetrics[*pointer.Result]

	Queries         int
	IndirectQueries int

	// Maximum points-to set size.
	PointsToSetSizeMax  int
	PointsToSetSizeP50  int
	PointsToSetSizeP90  int
	PointsToSetSizeP99  int
	PointsToSetSizeMode int
}

PTAMetrics aggregates important metrics about the points-to analysis.

func AggregatePTAResults

func AggregatePTAResults(dir string) []PTAMetrics

AggregatePTAResults recursively walks a directory, reads every file, and then unparses and aggregates all potential PTA metrics in the contents.

func Analyze

func Analyze(config *pointer.Config) PTAMetrics

Analyze runs the points-to analysis with the given configuration, collecting metrics i.e., duration and information about the call graph.

func AnalyzeWithTimeout

func AnalyzeWithTimeout(t time.Duration, config *pointer.Config) (PTAMetrics, bool)

AnalyzeWithTimeout runs the points-to analysis with the given configuration in the alloted time limit, collecting metrics i.e., duration and information about the call graph.

func UnparsePTAResultsFromReader

func UnparsePTAResultsFromReader(r io.Reader) []PTAMetrics

UnparsePTAResultsFromReader reads the whole content of a reader and then unparses it line by line. Any reconstructed PTAMetrics values are aggregated and then returned in a slice.

func (PTAMetrics) PointsToSetMetrics

func (m PTAMetrics) PointsToSetMetrics() PTAMetrics

PointsToSetMetrics computes metrics about the sizes of points-to sets.

func (PTAMetrics) String

func (m PTAMetrics) String() string

type Series

type Series[T constraints.Ordered] []T

Series is a sequence of orderable values.

func MakeSeries

func MakeSeries[T any, U constraints.Ordered](get func(T) U, ts ...T) Series[U]

MakeSeries creates an ordered series from a data list, given a transformation function over data in the list.

func (Series[T]) Max

func (s Series[T]) Max() T

Max returns the largest value in the series.

func (Series[T]) Mode

func (s Series[T]) Mode() T

Mode returns the most common value in the series.

func (Series[T]) Order

func (s Series[T]) Order() []T

Order returns a sorted copy of the original series, but where all elements have been ordered.

func (Series[T]) P50

func (s Series[T]) P50() T

P50 returns the smallest value in the 50'th percentile of the series.

func (Series[T]) P90

func (s Series[T]) P90() T

P90 returns the smallest value in the 90'th percentile of the series.

func (Series[T]) P99

func (s Series[T]) P99() T

P99 returns the smallest value in the 99'th percentile of the series.