motor

README

Motor

⚙️ A set of tools for logging, debugging, and measuring of Go code.

package main

import "aletheia.icu/motor"

func main() {
	// Motor functions via three three basic output modes.
	//
	// 1. log() is used for ordinary logs.
	// 2. debug() is used when "probing" and debugging.
	// 3. trace() is invoked only tracing / benchmarking purposes.
	log, debug, trace := motor.New()

	// V(2) forces debug mode.
	motor.V(2)

	log("Hello, world!")

	if debug() {
		debug("In debug mode.")

		n, m := 10, 0
		for i := 1; i <= n; i++ {
			trace("m (%d) += %d", m, i)
			m += i
		}

		debug("verifying")
		debug("m =", m)
		debug("m expected =", n*(n+1)/2)
	}
}

package main

//go:generate go install aletheia.icu/motor/cmd/probe
import (
	"strconv"
	"testing"

	"aletheia.icu/motor"
)

var log, debug, _ = motor.New()

// $ probe tinything [n]
//
func TestTinything(t *testing.T) {
	// if not in probe, quit early
	if !debug() {
		// in general order, by now
		// this test would have performed nothing.
		return
	}

	log("Proceed")

	// in probe, simply use args to augment the test.
	n, _ := strconv.Atoi(motor.Args[0])
	log("n = %d", n)
}

This repository contains a small Go library, an interface, and two simple command–line tools, probe and speed.

Install

go get -u aletheia.icu/motor

" optional
go install aletheia.icu/motor/cmd/probe
go install aletheia.icu/motor/cmd/speed

Background

Here's the deal.

I grew accustomed to a certain minimalistic programming style,

Suddenly, everything made sense. No more worries about logging and metrics. I've finally managed to incoroporate unit testing into my development workflow, to the point motor programming should probably look reminiscent of so–called test–driven development, which I learned to hate over the years.

There's nothing worse than assert(2+2, 4) and you know it.

I've come to realise that at some point my code becomes aware of its surroundings, be it planned or not. Motor programming model exploits this: there are three output modes, progressively more and more verbose. In normal conditions, my code is expected to run in log(1), debug(2), and sometimes, trace(3) modes.

Now, quantitative analysis of code, benchmarks.

Go can be very progressive in some major respects. For instance, it supports first–class benchmarks via Benchmark* functions and go test. Unfortunately, this is simply not enough. Benchmarking becomes overly counter–intuitive to apply in your development workflow the moment you walk out of the some abstract algorithm in some abstract context realm. And it's a good thing. There's no point desperately trying to fit your all–round code into a very square hole that is a benchmark. Quite a lot of it has to do with data locality. In real–life, code components are far from decoupled. It's not so much of a trouble, but inconvenience—to test them as such, without constantly having to fall back and refer to them as the whole. Maybe we're better off performing at least some of the measturements while the code is still running normally? In any case, that's exactly what speed does. There are two things you can measure, ∆t and ∆d/∆t. This may not seem like much, but in fact it's all you need. You get time and differential, latency and throughput. Go take some measurements! Good code is traceable, so you should report them over trace(). If the program runs in speed, it will trace automatically. The tool will then collect the printed measurements and produce a CSV (comma–separated values) output.

Usage

Motor is a no bullshit piece of software.

Program probe

Use program to run an individual probe of a test.

In vim, list all availablte tests with

:!probe

TestAlbus
TestBrewer
TestMethod01
TestMethod02
TestZoo

Then,

:!probe method01

=== RUN   TestMethod01
probe complete
--- PASS: TestMethod01 (0.00s)
PASS
ok      test    0.083s

To run a tracing probe,

:!probe method02...

=== RUN   TestMethod01
tracing on
% n=1 m=7.083
% n=2 m=9.112
probe complete
--- PASS: TestMethod02 (0.00s)
PASS
ok      test    0.180s

Program speed

TBA

License

MIT

Documentation

Index

• type Adapter
• type Brr
  • func (brr *Brr) Debug(mode ...bool) bool
  • func (brr *Brr) Debugf(format string, a ...interface{})
  • func (brr *Brr) Debugln(a ...interface{})
  • func (brr *Brr) Flush()
  • func (brr *Brr) Func(namekind, id string) *Brr
  • func (brr *Brr) Gofunc(namekind, id string, f func(*Brr))
  • func (brr *Brr) Printf(format string, a ...interface{})
  • func (brr *Brr) Println(a ...interface{})
• type Chunk
  • func (c Chunk) Autowrite(w io.Writer)
  • func (c Chunk) Flag(f Flag) bool
• type Config
• type Example
  • func (adp *Example) Begin(brr *Brr)
  • func (adp *Example) Device() io.Writer
  • func (adp *Example) End(brr *Brr)
  • func (adp *Example) MaxLatency() time.Duration
  • func (adp *Example) Write(brr *Brr, c Chunk, w io.Writer)
• type Flag
• type Motor
  • func New(config Config) *Motor
• type Tag

Types

type Adapter

type Adapter interface {
	// Begin is called whenever a procedure is started.
	Begin(*Brr)

	// Write manages the log transformation.
	//
	// This function transforms the provided chunk into
	// the intermediate batching buffer in charge of the
	// flush valve.
	Write(brr *Brr, chunk Chunk, w io.Writer)

	// End is called just before the final flush.
	End(*Brr)

	// "Real" destination of the log stream.
	//
	// The log writes are flushed here at the most suitable
	// time to minimize memory use and I/O pressure due to
	// irregular writes typical for logging.
	Device() io.Writer

	// Max allowed time-to-flush for any given write.
	//
	// Returns negative if unlimited.
	TTF() time.Duration
}

Adapter is how motor interacts with the destination I/O.

type Brr

type Brr struct {
	// (Not unique) one of a kind name (ie. /endpoint)
	Namekind string

	// (Unique) context (request) identifier.
	Id string

	// Start time
	T0 time.Time
	// contains filtered or unexported fields
}

Brr is the procedural log context.

If constructed from Func or Gofunc, it will attempt to predict both the average log size and time to flush in order to utilize memory most efficiently.

func (*Brr) Debug

func (brr *Brr) Debug(mode ...bool) bool

If set to true, Debugf/ln writes will come through.

func (*Brr) Debugf

func (brr *Brr) Debugf(format string, a ...interface{})

Debugf is the debug mode Printf counterpart.

If the context is not debugging, this function will return false immediately without ever consulting the log buffer.

func (*Brr) Debugln

func (brr *Brr) Debugln(a ...interface{})

Debugln is the debug mode Println counterpart.

If the context is not debugging, this function will return false immediately without ever consulting the log buffer.

func (*Brr) Flush

func (brr *Brr) Flush()

Flush orders the final flush of the log buffer.

This function is called when there's no more work to be done per the existing context. All further writes will be ignored.

func (*Brr) Func

func (brr *Brr) Func(namekind, id string) *Brr

Func consructs a new motorised log.

This function will allocate a new log buffer according to the estimate of procedure demands known at the time of its creation.

Use consistent procedure names.

func (*Brr) Gofunc

func (brr *Brr) Gofunc(namekind, id string, f func(*Brr))

Gofunc constructs a new asynchronous context.

func (*Brr) Printf

func (brr *Brr) Printf(format string, a ...interface{})

Printf puts a fragment of a message into the log buffer.

func (*Brr) Println

func (brr *Brr) Println(a ...interface{})

Println puts a new message into the log buffer.

type Chunk

type Chunk struct {
	// Printf format string, if provided.
	Format string

	Args []interface{}
	// Named printf arguments (tags) list.
	Tags  []Tag
	Flags []Flag

	// True if the chunk is a debug write in itself.
	Debug bool
}

Chunk represents a single log write to the log buffer.

func (Chunk) Autowrite

func (c Chunk) Autowrite(w io.Writer)

Autowrite prints (and formats) chunk arguments.

func (Chunk) Flag

func (c Chunk) Flag(f Flag) bool

Flag returns true if chunk contains flag.

type Config

type Config struct {
	// If true, motor will let debug writes through.
	Debug bool

	// Motor can write into multiple devices simultaneously.
	//
	// For example, you can have human-readable formatted
	// messages end up in stdout, structured JSON log in
	// the dedicated log file, and have a seperate exhaust
	// reserved for metrics only.
	Sinks []Adapter
}

Config is a set of preferences required to start it.

type Example

type Example struct {
}

Example is a basic adapter with terminal formatting.

func (*Example) Begin

func (adp *Example) Begin(brr *Brr)

func (*Example) Device

func (adp *Example) Device() io.Writer

func (*Example) End

func (adp *Example) End(brr *Brr)

func (*Example) MaxLatency

func (adp *Example) MaxLatency() time.Duration

func (*Example) Write

func (adp *Example) Write(brr *Brr, c Chunk, w io.Writer)

type Flag

type Flag int

Flag allows for customization of chunks.

const (
	Error Flag = iota
	// Pretty yellow warning thing :-)
	Warn
	Trace
)

type Motor

type Motor struct {
	Brr
	// contains filtered or unexported fields
}

Motor is the global logger context.

All writes to it are performed immediately, as opposed to contextual writes which may be held up in a buffer until further flushes.

func New

func New(config Config) *Motor

New returns a new motor.

type Tag

type Tag struct {
	Pos   int
	Label string
}

Tag is a structured log element.

They are extracted from named format string operands supported by out printf implementation.

%(label)s, %(label)#+v

See: Brr.Printf()