fio

Documentation

Overview

Package fio wraps calls to the fio tool. It assumes the tool is executable by "fio", but gives the option to specify another executable path by setting environment variable FIO_EXE.

Index

• Constants
• Variables
• type Config
  • func (cfg Config) String() string
• type Job
  • func (job Job) String() string
• type NullPathLocker
  • func (l *NullPathLocker) Lock(lockPath string) (pathlock.Unlocker, error)
  • func (l *NullPathLocker) Unlock()
• type Options
  • func (o Options) Merge(other Options) Options
  • func (o Options) WithBlockSize(blockSizeB int64) Options
  • func (o Options) WithDedupePercentage(dPcnt int) Options
  • func (o Options) WithDirectory(dir string) Options
  • func (o Options) WithFileSize(fileSizeB int64) Options
  • func (o Options) WithFileSizeRange(fileSizeMinB, fileSizeMaxB int64) Options
  • func (o Options) WithIOLimit(ioSizeB int64) Options
  • func (o Options) WithIOSize(sizeB int64) Options
  • func (o Options) WithNoFallocate() Options
  • func (o Options) WithNumFiles(numFiles int) Options
  • func (o Options) WithRandRepeat(set bool) Options
  • func (o Options) WithSize(sizeB int64) Options
  • func (o Options) WithSizeRange(sizeMinB, sizeMaxB int64) Options
• type Runner
  • func NewRunner() (fr *Runner, err error)
  • func (fr *Runner) Cleanup()
  • func (fr *Runner) DeleteContentsAtDepth(relBasePath string, depth int, prob float32) error
  • func (fr *Runner) DeleteDirAtDepth(relBasePath string, depth int) error
  • func (fr *Runner) DeleteRelDir(relDirPath string) error
  • func (fr *Runner) Run(args ...string) (stdout, stderr string, err error)
  • func (fr *Runner) RunConfigs(cfgs ...Config) (stdout, stderr string, err error)
  • func (fr *Runner) WriteFiles(relPath string, opt Options) error
  • func (fr *Runner) WriteFilesAtDepth(relBasePath string, depth int, opt Options) error
  • func (fr *Runner) WriteFilesAtDepthRandomBranch(relBasePath string, depth int, opt Options) error

Constants

const (
	// FioExeEnvKey gives the path to the fio executable to use in testing.
	FioExeEnvKey = "FIO_EXE"

	// FioDockerImageEnvKey specifies the docker image tag to use. If
	// FioExeEnvKey is set, the local executable will be used instead of
	// docker, even if this variable is also set.
	FioDockerImageEnvKey = "FIO_DOCKER_IMAGE"

	// LocalFioDataPathEnvKey is the local path where fio data will be
	// accessible. If not specified, defaults to the default temp directory (os.TempDir).
	LocalFioDataPathEnvKey = "LOCAL_FIO_DATA_PATH"

	// HostFioDataPathEnvKey specifies the path where fio data will be written,
	// relative to the docker host. If left blank, defaults to local fio data path
	// (works unless running via docker from within a container, e.g. for development).
	HostFioDataPathEnvKey = "HOST_FIO_DATA_PATH"
)

Environment variable keys.

const (
	BlockSizeFioArg        = "blocksize"
	DedupePercentageFioArg = "dedupe_percentage"
	DirectoryFioArg        = "directory"
	FallocateFioArg        = "fallocate"
	FileSizeFioArg         = "filesize"
	IOLimitFioArg          = "io_limit"
	IOSizeFioArg           = "io_size"
	NumFilesFioArg         = "nrfiles"
	RandRepeatFioArg       = "randrepeat"
	SizeFioArg             = "size"
)

List of FIO argument strings.

const (
	NoneFio       = "none"
	RandWriteFio  = "randwrite"
	RangeDelimFio = "-"
)

List of FIO specific fields and delimiters.

const (
	JobNameFlag = "--name"
)

List of fio flags.

Variables

var (
	ErrNoDirFound       = errors.New("no directory found at this depth")
	ErrCanNotDeleteRoot = errors.New("can not delete root directory")
)

List of known errors.

var (
	ErrEnvNotSet = fmt.Errorf("must set either %v or %v", FioExeEnvKey, FioDockerImageEnvKey)
)

Known error messages.

Types

type Config

type Config []Job

Config structures the fields of a FIO job run configuration.

func (Config) String

func (cfg Config) String() string

String implements the stringer interface, formats the Config as it would appear in a well-formed fio config file.

type Job

type Job struct {
	Name    string
	Options Options
}

Job represents the configuration for running a FIO job.

func (Job) String

func (job Job) String() string

String implements the stringer interface, formats the Job as it would appear in a well-formed fio config file.

type NullPathLocker

type NullPathLocker struct{}

NullPathLocker satisfies the pathlock.Locker interface but is a no-op.

func (*NullPathLocker) Lock

func (l *NullPathLocker) Lock(lockPath string) (pathlock.Unlocker, error)

Lock implements the pathlock.Locker interface.

func (*NullPathLocker) Unlock

func (l *NullPathLocker) Unlock()

Unlock satisfies the pathlock.Unlocker interface.

type Options

type Options map[string]string

Options are flags to be set when running fio.

func (Options) Merge

func (o Options) Merge(other Options) Options

Merge will merge two Options, overwriting common option keys with the incoming option values. Returns the merged result.

func (Options) WithBlockSize

func (o Options) WithBlockSize(blockSizeB int64) Options

WithBlockSize sets the fio block size option.

func (Options) WithDedupePercentage

func (o Options) WithDedupePercentage(dPcnt int) Options

WithDedupePercentage sets the fio dedupe percentage.

func (Options) WithDirectory

func (o Options) WithDirectory(dir string) Options

WithDirectory sets the fio option for the directory to write in.

func (Options) WithFileSize

func (o Options) WithFileSize(fileSizeB int64) Options

WithFileSize sets the fio file size.

func (Options) WithFileSizeRange

func (o Options) WithFileSizeRange(fileSizeMinB, fileSizeMaxB int64) Options

WithFileSizeRange sets the fio file size range.

func (Options) WithIOLimit

func (o Options) WithIOLimit(ioSizeB int64) Options

WithIOLimit sets the fio io limit.

func (Options) WithIOSize

func (o Options) WithIOSize(sizeB int64) Options

WithIOSize sets the fio io size.

func (Options) WithNoFallocate

func (o Options) WithNoFallocate() Options

WithNoFallocate sets the fio option fallocate to "none".

func (Options) WithNumFiles

func (o Options) WithNumFiles(numFiles int) Options

WithNumFiles sets the fio number of files.

func (Options) WithRandRepeat

func (o Options) WithRandRepeat(set bool) Options

WithRandRepeat sets the fio option rand repeat.

func (Options) WithSize

func (o Options) WithSize(sizeB int64) Options

WithSize sets the fio write size.

func (Options) WithSizeRange

func (o Options) WithSizeRange(sizeMinB, sizeMaxB int64) Options

WithSizeRange sets the fio size range.

type Runner

type Runner struct {
	Exe             string
	ExecArgs        []string
	LocalDataDir    string
	FioWriteBaseDir string
	Global          Config
	Debug           bool

	PathLock pathlock.Locker
}

Runner is a helper for running fio commands.

func NewRunner

func NewRunner() (fr *Runner, err error)

NewRunner creates a new fio runner.

func (*Runner) Cleanup

func (fr *Runner) Cleanup()

Cleanup cleans up the data directory.

func (*Runner) DeleteContentsAtDepth

func (fr *Runner) DeleteContentsAtDepth(relBasePath string, depth int, prob float32) error

DeleteContentsAtDepth deletes some or all of the contents of a directory at the provided depths. The probability argument denotes the probability in the range [0.0,1.0] that a given file system entry in the directory at this depth will be deleted. Probability set to 0 will delete nothing. Probability set to 1 will delete everything.

func (*Runner) DeleteDirAtDepth

func (fr *Runner) DeleteDirAtDepth(relBasePath string, depth int) error

DeleteDirAtDepth deletes a random directory at the given depth.

func (*Runner) DeleteRelDir

func (fr *Runner) DeleteRelDir(relDirPath string) error

DeleteRelDir deletes a relative directory in the runner's data directory.

func (*Runner) Run

func (fr *Runner) Run(args ...string) (stdout, stderr string, err error)

Run will execute the fio command with the given args.

func (*Runner) RunConfigs

func (fr *Runner) RunConfigs(cfgs ...Config) (stdout, stderr string, err error)

RunConfigs runs fio using the provided Configs.

func (*Runner) WriteFiles

func (fr *Runner) WriteFiles(relPath string, opt Options) error

WriteFiles writes files to the directory specified by path, up to the provided size and number of files.

func (*Runner) WriteFilesAtDepth

func (fr *Runner) WriteFilesAtDepth(relBasePath string, depth int, opt Options) error

WriteFilesAtDepth writes files to a directory "depth" layers deep below the base data directory.

func (*Runner) WriteFilesAtDepthRandomBranch

func (fr *Runner) WriteFilesAtDepthRandomBranch(relBasePath string, depth int, opt Options) error

WriteFilesAtDepthRandomBranch writes files to a directory "depth" layers deep below the base data directory and branches at a random depth.