{"id":20823933,"url":"https://github.com/equals215/deepsentinel","last_synced_at":"2025-12-26T05:17:11.613Z","repository":{"id":228106732,"uuid":"773168380","full_name":"equals215/deepsentinel","owner":"equals215","description":"A low-level, server-client software that monitors crucial machine and service states, alerting following a policy when services degrade.","archived":false,"fork":false,"pushed_at":"2024-04-13T17:37:04.000Z","size":6976,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-13T23:10:34.643Z","etag":null,"topics":["alerting","reliability"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/equals215.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}},"created_at":"2024-03-16T23:23:16.000Z","updated_at":"2024-04-16T02:40:44.482Z","dependencies_parsed_at":"2024-04-16T02:40:36.154Z","dependency_job_id":null,"html_url":"https://github.com/equals215/deepsentinel","commit_stats":null,"previous_names":["equals215/deepsentinel"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equals215%2Fdeepsentinel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equals215%2Fdeepsentinel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equals215%2Fdeepsentinel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equals215%2Fdeepsentinel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/equals215","download_url":"https://codeload.github.com/equals215/deepsentinel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243172129,"owners_count":20247885,"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","reliability"],"created_at":"2024-11-17T22:20:03.801Z","updated_at":"2025-12-26T05:17:11.581Z","avatar_url":"https://github.com/equals215.png","language":"Go","readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003ca href=\"http://www.amitmerchant.com/electron-markdownify\"\u003e\u003cimg src=\"https://gist.githubusercontent.com/equals215/4cc46fe3225e4def80c1e915a5608c8d/raw/1b16d0817e88d8d5fa8c0730a8bfa66e072484c9/deepsentinel-crop.svg\" alt=\"Markdownify\" width=\"700\"\u003e\u003c/a\u003e\n  \u003cbr\u003e\n\u003c/h1\u003e\n\n\n\u003c!-- \u003cp align=\"center\"\u003e\n  \u003ca href=\"https://linktr.ee/equals215\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/$-donate-ff69b4.svg?maxAge=2592000\u0026amp;style=flat\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e --\u003e\n\u003cp align=\"center\"\u003e\nIf you ever worried \"What would happen if my monitoring/alerting systems fail?\" then search no further, you're at the right place\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#key-features\"\u003eKey Features\u003c/a\u003e •\n  \u003ca href=\"#install-server\"\u003eInstall\u003c/a\u003e •\n  \u003ca href=\"#dashboard\"\u003eDashboard\u003c/a\u003e •\n  \u003ca href=\"#credits-and-thanks\"\u003eCredits\u003c/a\u003e •\n  \u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\u003cimg alt=\"GitHub Actions Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/equals215/deepsentinel/.github%2Fworkflows%2Fgo-build-and-release.yml\"\u003e\n\u003ca href=\"https://codecov.io/gh/equals215/deepsentinel\" \u003e \n \u003cimg src=\"https://codecov.io/gh/equals215/deepsentinel/branch/master/graph/badge.svg?token=6JKK7IP4VO\"/\u003e \n\u003c/a\u003e\n\u003ca href=\"https://goreportcard.com/report/github.com/equals215/deepsentinel\"\u003e\n  \u003cimg src=\"https://goreportcard.com/badge/github.com/equals215/deepsentinel\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://codeclimate.com/github/equals215/deepsentinel/maintainability\"\u003e\n  \u003cimg src=\"https://api.codeclimate.com/v1/badges/1058b0dd522c52babff0/maintainability\" /\u003e\n\u003c/a\u003e\n\u003cimg src=\"https://snyk.io/test/github/equals215/deepsentinel/badge.svg\" /\u003e\n\u003c/p\u003e\n\n## Quick description\n\nDeepSentinel is a low-level, server-agent software that monitors crucial machine and service states in a scalable and concurrent way that can process incoming data in real-time, track the health status of various services on multiple machines, and trigger alerts based on the absence of expected signals within given time intervals.  \n\nDeepSentinel is thought and coded to fit very niche use-cases where a reliability risk affects your monitoring and alerting systems ; don't expect it to replace your Datadog or Grafana cloud instances!  \n\n## Key Features\n\n* `server` runs fully in-ram with a low ressource footprint\n    - Can be hosted on a high SLA serverless provider\n    - Doesn't need disk access (but appreciate it to persist the auth-token)\n* `agent` pushes simple JSON payloads via HTTP/S as an alive signal\n* Both `server` and `agent` are monitoring themselves for any fatal error\n* `agent` daemonize itself and runs no matter what\n    - You only need to configure `server` address, machine name and auth token\n    - No actions required on the server-side\n* `agent` daemon is live configurable and live unregisterable\n\n## Install Server\n### Docker\nOn any instance that has Docker installed you can run the following commands :\n\n```bash\ndocker run \\\n    -v /your/host/path:/etc/deepsentinel \\\n    -p \u003chost_port\u003e:5000 \\\n    -e DEEPSENTINEL_ADDRESS=0.0.0.0 \\\n    -e DEEPSENTINEL_PORT=5000 \\\n    -e DEEPSENTINEL_PROBE_INACTIVITY_DELAY=10s \\\n    -e DEEPSENTINEL_DEGRADED_TO_FAILED=20 \\\n    -e DEEPSENTINEL_FAILED_TO_ALERT_LOW=30 \\\n    -e DEEPSENTINEL_ALERT_LOW_TO_ALERT_HIGH=50 \\\n    -e DEEPSENTINEL_LOGGING_LEVEL=info \\\n    -e DEEPSENTINEL_LOW_ALERT_PROVIDER=pagerduty \\\n    -e DEEPSENTINEL_HIGH_ALERT_PROVIDER=pagerduty \\\n    -e DEEPSENTINEL_PAGERDUTY_API_KEY=\u003cpd_api_key\u003e \\\n    -e DEEPSENTINEL_PAGERDUTY_INTEGRATION_KEY=\u003cpd_integration_key\u003e \\\n    -e DEEPSENTINEL_PAGERDUTY_INTEGRATION_URL=\u003cpd_integration_url\u003e \\\n    ghcr.io/equals215/deepsentinel-server:latest\n\n```\n\nReplace latest by any tag you want to run. Docker Image tag == Repo tag.  \nAdapt environment variables based on the config you want to apply.  \n\n**You will have to grab the auth token from either the logs or the config file bind mounted to your host**\n\n---\n\n### Binaries\n1. Get the server binary that matches your system under the [Release section](https://github.com/equals215/deepsentinel/releases).  \n\n```bash\nwget https://github.com/equals215/deepsentinel/releases/download/v0.0.3-untested/deepsentinel-server-linux-amd64 -O deepsentinel-server \u0026\u0026 \\\nchmod +x deepsentinel-server\n```\n\n2. Now you have to configure the server :  \n\n```bash\nmkdir -p /etc/deepsentinel/\nnano /etc/deepsentinel/server-config.json\n```\n\nEdit the following configuration example as you wish :  \n\n```json\n{\n  \"address\": \"0.0.0.0\",\n  \"alertlow-to-alerthigh\": 30,\n  \"degraded-to-failed\": 10,\n  \"failed-to-alertlow\": 20,\n  \"high-alert-provider\": \"pagerduty\",\n  \"logging-level\": \"info\",\n  \"low-alert-provider\": \"\",\n  \"no-alert\": false,\n  \"pagerduty\": {\n    \"api-key\": \"...\",\n    \"integration-key\": \"...\",\n    \"integration-url\": \"...\"\n  },\n  \"port\": \"5000\",\n  \"probe-inactivity-delay\": \"5s\"\n}\n```\n\n3. Now that you generated the configuration you can daemonize it if your system supports `systemd` or `launchd` :\n```bash\n./deepsentinel-server daemon install\n```\n\n4. The server should now be able to accept incoming connections. Remember to grab the auth token from either the logs or the config file at `/etc/deepsentinel/server-config.json` — you will need it to configure agents.\n\n## Install Agent\n\nAs the agent is supposed to be run as close to the system as possible, it's not a good practice to run it inside a Docker container, hence why there is not Docker container for it 🤠  \n\n1. Get the agent binary that matches your system under the [Release section](https://github.com/equals215/deepsentinel/releases).  \n\n```bash\nwget https://github.com/equals215/deepsentinel/releases/download/v0.0.3-untested/deepsentinel-agent-linux-amd64 -O deepsentinel-agent \u0026\u0026 \\\nchmod +x deepsentinel-agent\n```\n\n2. Now you have to configure the agent using the `install` command :  \n\nThe following command will ask you for `auth-token`, `server-address` and `machine-name` in order to set up properly. It will then generate it's config file located in `/etc/deepsentinel/agent-config.json` and daemonize itself if your system supports `systemd` or `launchd`\n\n```bash\nsudo ./deepsentinel-agent install\n```\n\n3. Your agent should now be sending alive signals to the server. Check the server's logs to ensure that everything is setup properly.  \n\n## Dashboard\n\nA simple yet effective dashboard was introduced in `v0.0.4-untested`.  \nThis dashboard lets you see the status of your machines at a glance and even execute actions on the probes such as `Delete` them in case a machine died and you don't want to be alerted.  \nIt can be disabled using the `--no-dashboard` flag on the `deepsentinel-server run` command.  \n\n\u003cimg width=\"500\" alt=\"dashboard screenshot\" src=\"https://github.com/equals215/deepsentinel/assets/20166324/3549ce23-36ff-4fea-a72f-969c8eeede2c\"\u003e\n\nThe dashboard is protected with a login mechanism that uses `auth-token` from the server to authenticate against the back-end and pass the `auth-token` as a cookie.  \n\n\u003cimg width=\"500\" alt=\"dashboard login screenshot\" src=\"https://github.com/equals215/deepsentinel/assets/20166324/7c7802e5-f6bc-4970-9ae1-a308d230bdcd\"\u003e  \n\nBehind the cool HTML and JS involved, the dashboard gets it's data from a WebSocket. If you wish to integrate your own dashboard and make use of the WebSocket, here it is : `/dashws` and it requires basic auth.  \nHere's an example URL to use the WebSocket : `ws://admin:\u003cauth-token\u003e@\u003chost:port\u003e/dashws`  \n**Also note that the WebSocket is disabled if you use `--no-dashboard`**\n\n## Credits and Thanks\n- Thanks to [@sovajri7](https://github.com/sovajri7) for troubleshooting and giving feature ideas\n\n## License\n\n[GNU-GPLv3](https://github.com/equals215/deepsentinel/blob/8d8f70623c8725c2596ee5181d37ebdcf14ee81d/LICENSE)\n\n---\n\n\u003e GitHub [@equals215](https://github.com/equals215) \u0026nbsp;\u0026middot;\u0026nbsp;\n\u003e LinkedIn [Thomas Foubert](https://www.linkedin.com/in/thomas-f-devops/)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fequals215%2Fdeepsentinel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fequals215%2Fdeepsentinel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fequals215%2Fdeepsentinel/lists"}