GoVector is a vector clock logging library written in Go. The vector
clock algorithm is used
to order events in distributed systems in the absence of a centralized
clock. GoVector implements the vector clock algorithm and provides
feature-rich logging and encoding infrastructure.
Vector clock events
are generated using 3 key functions, PrepareSend
, UnpackReceive
,
and LogLocalEvent
. PrepareSend
encodes messages for network
transport, updates GoVectors local time, and logs a sending event.
UnpackReceive
decodes messages from the network, merges GoVectors local
clock with the received clock, and logs a receiving event. LogLocalEvent
event ticks the clock, and logs a message.
This library can be added to a Go project to generate a
ShiViz-compatible vector-clock
timestamped log of events in a concurrent or distributed system.
This library can also be used to generate TSViz-compatible
log of events.
GoVector is compatible with Go 1.11+ and requires support for Go modules.
govec/
: Contains the Library and all its dependencies
govec/vclock
: Pure vector clock library
govec/vrpc
: Go's rpc with GoVector integration
example/
: Contains some examples instrumented with different features of GoVector
Installation
To install GoVector you must have a correctly configured go development
environment. See How to Write Go
Code.
Once you set up your environment, GoVector can be installed with the go
tool command:
$ go install github.com/DistributedClocks/GoVector
Usage
The following is a basic example of how this library can be used:
package main
import "github.com/DistributedClocks/GoVector/govec"
func main() {
// Initialize GoVector logger
logger := govec.InitGoVector("MyProcess", "LogFile", govec.GetDefaultConfig())
// Encode message, and update vector clock
messagePayload := []byte("sample-payload")
vectorClockMessage := logger.PrepareSend("Sending Message", messagePayload, govec.GetDefaultLogOptions())
// Send message
connection.Write(vectorClockMessage)
// In Receiving Process
connection.Read(vectorClockMessage)
// Decode message, and update local vector clock with received clock
logger.UnpackReceive("Receiving Message", vectorClockMessage, &messagePayload, govec.GetDefaultLogOptions())
// Log a local event
logger.LogLocalEvent("Example Complete", govec.GetDefaultLogOptions())
}
For complete documentation with examples see GoVector's GoDoc.
End-to-End Examples
Generating ShiViz/TSViz compatible logs
By default, when you download the GoVector package using the go get command, the command installs a binary of the to-level file govec.go
by the name of GoVector in the directory $GOPATH/bin
. As long as this directory is part of your path, you can run the GoVector binary to generate a ShiViz or TSViz compatible log from all the logs in a given directory.
Note: Make sure that you are running the GoVector binary on a directory that contains log files from the same execution of the system. If it contains logs from multiple executions, then ShiViz and TSViz won't be able to interpret the log file.
Usage
To generate a ShiViz-compatible log file called hello.log
from all log files in the directory path/to/logs
do the following:
$ GoVector --log_type shiviz --log_dir path/to/logs --outfile hello.log
Similarly, to generate a TSViz-compatible log file called hello-ts.log
from all log files in the directory path/to/logs
do the following:
$ GoVector --log_type tsviz --log_dir path/to/logs --outfile hello-ts.log
Motivation
GoVector was initially developed as a pedagogical tool for UBC's computer science course on distributed systems (CPSC 416). Students new to the development of distributed systems can feed generated logs into ShiViz to visualize their program executions and reason about event orderings. Furthermore, GoVector's marshaling functionality reduces the effort needed to write networking code that is largely boilerplate.
Eventually, as a result of student requests, GoVector has been transformed into a general-purpose logging tool. Additional features include optimized IO, priority logging, TSViz compatibility, and RPC instrumentation (including support for message broadcast via RPC calls).
Dependencies
GoVector has the following dependencies:
Contributors
- Ivan Beschastnikh
- Mike Fink
- Stewart Grant
- Clement Fung
- Fabian Ruffy
- Vaastav Anand
- Sasha Avreline
- Shayan Hosseini (Maintainer)
Output Example
The source code from the usage example produces the following log into a file named "LogFile.txt":
MyProcess {"MyProcess":1}
Initialization Complete
MyProcess {"MyProcess":2}
Sending Message
MyProcess {"MyProcess":3}
Receiving Message
MyProcess {"MyProcess":4}
Example Complete
Here is a sample output of the priority logger:
Here is an example of ShiViz output generated by an RPC client server
interaction:
Here is an example of ShiViz output generated by broadcasting a message
to three servers via RPC calls.