{"id":37146962,"url":"https://github.com/distributedclocks/govector","last_synced_at":"2026-01-14T17:12:18.676Z","repository":{"id":25073294,"uuid":"28493652","full_name":"DistributedClocks/GoVector","owner":"DistributedClocks","description":"Vector clock logging library for Go","archived":false,"fork":false,"pushed_at":"2024-01-18T07:29:37.000Z","size":2577,"stargazers_count":182,"open_issues_count":15,"forks_count":35,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-11-17T12:27:43.776Z","etag":null,"topics":["distributed-systems","go","instrumentation","shiviz","vector-clock"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DistributedClocks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-12-25T23:29:16.000Z","updated_at":"2024-08-29T06:25:08.000Z","dependencies_parsed_at":"2024-06-18T14:41:38.250Z","dependency_job_id":null,"html_url":"https://github.com/DistributedClocks/GoVector","commit_stats":null,"previous_names":["arcaneiceman/govector"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/DistributedClocks/GoVector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DistributedClocks%2FGoVector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DistributedClocks%2FGoVector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DistributedClocks%2FGoVector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DistributedClocks%2FGoVector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DistributedClocks","download_url":"https://codeload.github.com/DistributedClocks/GoVector/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DistributedClocks%2FGoVector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28427203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T16:38:47.836Z","status":"ssl_error","status_checked_at":"2026-01-14T16:34:59.695Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["distributed-systems","go","instrumentation","shiviz","vector-clock"],"created_at":"2026-01-14T17:12:17.808Z","updated_at":"2026-01-14T17:12:18.663Z","avatar_url":"https://github.com/DistributedClocks.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"![GoVector.png](.images/GoVector.png)\n\n[![Build Status](https://travis-ci.com/DistributedClocks/GoVector.svg?branch=master)](https://travis-ci.com/DistributedClocks/GoVector)\n[![GoDoc](https://godoc.org/github.com/DistributedClocks/GoVector?status.svg)](https://godoc.org/github.com/DistributedClocks/GoVector)\n[![Go Report Card](https://goreportcard.com/badge/github.com/DistributedClocks/GoVector)](https://goreportcard.com/report/github.com/DistributedClocks/GoVector)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Coverage Status](https://img.shields.io/codecov/c/github/DistributedClocks/GoVector/master.svg)](https://codecov.io/gh/DistributedClocks/GoVector)\n\n\nGoVector is a vector clock logging library written in Go. The [vector\nclock algorithm](https://en.wikipedia.org/wiki/Vector_clock) is used\nto order events in distributed systems in the absence of a centralized\nclock. GoVector implements the vector clock algorithm and provides\nfeature-rich logging and encoding infrastructure. \n\nVector clock events\nare generated using 3 key functions, `PrepareSend`, `UnpackReceive`,\nand `LogLocalEvent`. `PrepareSend` encodes messages for network\ntransport, updates GoVectors local time, and logs a sending event.\n`UnpackReceive` decodes messages from the network, merges GoVectors local\nclock with the received clock, and logs a receiving event. `LogLocalEvent`\nevent ticks the clock, and logs a message.\n\nThis library can be added to a Go project to generate a\n[ShiViz](http://bestchai.bitbucket.io/shiviz/)-compatible vector-clock\ntimestamped log of events in a concurrent or distributed system.\nThis library can also be used to generate [TSViz](https://bestchai.bitbucket.io/tsviz/)-compatible\nlog of events.\nGoVector is compatible with Go 1.11+ and requires support for [Go modules](https://github.com/golang/go/wiki/Modules).\n\n* `govec/`    \t    : Contains the Library and all its dependencies\n* `govec/vclock`\t: Pure vector clock library\n* `govec/vrpc`\t    : Go's rpc with GoVector integration\n* `example/`  \t    : Contains some examples instrumented with different features of GoVector\n\n### Installation\n\nTo install GoVector you must have a correctly configured go development\nenvironment. See [How to Write Go\nCode](https://golang.org/doc/code.html).\n\nOnce you set up your environment, GoVector can be installed with the go\ntool command:\n\n```\n$ go install github.com/DistributedClocks/GoVector\n```\n\n### Usage\n\nThe following is a basic example of how this library can be used:\n\n```go\npackage main\n\nimport \"github.com/DistributedClocks/GoVector/govec\"\n\nfunc main() {\n    // Initialize GoVector logger\n    logger := govec.InitGoVector(\"MyProcess\", \"LogFile\", govec.GetDefaultConfig())\n\n    // Encode message, and update vector clock\n    messagePayload := []byte(\"sample-payload\")\n    vectorClockMessage := logger.PrepareSend(\"Sending Message\", messagePayload, govec.GetDefaultLogOptions())\n\n    // Send message\n    connection.Write(vectorClockMessage)\n\n    // In Receiving Process\n    connection.Read(vectorClockMessage)\n\n    // Decode message, and update local vector clock with received clock\n    logger.UnpackReceive(\"Receiving Message\", vectorClockMessage, \u0026messagePayload, govec.GetDefaultLogOptions())\n\n    // Log a local event\n    logger.LogLocalEvent(\"Example Complete\", govec.GetDefaultLogOptions())\n}\n```\nFor complete documentation with examples see GoVector's [GoDoc](https://godoc.org/github.com/DistributedClocks/GoVector/govec).\n\n### End-to-End Examples\n\n* Client-Server GoVector instrumentation [Examples/ClientServer.go](example/ClientServer/ClientServer.go)\n* RPC Client-Server program [Examples/RpcClientServer.go](example/RpcClientServer/RpcClientServer.go)\n* Message Broadcast via RPC Calls [Examples/RpcBroadcast.go](example/RpcBroadcast/RpcBroadcast.go)\n\n### Generating ShiViz/TSViz compatible logs\n\nBy 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.\n\n**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.\n\n#### Usage\n\nTo generate a ShiViz-compatible log file called `hello.log` from all log files in the directory `path/to/logs` do the following:\n\n```\n$ GoVector --log_type shiviz --log_dir path/to/logs --outfile hello.log\n```\n\nSimilarly, to generate a TSViz-compatible log file called `hello-ts.log` from all log files in the directory `path/to/logs` do the following:\n\n```\n$ GoVector --log_type tsviz --log_dir path/to/logs --outfile hello-ts.log\n```\n\n### Motivation\n\nGoVector 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](http://bestchai.bitbucket.io/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.\n\nEventually, as a result of student requests, GoVector has been transformed into a general-purpose logging tool. Additional features include optimized IO, priority logging, [TSViz](https://bestchai.bitbucket.io/tsviz/) compatibility, and RPC instrumentation (including support for message broadcast via RPC calls).\n\n### Dependencies\n\nGoVector has the following dependencies: \n\n+ [msgpack](https://github.com/vmihailenco/msgpack)\n+ [go-colortext](https://github.com/daviddengcn/go-colortext)\n\n### Contributors\n\n+ Ivan Beschastnikh\n+ Mike Fink\n+ Stewart Grant\n+ Clement Fung\n+ Fabian Ruffy\n+ Vaastav Anand\n+ Sasha Avreline\n+ Shayan Hosseini (Maintainer)\n\n### Output Example\n\nThe source code from the usage example produces the following log into a file named \"LogFile.txt\":\n\n```\nMyProcess {\"MyProcess\":1}\nInitialization Complete\nMyProcess {\"MyProcess\":2}\nSending Message\nMyProcess {\"MyProcess\":3}\nReceiving Message\nMyProcess {\"MyProcess\":4}\nExample Complete\n```\n\nHere is a sample output of the priority logger:\n![PriorityLoggerOutput.png](.images/PriorityLoggerOutput.png)\n\nHere is an example of ShiViz output generated by an RPC client server\ninteraction:\n![ShivizExample.png](.images/shiviz_output.png)\n\n[Here](.images/shiviz_broadcast.png) is an example of ShiViz output generated by broadcasting a message\nto three servers via RPC calls.\n\n\u003c!-- July 2017: Brokers are no longer supported, maybe they will come back.\n\n### VectorBroker\n\ntype VectorBroker\n   * func Init(logfilename string, pubport string, subport string)\n\n### Usage\n\n    A simple stand-alone program can be found in server/broker/runbroker.go \n    which will setup a broker with command line parameters.\n   \tUsage is: \n    \"go run ./runbroker (-logpath logpath) -pubport pubport -subport subport\"\n\n    Tests can be run via GoVector/test/broker_test.go and \"go test\" with the \n    Go-Check package (https://labix.org/gocheck). To get this package use \n    \"go get gopkg.in/check.v1\".\n    \nDetailed Setup:\n\nStep 1:\n\n    Create a Global Variable of type brokervec.VectorBroker and Initialize \n    it like this =\n\n    broker.Init(logpath, pubport, subport)\n    \n    Where:\n    - the logpath is the path and name of the log file you want created, or \n    \"\" if no log file is wanted. E.g. \"C:/temp/test\" will result in the file \n    \"C:/temp/test-log.txt\" being created.\n    - the pubport is the port you want to be open for publishers to send\n    messages to the broker.\n    - the subport is the port you want to be open for subscribers to receive \n    messages from the broker.\n\nStep 2:\n\n    Setup your GoVec so that the real-time boolean is set to true and the correct\n    brokeraddr and brokerpubport values are set in the Initialize method you\n    intend to use.\n\nStep 3 (optional):\n\n    Setup a Subscriber to connect to the broker via a WebSocket over the correct\n    subport. For example, setup a web browser running JavaScript to connect and\n    display messages as they are received. Make RPC calls by sending a JSON \n    object of the form:\n            var msg = {\n            method: \"SubManager.AddFilter\", \n            params: [{\"Nonce\":nonce, \"Regex\":regex}], \n            id: 0\n            }\n            var text = JSON.stringify(msg)\n\n####   RPC Calls\n\n    Publisher RPC calls are made automatically from the GoVec library if the \n    broker is enabled.\n    \n    Subscriber RPC calls:\n    * AddNetworkFilter(nonce string, reply *string)\n        Filters messages so that only network messages are sent to the \n        subscriber.      \n    * RemoveNetworkFilter(nonce string, reply *string)\n        Filters messages so that both network and local messages are sent to the \n        subscriber.\n    * SendOldMessages(nonce string, reply *string)\n        Sends any messages received before the requesting subscriber subscribed.\n  --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdistributedclocks%2Fgovector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdistributedclocks%2Fgovector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdistributedclocks%2Fgovector/lists"}