{"id":15914353,"url":"https://github.com/bbengfort/orca","last_synced_at":"2026-01-20T13:08:36.027Z","repository":{"id":57551324,"uuid":"70818229","full_name":"bbengfort/orca","owner":"bbengfort","description":"Echolocation of device with static nodes and network latency. ","archived":false,"fork":false,"pushed_at":"2016-11-02T12:10:39.000Z","size":3143,"stargazers_count":3,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-07T15:47:14.527Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/bbengfort.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}},"created_at":"2016-10-13T15:00:47.000Z","updated_at":"2019-09-24T07:32:46.000Z","dependencies_parsed_at":"2022-09-26T18:41:23.269Z","dependency_job_id":null,"html_url":"https://github.com/bbengfort/orca","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/bbengfort/orca","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbengfort%2Forca","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbengfort%2Forca/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbengfort%2Forca/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbengfort%2Forca/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbengfort","download_url":"https://codeload.github.com/bbengfort/orca/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbengfort%2Forca/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28603437,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T12:01:53.233Z","status":"ssl_error","status_checked_at":"2026-01-20T12:01:46.545Z","response_time":117,"last_error":"SSL_read: 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":[],"created_at":"2024-10-06T17:01:52.654Z","updated_at":"2026-01-20T13:08:36.009Z","avatar_url":"https://github.com/bbengfort.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Orca\n\n[![Build Status](https://travis-ci.org/bbengfort/orca.svg?branch=master)](https://travis-ci.org/bbengfort/orca)\n[![Coverage Status](https://coveralls.io/repos/github/bbengfort/orca/badge.svg?branch=master)](https://coveralls.io/github/bbengfort/orca?branch=master)\n[![GoDoc Reference](https://godoc.org/github.com/bbengfort/orca?status.svg)](https://godoc.org/github.com/bbengfort/orca)\n[![Go Report Card](https://goreportcard.com/badge/github.com/bbengfort/orca)](https://goreportcard.com/report/github.com/bbengfort/orca)\n[![Stories in Ready](https://badge.waffle.io/bbengfort/orca.png?label=ready\u0026title=Ready)](https://waffle.io/bbengfort/orca)\n\n**Echolocation of device with static nodes and network latency.*\n\n[![Orca][orca.jpg]][orca_flickr]\n\nOrca is a reflector/ping generator service that is intended to measure network latency of gRPC requests from mobile devices (laptops) to storage locations in home and work networks. Orca was built to get some baseline metrics for latencies in distributed storage systems and is purely experimental, not intended for large scale use.\n\nOrca specifies two primary commands: _reflect_ and _generate_. The reflector is a Protocol Buffers service that accepts echo requests and returns replies. The generator is a service that sends a request to all known reflectors on a routine interval and logs the latency in a SQLite database.\n\n## Installation\n\nIn order to install Orca and get it running on your system, you have two options: build from source or download a prebuilt binary that may or may not exist for your system.\n\nTo download the prebuilt binary, visit the [Current Release](#) on GitHub and download the executable for your system. Extract the archive to reveal the executable, and put it on your path, making sure it has executable permissions.\n\nNote: currently only Linux x64 and OS X (darwin) x64 binaries are prebuilt. My preference for path location is `$HOME/bin` but make sure that location is in your path. Otherwise, `/usr/local/bin` is a good choice for moving the binary to.\n\nTo build from source, make sure you have your Go environment setup and run:\n\n```\n$ go get github.com/bbengfort/orca/...\n```\n\nYou can then use `go install` to install the binary to `$GOBIN` as follows:\n\n```\n$ go install cmd/orca.go\n```\n\nTo contribute or modify the orca command, you'll want to go the source route; otherwise if you are using Linux or OS X, I recommend going the binary route. If there is an architecture that you'd like prebuilt, please let me know in a GitHub issue.\n\n## Getting Started\n\nOnce installed, some configuration is necessary. This is the recommended configuration, though other configuration options are available and can be inspected via the `orca help` command.\n\n1. Create the directory where configuration and data will reside:\n\n        $ mkdir ~/.orca\n\n2. Copy the example configuration file to the orca directory\n\n        $ cp fixtures/orca-config-example.yml ~/.orca/config.yml\n\n    Note that the first path refers to the fixtures directory inside of the\n    GitHub repository. If you downloaded the binary package from the releases page, then the example configuration will be in the archive you downloaded.\n\n3. Edit the configuration as needed, noting the defaults and comments in the example configuration file.\n\n4. Create the orca SQLite database used to track meta information about reflection and generators.\n\n        $ orca createdb\n\nAt this point orca is configured to begin reflecting, however generators require an extra configuration step.\n\n### Relectors\n\nRunning orca as a reflector runs a gRPC service that listens for echo requests on the current IP address and port, increments the request sequence (to detect out of order messages), and responds with an echo reply. This process means that there is a small database transaction before reply, so latency will not be exactly the same as using the `ping` utility. If `debug: true` in the configuration, then the server will also log all incoming echo requests to `stdout`, which can be redirected to a log file if required.\n\nRun the reflector as follows:\n\n```\n$ orca reflect\n```\n\nTo run in the background on a constant server:\n\n```\n$ nohup orca reflect \u0026\n```\n\nUpstart and LaunchAgent scripts for managing the background process are forthcoming, though I'd be happy to accept a pull request for them!\n\n### Generators\n\nGenerators require a bit more configuration, since you'll have to add all of the reflectors that you want the generator to ping to the database. Do this via the `orca devices --add` command:\n\n```\n$ orca devices --add\nEnter device name []: rogue\nEnter device IP address []: 1.2.3.4:3265\nEnter device domain []:\n```\n\nDo this for as many devices as you'd like to ping on each interval. To see the devices already added use `orca devices --list`. Run the generator as follows:\n\n```\n$ orca generate\n```\n\nSimilar to the reflector, you'll have to nohup and background this in order to ensure it always runs. LaunchAgent and Upstart scripts are coming soon. The generator waits until the interval has passed, loads up the list of devices to ping, and sends an echo request to them, recording the request (in the case of non-connectivity) and sequence number in the database. On receipt of the reply, it measures latency and stores the information in the database.\n\n## Location Servicesd\n\nOrca can provide location services for mobile devices via the [MaxMind GeoIP2 Precision City Service](https://www.maxmind.com/en/geoip2-precision-city-service). In order to enable location services, you need to register for a MaxMind developer account and include your API user id and license key in the YAML configuration file. Because MaxMind is a paid service, location lookups are only made when the current IP address of the machine changes.\n\nNote also that the granularity for this service is limited; for example, a GeoIP2 lookup from my office in the A.V. Williams Building of the University of Maryland yielded the following location via latitude and longitude:\n\n![Map Granularity](fixtures/map.png)\n\nThis location is not centered on my office, the building, or even in the center of the university. The level of granularity probably differs based on the type of network you're connected to. If a higher level of granularity is required, then the use of GPS is recommended. Additional location inaccuracy can come about when tethering to a mobile phone. Use specified locations with care!\n\n## Acknowledgements\n\nOrca is an open source project built to obtain metrics about mobile distributed systems and various latencies. If you'd like to contribute, I'd love some help, but no current plans are underway for future development.\n\n### Attribution\n\nThe photo used in this README, \u0026ldquo;[Orca (Design Exploration)][orca_flickr]\u0026rdquo; by [Alberto Cerriteño](https://www.flickr.com/photos/acerriteno/) is used under a [CC BY-NC-ND 2.0](https://creativecommons.org/licenses/by-nc-nd/2.0/) creative commons license.\n\n[orca.jpg]: fixtures/orca.jpg\n[orca_flickr]: https://flic.kr/p/4HDnoE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbengfort%2Forca","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbengfort%2Forca","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbengfort%2Forca/lists"}