{"id":13797826,"url":"https://github.com/thevxn/dish","last_synced_at":"2025-05-04T15:32:30.456Z","repository":{"id":129064049,"uuid":"468033120","full_name":"thevxn/dish","owner":"thevxn","description":"A lightweight monitoring service that efficiently checks socket connections and can be configured remotely.","archived":false,"fork":false,"pushed_at":"2025-05-02T18:26:26.000Z","size":6690,"stargazers_count":191,"open_issues_count":6,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-02T18:27:24.965Z","etag":null,"topics":["alerting","docker-compose","go","golang","monitoring","monitoring-automation","monitoring-systems","monitoring-tool","networking","telegram"],"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/thevxn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2022-03-09T17:44:33.000Z","updated_at":"2025-05-02T18:24:44.000Z","dependencies_parsed_at":"2024-01-21T16:05:43.925Z","dependency_job_id":"43d5be81-7398-4f44-a5a9-8b57058262eb","html_url":"https://github.com/thevxn/dish","commit_stats":null,"previous_names":["savla-dev/savla-dish","thevxn/dish","savla-dev/dish"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thevxn%2Fdish","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thevxn%2Fdish/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thevxn%2Fdish/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thevxn%2Fdish/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thevxn","download_url":"https://codeload.github.com/thevxn/dish/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252090144,"owners_count":21693106,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["alerting","docker-compose","go","golang","monitoring","monitoring-automation","monitoring-systems","monitoring-tool","networking","telegram"],"created_at":"2024-08-04T00:00:33.861Z","updated_at":"2025-05-04T15:32:30.445Z","avatar_url":"https://github.com/thevxn.png","language":"Go","funding_links":[],"categories":["Software Packages","Opensource","Network","Go","软件包","\u003ca name=\"networking\"\u003e\u003c/a\u003eNetworking","Go Tools"],"sub_categories":["DevOps Tools","DevOps 工具"],"readme":"\u003ch1 align=\"left\"\u003e\n\u003cimg alt=\"dish_logo\" src=\"https://vxn.dev/logos/dish_no_bg.svg\" width=\"90\" height=\"90\"\u003e\ndish\n\u003c/h1\u003e\n\n[![PkgGoDev](https://pkg.go.dev/badge/go.vxn.dev/dish)](https://pkg.go.dev/go.vxn.dev/dish)\n[![Go Report Card](https://goreportcard.com/badge/go.vxn.dev/dish)](https://goreportcard.com/report/go.vxn.dev/dish)\n[![libs.tech recommends](https://libs.tech/project/468033120/badge.svg)](https://libs.tech/project/468033120/dish)\n\n+ __Tiny__ one-shot monitoring service\n+ __Remote__ configuration of independent 'dish network' (via loading the socket list to be checked from a remote API)\n+ __Fast__ concurrent testing, low overall execution time, 10-sec timeout per socket by default\n+ __Zero__ dependencies\n\n## Use Cases\n\n+ Lightweight health checks of HTTP and/or TCP sockets\n+ Decentralized monitoring with standalone dish instances deployed on different hosts that pull configuration from a common API\n+ Cron-driven one-shot checks without the need for any long-running agents\n\n## Install\n\n### Using go install\n\n```shell\ngo install go.vxn.dev/dish/cmd/dish@latest\n```\n\n### Using Homebrew\n\n```shell\nbrew install dish\n```\n\n### Manual Download\n\nDownload the binary built for your OS and architecture from the [Releases](https://github.com/thevxn/dish/releases) section.\n\n## Usage\n\n```\ndish [FLAGS] SOURCE\n```\n\n![dish run](.github/dish_run.png)\n\n### Source\n\nThe list of sockets to be checked can be provided in 2 ways:\n\n1. A local JSON file\n   + E.g., the `./configs/demo_sockets.json` file included in this repository as an example.\n2. A remote RESTful JSON API endpoint\n   + The list of sockets retrieved from this endpoint can also be locally cached (see the `-cache`, `-cacheDir` and `-cacheTTL` flags below).\n   + Using local cache prevents constant hitting of the endpoint when running checks in short, periodic intervals. It also enables dish to run its checks even if the remote endpoint is down using the cached list of sockets (if available), even when the cache is considered expired.\n\nFor the expected JSON schema of the list of sockets to be checked, see `./configs/demo_sockets.json`.\n\n```bash\n# local JSON file\ndish /opt/dish/sockets.json\n\n# remote JSON API source\ndish http://restapi.example.com/dish/sockets/:instance\n```\n\n### Flags\n\n```\ndish -h\nUsage of dish:\n  -cache\n        a bool, specifies whether to cache the socket list fetched from the remote API source\n  -cacheDir string\n        a string, specifies the directory used to cache the socket list fetched from the remote API source (default \".cache\")\n  -cacheTTL uint\n        an int, time duration (in minutes) for which the cached list of sockets is valid (default 10)\n  -hname string\n        a string, name of a custom additional header to be used when fetching and pushing results to the remote API (used mainly for auth purposes)\n  -hvalue string\n        a string, value of the custom additional header to be used when fetching and pushing results to the remote API (used mainly for auth purposes)\n  -machineNotifySuccess\n        a bool, specifies whether successful checks with no failures should be reported to machine channels\n  -name string\n        a string, dish instance name (default \"generic-dish\")\n  -target string\n        a string, result update path/URL to pushgateway, plaintext/byte output\n  -telegramBotToken string\n        a string, Telegram bot private token\n  -telegramChatID string\n        a string, Telegram chat/channel ID\n  -textNotifySuccess\n        a bool, specifies whether successful checks with no failures should be reported to text channels\n  -timeout uint\n        an int, timeout in seconds for http and tcp calls (default 10)\n  -updateURL string\n        a string, API endpoint URL for pushing results\n  -verbose\n        a bool, console stdout logging toggle\n  -webhookURL string\n        a string, URL of webhook endpoint\n```\n\n### Alerting\n\nWhen a socket test fails, it's always good to be notified. For this purpose, dish provides 4 different ways of doing so (can be combined):\n\n+ Test results upload to a remote JSON API (using the `-updateURL` flag)\n+ Check results as the Telegram message body (via the `-telegramBotToken` and `-telegramChatID` flags)\n+ Failed count and last test timestamp update to Pushgateway for Prometheus (using the `-target` flag)\n+ Test results push to a webhook URL (using the `-webhookURL` flag)\n\nWhether successful runs with no failed checks should be reported can also be configured using flags:\n\n+ `-textNotifySuccess` for text channels (e.g. Telegram)\n+ `-machineNotifySuccess` for machine channels (e.g. webhooks, remote API or Pushgateway)\n\n![telegram-alerting](/.github/dish_telegram.png)\n\n(The screenshot above shows Telegram alerting as of `v1.10.0`. The screenshot shows the result of using the `-textNotifySuccess` flag to include successful checks in the alert as well.)\n\n### Examples\n\nOne way to run dish is to build and install a binary executable.\n\n```shell\n# Fetch and install the specific version\ngo install go.vxn.dev/dish/cmd/dish@latest\n\nexport PATH=$PATH:~/go/bin\n\n# Load sockets from sockets.json file, and use Telegram \n# provider for alerting\ndish -telegramChatID \"-123456789\" \\\n -telegramBotToken \"123:AAAbcD_ef\" \\\n sockets.json\n\n# Use remote JSON API service as socket source, and push\n# the results to Pushgateway\ndish -target https://pushgw.example.com/ \\\n https://api.example.com/dish/sockets\n```\n\n#### Using Docker\n\n```shell\n# Copy, and/or edit dot-env file (optional)\ncp .env.example .env\nvi .env\n\n# Build a Docker image\nmake build\n\n# Run using docker compose stack\nmake run\n\n# Run using native docker run\ndocker run --rm \\\n dish:1.10.4-go1.24 \\\n -verbose \\\n -target https://pushgateway.example.com \\\n https://api.example.com\n```\n\n#### Bash script and cronjob\n\nCreate a bash script to easily deploy dish and update its settings:\n\n```shell\nvi tiny-dish-run.sh\n```\n\n```shell\n#!/bin/bash\n\nTELEGRAM_TOKEN=\"123:AAAbcD_ef\"\nTELEGRAM_CHATID=\"-123456789\"\n\nSOURCE_URL=https://api.example.com/dish/sockets\nUPDATE_URL=https://api.example.com/dish/sockets/results\nTARGET_URL=https://pushgw.example.com\n\nDISH_TAG=dish:1.10.4-go1.24\nINSTANCE_NAME=tiny-dish\n\nAPI_TOKEN=AbCd\n\ndocker run --rm \\\n        ${DISH_TAG} \\\n        -name ${INSTANCE_NAME} \\\n        -hvalue ${API_TOKEN} \\\n        -hname X-Auth-Token \\\n        -target ${TARGET_URL} \\\n        -updateURL ${UPDATE_URL} \\\n        -telegramBotToken ${TELEGRAM_TOKEN} \\\n        -telegramChatID ${TELEGRAM_CHATID} \\\n        -timeout 15 \\\n        -verbose \\\n        ${SOURCE_URL}\n```\n\nMake it an executable:\n\n```shell\nchmod +x tiny-dish-run.sh\n```\n\n##### Cronjob to run periodically\n\n```shell\ncrontab -e\n```\n\n```shell\n# m h  dom mon dow   command\nMAILTO=monitoring@example.com\n\n*/2 * * * * /home/user/tiny-dish-run.sh\n```\n\n### Integration Example\n\nFor an example of what can be built using dish integrated with a remote API, you can check out our [status page](https://status.vxn.dev).\n\n## Articles\n\n+ [dish deep-dive article](https://blog.vxn.dev/dish-monitoring-service)\n+ [dish history article](https://krusty.space/projects/dish/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthevxn%2Fdish","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthevxn%2Fdish","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthevxn%2Fdish/lists"}