govec

Documentation

Overview

Package govec is a vector clock logging library

Index

• type GoLog
  • func InitGoVector(processid string, logfilename string, config GoLogConfig) *GoLog
  • func (gv *GoLog) DisableBufferedWrites()
  • func (gv *GoLog) EnableBufferedWrites()
  • func (gv *GoLog) Flush() bool
  • func (gv *GoLog) GetCurrentVC() vclock.VClock
  • func (gv *GoLog) GetCurrentVCSafe() vclock.VClock
  • func (gv *GoLog) LogLocalEvent(LogMessage string, opts GoLogOptions) vclock.VClock
  • func (gv *GoLog) MergeIncomingClock(mesg string, clock vclock.VClock, Priority LogPriority)
  • func (gv *GoLog) PrepareSend(mesg string, buf interface{}, opts GoLogOptions) (encodedBytes []byte)
  • func (gv *GoLog) StartBroadcast(msg string, opts GoLogOptions) vclock.VClock
  • func (gv *GoLog) StopBroadcast()
  • func (gv *GoLog) UnpackReceive(mesg string, buf []byte, unpack interface{}, opts GoLogOptions)
• type GoLogConfig
  • func GetDefaultConfig() GoLogConfig
• type GoLogOptions
  • func GetDefaultLogOptions() GoLogOptions
  • func (o *GoLogOptions) SetPriority(Priority LogPriority) GoLogOptions
• type LogPriority
• type VClockPayload
  • func (d *VClockPayload) DecodeMsgpack(dec *msgpack.Decoder) error
  • func (d *VClockPayload) EncodeMsgpack(enc *msgpack.Encoder) error
  • func (d *VClockPayload) PrintDataBytes()
  • func (d *VClockPayload) String() (s string)

Examples

• GoLog (Basic)
• GoLog (Priority)
• GoLog (TSVizCompatable)

Types

type GoLog

type GoLog struct {
	// contains filtered or unexported fields
}

The GoLog struct provides an interface to creating and maintaining vector timestamp entries in the generated log file. GoLogs are initialized with Configs which control logger output, format, and frequency.

Example (Basic)

Basic example of GoVectors key functions

package main

import (
	"fmt"

	"github.com/savreline/GoVector/govec"
)

func main() {
	//Initialize logger with default configuration. This can be done in
	//a var block to ensure that GoVector is initialized at boot time.
	Logger := govec.InitGoVector("MyProcess", "LogFile", govec.GetDefaultConfig())
	opts := govec.GetDefaultLogOptions()

	//An example message
	messagepayload := []byte("samplepayload")

	//Prior to sending a message, call PrepareSend on the payload to
	//encode the payload and append this processes vector clock to the
	//payload
	encodedVCpayload := Logger.PrepareSend("Sending Message", messagepayload, opts)

	//encodedVCpayload is ready to be written to the network
	//ex) conn.Write(encodedVCpayload)

	//Receiving Example
	//First allocate a buffer to receive a message into. This must be
	//the same type as the encoded message. Here incommingMessage and
	//messagepayload are the same type []byte.
	var incommingMessage []byte

	//Prior to unpacking call a message must be received
	//ex) conn.Read(encodedVCPayload)

	//Call UnpackReceive on received messages to update local vector
	//clock values, and decode the original message.
	Logger.UnpackReceive("Received Message from server", encodedVCpayload, &incommingMessage, opts)
	fmt.Printf("Received Message: %s\n", incommingMessage)

	//Important local events can be timestamped with vector clocks
	//using LogLocalEvent, which also increments the local clock.
	Logger.LogLocalEvent("Example Complete", opts)

}

Output:

Received Message: samplepayload

Example (Priority)

Logging with priority trims all events which are lower from the specified priority from the log. This functionality is useful for isolating behaviour such as recovery protocols, from common behaviour like heartbeats.

package main

import (
	"github.com/savreline/GoVector/govec"
)

func main() {
	//Access GoVectors default configureation, and set priority
	config := govec.GetDefaultConfig()
	config.Priority = govec.DEBUG
	config.PrintOnScreen = true
	//Initialize GoVector
	Logger := govec.InitGoVector("MyProcess", "PrioritisedLogFile", config)
	opts := govec.GetDefaultLogOptions()

	Logger.LogLocalEvent("Debug Priority Event", opts.SetPriority(govec.DEBUG))
	Logger.LogLocalEvent("Info Priority Event", opts.SetPriority(govec.INFO))
	Logger.LogLocalEvent("Warning Priority Event", opts.SetPriority(govec.WARNING))
	Logger.LogLocalEvent("Error Priority Event", opts.SetPriority(govec.ERROR))
	Logger.LogLocalEvent("Fatal Priority Event", opts.SetPriority(govec.FATAL))

	//BUG Output contains timestamps so it cant be tested with *******
	//comments
	//Debug Priority Event
	//Info Priority Event
	//Warning Priority Event
	//Error Priority Event
	//Fatal Priority Event
}

Example (TSVizCompatable)

GoVector logs can be used to associate real time events for visualization with TSViz

package main

import (
	"fmt"

	"github.com/savreline/GoVector/govec"
)

func main() {
	//Access config and set timestamps (realtime) to true
	config := govec.GetDefaultConfig()
	config.UseTimestamps = true
	//Initalize GoVector
	Logger := govec.InitGoVector("MyProcess", "LogFile", config)
	opts := govec.GetDefaultLogOptions()

	//In Sending Process

	//Prepare a Message
	messagepayload := []byte("samplepayload")
	finalsend := Logger.PrepareSend("Sending Message", messagepayload, opts)
	//In Receiving Process

	//receive message
	var incommingMessage []byte
	Logger.UnpackReceive("Received Message from server", finalsend, &incommingMessage, opts)
	fmt.Printf("Received Message: %s\n", incommingMessage)
	//Can be called at any point
	Logger.LogLocalEvent("Example Complete", opts)

}

Output:

Received Message: samplepayload

func InitGoVector

func InitGoVector(processid string, logfilename string, config GoLogConfig) *GoLog

InitGoVector returns a GoLog which generates a logs prefixed with processid, to a file name logfilename.log. Any old log with the same name will be trucated. Config controls logging options. See GoLogConfig for more details.

func (*GoLog) DisableBufferedWrites

func (gv *GoLog) DisableBufferedWrites()

DisableBufferedWrites disables buffered writes to the log file. All the log messages from now on will be written to the Log file immediately. Writes all the existing log messages that haven't been written to Log file yet.

func (*GoLog) EnableBufferedWrites

func (gv *GoLog) EnableBufferedWrites()

EnableBufferedWrites enables buffered writes to the log file. All the log messages are only written to the LogFile via an explicit call to the function Flush. Note: Buffered writes are automatically disabled.

func (*GoLog) Flush

func (gv *GoLog) Flush() bool

Flush writes the log messages stored in the buffer to the Log File. This function should be used by the application to also force writes in the case of interrupts and crashes. Note: Calling Flush when BufferedWrites is disabled is essentially a no-op.

func (*GoLog) GetCurrentVC

func (gv *GoLog) GetCurrentVC() vclock.VClock

GetCurrentVC returns the current vector clock

func (*GoLog) GetCurrentVCSafe

func (gv *GoLog) GetCurrentVCSafe() vclock.VClock

GetCurrentVCSafe returns the current vector clock in a thread-safe way

func (*GoLog) LogLocalEvent

func (gv *GoLog) LogLocalEvent(LogMessage string, opts GoLogOptions) vclock.VClock

LogLocalEvent implements LogLocalEvent with priority levels. If the priority of the logger is lower than or equal to the priority of this event then the current vector timestamp is incremented and the message is logged it into the Log File. A color coded string is also printed on the console. * LogMessage (string) : Message to be logged * Priority (LogPriority) : Priority at which the message is to be logged

func (*GoLog) MergeIncomingClock

func (gv *GoLog) MergeIncomingClock(mesg string, clock vclock.VClock, Priority LogPriority)

MergeIncomingClock merges incoming clock

func (*GoLog) PrepareSend

func (gv *GoLog) PrepareSend(mesg string, buf interface{}, opts GoLogOptions) (encodedBytes []byte)

PrepareSend is meant to be used immediately before sending. LogMessage will be logged along with the time of the send buf is encode-able data (structure or basic type) Returned is an encoded byte array with logging information.

This function is meant to be called before sending a packet. Usually, it should Update the Vector Clock for its own process, package with the clock using gob support and return the new byte array that should be sent onwards using the Send Command

func (*GoLog) StartBroadcast

func (gv *GoLog) StartBroadcast(msg string, opts GoLogOptions) vclock.VClock

StartBroadcast is called just prior to starting RPC broadcast Log a "local event" and flip the broadcast flag to true

func (*GoLog) StopBroadcast

func (gv *GoLog) StopBroadcast()

StopBroadcast is called once RPC broadcast is done Flip the broadcast flag back to false

func (*GoLog) UnpackReceive

func (gv *GoLog) UnpackReceive(mesg string, buf []byte, unpack interface{}, opts GoLogOptions)

UnpackReceive is used to unmarshall network data into local structures. LogMessage will be logged along with the vector time the receive happened buf is the network data, previously packaged by PrepareSend unpack is a pointer to a structure, the same as was packed by PrepareSend

This function is meant to be called immediately after receiving a packet. It unpacks the data by the program, the vector clock. It updates vector clock and logs it. and returns the user data

type GoLogConfig

type GoLogConfig struct {
	//If true logging events are buffered until flushed. This option
	//increase logging performance at the cost of safety.
	Buffered bool
	//Logging events are printed to screen
	PrintOnScreen bool
	//Continue writing to a log from a prior execution
	AppendLog bool
	//Log real time timestamps for TSVis
	UseTimestamps bool
	//Encoding and decoding strateges for customizable
	//interoperability
	EncodingStrategy func(interface{}) ([]byte, error)
	DecodingStrategy func([]byte, interface{}) error
	//Write logging events to a file
	LogToFile bool
	//The minimum priority event to log
	Priority LogPriority
}

GoLogConfig controls the logging parameters of GoLog and is taken as input to GoLog initialization. See defaults in GetDefaultsConfig

func GetDefaultConfig

func GetDefaultConfig() GoLogConfig

GetDefaultConfig returns the default GoLogConfig with default values for various fields.

type GoLogOptions

type GoLogOptions struct {
	// The Log priority for this event
	Priority LogPriority
}

GoLogOptions provides logging parameters for individual logging statements

func GetDefaultLogOptions

func GetDefaultLogOptions() GoLogOptions

GetDefaultLogOptions returns the default GoLogOptions with default values for the fields

func (*GoLogOptions) SetPriority

func (o *GoLogOptions) SetPriority(Priority LogPriority) GoLogOptions

SetPriority returns a new GoLogOptions object with its priority field set to Priority. Follows the builder pattern. Priority : (GoLogPriority) The Priority that the new GoLogOptions object must have

type LogPriority

type LogPriority int

LogPriority controls the minimum priority of logging events which will be logged.

const (
	DEBUG LogPriority = iota
	INFO
	WARNING
	ERROR
	FATAL
)

LogPriority enum provides all the valid Priority Levels that can be used to log events with.

type VClockPayload

type VClockPayload struct {
	Pid     string
	VcMap   map[string]uint64
	Payload interface{}
}

VClockPayload is the data structure that is actually end on the wire

func (*VClockPayload) DecodeMsgpack

func (d *VClockPayload) DecodeMsgpack(dec *msgpack.Decoder) error

DecodeMsgpack is a custom decoder function, needed for msgpack interoperability

func (*VClockPayload) EncodeMsgpack

func (d *VClockPayload) EncodeMsgpack(enc *msgpack.Encoder) error

EncodeMsgpack is a custom encoder function, needed for msgpack interoperability

func (*VClockPayload) PrintDataBytes

func (d *VClockPayload) PrintDataBytes()

PrintDataBytes prints the Data Stuct as Bytes

func (*VClockPayload) String

func (d *VClockPayload) String() (s string)

String returns VClockPayload's pid as a string