joefriday

README

joefriday

"All we want are the facts, ma'am"

• Joe Friday

JoeFriday is a group of libraries that gathers system information: cpu, disk, memory, network, system, etc. This information can be returned as Go structs, Flatbuffers serialized bytes, or JSON serialized bytes. For Flatbuffers and JSON, deserialization convenience methods are provided. When it makes sense, a Ticker based implementation is provided to enable periodic gathering of information.

JoeFriday seeks to minimize allocations and time spent gathering the information. For minimal resource usage, use the sysinfo implementations, if appropriate, as the data provided by those implementations use syscalls, which are at least an order of magnitude faster than processing the proc files.

This library only supports Linux.

See package specific READMEs for information about what those packages provide.

Benchmarks

Comparative Benchmarks

The bench package provides comparative benchmarks; showing how JoeFriday implementations compare with some other libraries that provide similar information.

The information provided by the various libraries are not the same; that should also be factored into the decision as to which library best suits your requirements.

Either a benchmark app can be compiled with go build or they can be run using go test -bench=. [flags].

The benchmark app's output includes group, e.g. CPU, Memory, etc, package name and function called, Ops, ns/Op, B/op, and Allocs/Op. The output can be formatted as text lines (default), CSV, or Markdown Table and written to a file.

JoeBench

JoeBench is an app that runs benchmarks of JoeFriday functionality, including serialization implementations, and generates formatted output. Output includes group, e.g. CPU, Memory, etc, package name and function called, Ops, ns/Op, B/op, and Allocs/Op. The output can be formatted as text lines (default), CSV, or Markdown Table and written to a file.

Notes:

A big thanks to Eric Lagergren for all of his help and his contributions.

alpha-1 branch:

The alpha-1 branch has the original JoeFriday implementation. If your code relies on the package's state prior to 7/2017, this branch should be used if you don't want to change your existing code to work with the refactored JoeFriday.

TODO

• Provide protobuf implementations.
• Add CPU speed info: min, max, current.
• For utilization and usage, add output of deltas between snapshots.
• For utilization and usage revisit calculations and algorithms used, maybe add additional algorithms, where appropriate. This may be a separate library.

Documentation

Overview

Package joefriday gets information about a system: platform, kernel, memory information, cpu information, cpu stats, cpu utilization, network information, and network usage.

Ticker versions of non-static information are available to enable monitoring.

The data can be returned as Go structs, Flatbuffer serialized bytes, or JSON serialized bytes. For convenience, there are deserialization functions for all structs that are serialized.

Index

• Constants
• func Column(w int, s string) string
• func Int64Column(w int, v int64) string
• func IsParseError(e error) bool
• func IsReadError(e error) bool
• func IsResetError(e error) bool
• func TrimLeadingSpaces(p []byte) []byte
• func TrimTrailingSpaces(p []byte) []byte
• type Buffer
  • func NewBuffer() *Buffer
  • func (b *Buffer) Reset()
• type ParseError
  • func (e *ParseError) Error() string
• type Proc
  • func NewProc(fname string) (*Proc, error)
  • func (p *Proc) ReadSlice(delim byte) (line []byte, err error)
  • func (p *Proc) Reset() error
• type Procer
• type ReadError
  • func (e *ReadError) Error() string
• type ResetError
  • func (e *ResetError) Error() string
• type TempFileProc
  • func NewTempFileProc(prefix, name string, data []byte) (proc *TempFileProc, err error)
  • func (p *TempFileProc) FullPath() string
  • func (p *TempFileProc) ReadSlice(delim byte) (line []byte, err error)
  • func (p *TempFileProc) Remove() error
  • func (p *TempFileProc) Reset() error
• type Ticker
  • func NewTicker(d time.Duration) *Ticker
  • func (t *Ticker) Close()
  • func (t *Ticker) Stop()
• type Tocker

Constants

const SysFSSystem = "/sys/devices/system"

Functions

func Column

func Column(w int, s string) string

Column returns a right justified string of width w. TODO: replace with text/tabwriter

func Int64Column

func Int64Column(w int, v int64) string

Int64Column takes an int64 and returns a right justified string of width w.

func IsParseError

func IsParseError(e error) bool

IsParseError r eturns a boolean indicating whether the error is a result of encountering a problem while trying to parse the file data.

func IsReadError

func IsReadError(e error) bool

IsReadError returns a boolean indicating whether the error is a result of a read problem.

func IsResetError

func IsResetError(e error) bool

IsResetError returns a boolean indicating whether the error is a result of a problem resetting the file buffer.

func TrimLeadingSpaces

func TrimLeadingSpaces(p []byte) []byte

TrimLeadingpaces removes the leading spaces from a slice and returns it. Only 0x20 and tabs are considered space characters.

func TrimTrailingSpaces

func TrimTrailingSpaces(p []byte) []byte

TrimTrailingSpaces removes the trailing spaces from a slice and returns it. Only 0x20, tabs, NL are considered space characters.

Types

type Buffer

type Buffer struct {
	Line []byte
	Val  []byte
}

Buffer is used to hold lines and values being processed.

func NewBuffer

func NewBuffer() *Buffer

NewBuffer returns an initialized Buffer.

func (*Buffer) Reset

func (b *Buffer) Reset()

Reset resets the Buffer's slices len to 0 so that they can be re-used.

type ParseError

type ParseError struct {
	Info string
	Err  error
}

func (*ParseError) Error

func (e *ParseError) Error() string

type Proc

type Proc struct {
	*os.File
	Buf *bufio.Reader
}

A Proc holds everything related to a proc file and some processing vars.

func NewProc

func NewProc(fname string) (*Proc, error)

NewProc Creates a Proc using the file handle.

func (*Proc) ReadSlice

func (p *Proc) ReadSlice(delim byte) (line []byte, err error)

ReadSlice is a wrapper for bufio.Reader.ReadSlice.

func (*Proc) Reset

func (p *Proc) Reset() error

Reset reset's the profiler's resources.

type Procer

type Procer interface {
	ReadSlice(byte) ([]byte, error)
	Reset() error
}

Procer processes things.

type ReadError

type ReadError struct {
	Info string
	Err  error
}

func (*ReadError) Error

func (e *ReadError) Error() string

type ResetError

type ResetError struct {
	Err error
}

func (*ResetError) Error

func (e *ResetError) Error() string

type TempFileProc

type TempFileProc struct {
	*Proc
	// The directory holding the temp file.
	Dir string
	// The name of the file.
	Name string
}

TempFileProc is used to do Proc processing off of a temp file. Prefer using the Proc type instead.

func NewTempFileProc

func NewTempFileProc(prefix, name string, data []byte) (proc *TempFileProc, err error)

NewTempFileProc creates a temporary file with data as its contents and returns a TempFileProc that uses the temporary file. The file will be saved in a randomly generated tempdir that starts with prefix. If prefix is empty the os.TempDir will be used as the save directory. Name is the name of the temporary file that will be created. If name is empty, the name will be 12 randomly selected characters without an extension. The data will be used for the file and the file will be created with 0777 perms. If an error occurs, proc will be nil.

func (*TempFileProc) FullPath

func (p *TempFileProc) FullPath() string

Returns the full path of the temp file for this TempFileProc.

func (*TempFileProc) ReadSlice

func (p *TempFileProc) ReadSlice(delim byte) (line []byte, err error)

ReadSlice is a wrapper for bufio.Reader.ReadSlice.

func (*TempFileProc) Remove

func (p *TempFileProc) Remove() error

Remove removes the temp dir and temp file.

func (*TempFileProc) Reset

func (p *TempFileProc) Reset() error

Reset reset's the profiler's resources.

type Ticker

type Ticker struct {
	*time.Ticker
	Done chan struct{} // done channel
	Errs chan error    // error channel
}

func NewTicker

func NewTicker(d time.Duration) *Ticker

func (*Ticker) Close

func (t *Ticker) Close()

Close stops the ticker and closes the ticker resources.

func (*Ticker) Stop

func (t *Ticker) Stop()

Stop sends a signal to the done channel; stopping the Ticker. The Ticker can be restarted with Run.

type Tocker

type Tocker interface {
	Close() // Close the Tocker's resources
	Run()   // Run some code on an interval.
	Stop()  // Stop the Tocker.
}