performance

README

Go Performance Testing Tool

This repository contains a performance testing tool written in Go. The tool primarily consists of two components: Runner and Summary.

Runner

The Runner is the main component that executes the performance tests. It is initialized with a test duration, a test function, a rate of calls per second, and a verbosity flag.

The test function is a function that is run on each iteration of the test. This function can be any function that returns an error, allowing for great flexibility in what can be tested.

The Runner runs the test function at the specified rate for the specified period of time. It collects statistics about the number of successful and failed tests, as well as the latency of the tests.

A ramp-up period can be specified to gradually increase the rate of calls per second over time. This can be useful for testing how an application behaves under increasing load. This configuration can be set by passing a ramp-up duration to the runner.Run

Summary

The Summary is a report generated by the Runner after the tests are completed. It contains detailed information about the test results, including:

• The total number of tests run.
• The total runtime.
• The number and percentage of successful tests.
• The number and percentage of failed tests.
• A breakdown of the errors that occurred.
• Test latencies.

The Summary also calculates and provides latency percentiles to give a better idea of how the test function performed over time.

Usage

To use this tool, simply import the performance package in your Go code, create a new Runner with the desired test function and configuration, and then call the Run method on the Runner.

package performance_test

import (
	"context"
	"time"
	
	"github.com/tangelo-labs/go-performance"
)

func Example() {
	// Define the test function
	testFunc := func() error {
		// This is where your test code would go.
		// For example, you could make an HTTP request or call a specific function in your application.
		// In this example, we simply simulate the execution of the test function.
		return nil
	}

	// Create a new Runner
	runner := performance.NewRunner(6*time.Second, testFunc, 10, true)

	// Create a context taking into account the timeout because 
	// the Runner will run until the context is canceled or the duration runner.Run parameter is reached.
	// If context is less than the duration runner.Run parameter, 
	// the Runner will stop when the context is canceled due to the timeout.
	ctx, cancel := context.WithTimeout(context.Background(), 10 *time.Second)
	defer cancel()
	
	// Define the ramp-up period for the test.
	rampUp := 2 * time.Second
	
	summary, err := runner.Run(ctx, &rampUp)
	if err != nil {
		// Handle the error here.
		return
	}

	println(summary.String())

	// ╔ RESULTS ═══════════════════════╗
	// ║                                ║
	// ║                                ║
	// ║  - Running Time: 6.910971625s  ║
	// ║  - Iterations: 60              ║
	// ║  - Success ✔: 57 (95.00%)      ║
	// ║  - Failures ✘: 3 (5.00%)       ║
	// ║  - Latencies:                  ║
	// ║    - p(50) = 4 ms              ║
	// ║    - p(75) = 6 ms              ║
	// ║    - p(90) = 9 ms              ║
	// ║    - p(95) = 9 ms              ║
	// ║    - p(99) = 10 ms             ║
	// ║  - Errors:                     ║
	// ║    - [#1] Gray                 ║
	// ║    - [#1] Wheat                ║
	// ║    - [#1] WhiteSmoke           ║
	// ║                                ║
	// ║                                ║
	// ╚════════════════════════════════╝
}

Tests

This repository also includes unit tests for the Runner. The tests simulate a test function with random latency and error rate to demonstrate how the Runner behaves.

Dependencies

This project depends on several Go packages, which can be found in the go.mod file.

Conclusion

This tool is useful for performing stress tests on Go applications, allowing developers to identify and address performance and reliability issues.

License

go-performance is licensed under the MIT License. See the LICENSE file for more information.

Documentation

Overview

Package performance provide basic definitions for building CLI-oriented performance tests.

Index

• type CallbackFn
• type Runner
  • func NewRunner(duration time.Duration, callbackFn CallbackFn, callsPerSecond uint16, ...) *Runner
  • func (p *Runner) Run(ctx context.Context, rampUp *time.Duration) (Summary, error)
• type Summary
  • func (s Summary) String() string

Types

type CallbackFn

type CallbackFn func() error

CallbackFn is the function responsible for executing a unit of work which performance is subject to be evaluated.

type Runner

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

Runner is a performance test runner.

func NewRunner

func NewRunner(
	duration time.Duration,
	callbackFn CallbackFn,
	callsPerSecond uint16,
	verbose bool,
) *Runner

NewRunner creates a new performance test runner.

func (*Runner) Run

func (p *Runner) Run(ctx context.Context, rampUp *time.Duration) (Summary, error)

Run starts running the performance suite and collecting metrics until the given context is canceled, or the duration parameter is reached.

type Summary

type Summary struct {
	// Total number of iterations.
	Total uint64

	// Time is the amount of time spent running the test.
	Time time.Duration

	// Failed is the number of failed iterations.
	Failed uint64

	// FailedPercent percentage of failed iterations.
	FailedPercent float64

	// Success is the number of successful iterations.
	Success uint64

	// SuccessPercent percentage of successful iterations.
	SuccessPercent float64

	// Errors is a list of error messages and their respective counts detected
	// during the test.
	Errors map[string]uint64

	// Latencies the list of observed latencies (in Milliseconds) indexed by
	// percentile.
	Latencies map[uint8]int64
}

Summary is a performance result report.

func (Summary) String

func (s Summary) String() string