replay

README

GoReplay: record-less semi-deterministic replayer for Go programs

GoReplay replays concurrent Go programs semi-deterministically without recording concrete events.

How it works

GoReplay injects time.Sleep(time.Duration(hash(seed, context, stack)) % maxInterval) to arbitrary execution points of the target Go program.

• seed: environmental variable GRSEED. You can replay the execution by remembering and setting GRSEED. The default value is empty value and it disables GoReplay.
• context: optional []byte slice.
• stack: runtime stack. (planned)
• maxInterval: environmental variable GRMAX (should be time.Duration string). The default value is 10ms.

Name	Type	Default	Description
GRSEED	string	(empty)	The seed value for determining the delay. An empty value disables GoReplay.
GRMAX	time.Duration	10ms	Max delay.
GRZBIAS	float64	0.0	Probability of enforcing the delay to be zero. must be in [0.0, 1.0).

Usage

Follow the example: example/ex01.

package main

import (
	"fmt"
	"sync"

	"github.com/AkihiroSuda/go-replay"
)

func main() {
	n := 8
	var wg sync.WaitGroup
	for i := 0; i < n; i++ {
		wg.Add(1)
		go func(i interface{}) {
			msg := fmt.Sprintf("i=%d", i)
			replay.Inject([]byte(msg))
			fmt.Printf("%s\n", msg)
			wg.Done()
		}(i)
	}
	wg.Wait()
}

The result is non-deterministic without GoReplay:

$ go run example/ex01/main.go
i=7
i=5
i=1
i=6
i=0
i=2
i=3
i=4
$ (for f in $(seq 1 10);do go run example/ex01/main.go | sha512sum -; done) | sort | uniq | wc -l
4

If you set GRSEED, the result becomes deterministic:

$ (for f in $(seq 1 10);do GRSEED=foo go run example/ex01/main.go | sha512sum -; done) | sort | uniq
7ea818bd9e800609ab8e360688d975189033a9b9277d1ad9c9c96c9013f4ffeb1cf05c16ace9de737dcedaa68bc99162d611ac60b7169a43b4f9b17b1665f121  -

$ (for f in $(seq 1 10);do GRSEED=bar go run example/ex01/main.go | sha512sum -; done) | sort | uniq
fc1c177ebbc58baa7e4960102cf26da25173559de0d7a08e00c37a4512eb0a579fc6b4b70f2c708fe1166a1c0641e8839305d5fe7e26624cabbce2cb8274d963  -

Practical Examples

• example/etcd-5155: data race (coreos/etcd#5155)

Hint

You may use AspectGo(WIP) for automatic instrumentation.

Related project

• Namazu: a programmable fuzzy scheduler for testing distributed systems

GoReplay is planned to be merged to Namazu.

Documentation

Overview

Package replay provides semi-deterministic replayer.

Index

• Constants
• func Inject(context []byte)
• type BasicReplayer
  • func (r *BasicReplayer) Init() error
  • func (r *BasicReplayer) Inject(context []byte)
• type NopReplayer
  • func (r *NopReplayer) Init() error
  • func (r *NopReplayer) Inject(context []byte)
• type Replayer

Constants

const DefaultMax = "10ms"

DefaultMax is the default max delay for DefaultReplayer.

const DefaultSeed = ""

DefaultSeed is the default seed for DefaultReplayer.

const DefaultZBias = "0.0"

DefaultZBias is the default zbias for DefaultReplayer.

Functions

func Inject

func Inject(context []byte)

Inject calls DefaultReplayer.Inject().

Types

type BasicReplayer

type BasicReplayer struct {

	// Debug is true if debugging mode.
	Debug bool
	// Seed is an arbitrary byte slice for replaying execution.
	// If seed is nil, it disables Replayer.
	Seed []byte
	// Max is the max value for delays injected by Replayer.
	Max time.Duration
	// ZBias is the probability of enforcing the delay to be zero.
	ZBias float64
	// contains filtered or unexported fields
}

BasicReplayer is an instance of Replayer.

func (*BasicReplayer) Init

func (r *BasicReplayer) Init() error

Init initializes Replayer.

func (*BasicReplayer) Inject

func (r *BasicReplayer) Inject(context []byte)

Inject injects a random delay using context. The delay can be replayed with the seed value. Context can be nil.

type NopReplayer

type NopReplayer struct {
}

NopReplayer is an instance of Replayer but it does nothing.

func (*NopReplayer) Init

func (r *NopReplayer) Init() error

Init initializes Replayer.

func (*NopReplayer) Inject

func (r *NopReplayer) Inject(context []byte)

Inject injects a random delay using context. The delay can be replayed with the seed value. Context can be nil.

type Replayer

type Replayer interface {
	Init() error
	Inject(context []byte)
}

var DefaultReplayer Replayer = &NopReplayer{}

DefaultReplayer is the default instance of Replayer.