{"id":13606934,"url":"https://github.com/slok/alertgram","last_synced_at":"2025-03-25T03:31:27.426Z","repository":{"id":54981065,"uuid":"224978252","full_name":"slok/alertgram","owner":"slok","description":"Easy and simple prometheus alertmanager alerts on telegram","archived":false,"fork":false,"pushed_at":"2023-01-09T14:46:04.000Z","size":182,"stargazers_count":60,"open_issues_count":6,"forks_count":12,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-19T08:39:40.545Z","etag":null,"topics":["alert","alertmanager","alerts","dead-man-switch","dead-mans-switch","notifications","oncall","prometheus","telegram","webhook"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slok.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2019-11-30T07:50:28.000Z","updated_at":"2025-02-22T21:01:34.000Z","dependencies_parsed_at":"2023-02-08T12:31:33.269Z","dependency_job_id":null,"html_url":"https://github.com/slok/alertgram","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slok%2Falertgram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slok%2Falertgram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slok%2Falertgram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slok%2Falertgram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slok","download_url":"https://codeload.github.com/slok/alertgram/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245394737,"owners_count":20608122,"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":["alert","alertmanager","alerts","dead-man-switch","dead-mans-switch","notifications","oncall","prometheus","telegram","webhook"],"created_at":"2024-08-01T19:01:13.944Z","updated_at":"2025-03-25T03:31:27.077Z","avatar_url":"https://github.com/slok.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Alertgram [![Build Status][github-actions-image]][github-actions-url] [![Go Report Card][goreport-image]][goreport-url]\n\nAlertgram is the easiest way to forward alerts to [Telegram] (Supports [Prometheus alertmanager] alerts).\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://i.imgur.com/4jdOFj9.jpg\" width=\"40%\" align=\"center\" alt=\"alertgram\"\u003e\n\u003c/p\u003e\n\n## Table of contents\n\n- [Introduction](#introduction)\n- [Features](#features)\n- [Input alerts](#input-alerts)\n- [Options](#options)\n- [Run](#run)\n  - [Simple example](#simple-example)\n  - [Production](#production)\n- [Metrics](#metrics)\n- [Development and debugging](#development-and-debugging)\n- [FAQ](#faq)\n  - [Only alertmanager alerts are supported?](#only-alertmanager-alerts-are-supported)\n  - [Where does alertgram listen to alertmanager alerts?](#where-does-alertgram-listen-to-alertmanager-alerts)\n  - [Can I notify to different chats?](#can-i-notify-to-different-chats)\n  - [Can I use custom templates?](#can-i-use-custom-templates)\n  - [Dead man's switch?](#dead-mans-switch)\n\n## Introduction\n\nEverything started as a way of forwarding [Prometheus alertmanager] alerts to [Telegram] because the solutions that I found were too complex, I just wanted to forward alerts to channels without trouble. And Alertgram is just that, a simple app that forwards alerts to Telegram groups and channels and some small features that help like metrics and dead man's switch.\n\n## Features\n\n- Alertmanager alerts webhook receiver compatibility.\n- Telegram notifications.\n- Metrics in Prometheus format.\n- Optional dead man switch endpoint.\n- Optional customizable templates.\n- Configurable notification chat ID targets (with fallback to default chat ID).\n- Easy setup and flexible.\n- Lightweight.\n- Perfect for any environment, from a company cluster to home cheap clusters (e.g [K3S]).\n\n## Input alerts\n\nAlertgram is developed in a decoupled way so in a future may be extended to more inputs apart from Alertmanager's webhook API (ask for a new input if you want).\n\n## Options\n\nUse `--help` flag to show the options.\n\nThe configuration of the app is based on flags that also can be set as env vars prepending `ALERTGRAM` to the var. e.g: the flag `--telegram.api-token` would be `ALERTGRAM_TELEGRAM_API_TOKEN`. You can combine both, flags have preference.\n\n## Run\n\nTo forward alerts to Telegram the minimum options that need to be set are `--telegram.api-token` and `--telegram.chat-id`\n\n### Simple example\n\n```bash\ndocker run -p8080:8080 -p8081:8081 slok/alertgram:latest --telegram.api-token=XXXXX --telegram.chat-id=YYYYY\n```\n\n### Production\n\n- [Get telegram API token][telegram-token]\n- [Get telegram chat IDs][telegram-chat-id]\n- [Configure Alertmanager][alertmanager-configuration]\n- [Deploy on Kubernetes][kubernetes-deployment]\n\n## Metrics\n\nThe app comes with [Prometheus] metrics, it measures the forwarded alerts, HTTP requests, errors... with rate and latency.\n\nBy default are served on `/metrics` on `0.0.0.0:8081`\n\n## Development and debugging\n\nYou can use the `--notify.dry-run` to show the alerts on the terminal instead of forwarding them to telegram.\n\nAlso remember that you can use `--debug` flag.\n\n## FAQ\n\n### Only alertmanager alerts are supported?\n\nAt this moment yes, but we can add more input alert systems if you want, create an issue\nso we can discuss and implement.\n\n### Where does alertgram listen to alertmanager alerts?\n\nBy default in `0.0.0.0:8080/alerts`, but you can use `--alertmanager.listen-address` and\n`--alertmanager.webhook-path` to customize.\n\n### Can I notify to different chats?\n\nThere are 3 levels where you could customize the notification chat:\n\n- By default: Using the required `--telegram.chat-id` flag.\n- At URL level: using [query string] parameter, e.g. `0.0.0.0:8080/alerts?chat-id=-1009876543210`.\n  This query param can be customized with `--alertmanager.chat-id-query-string` flag.\n- At alert level: If alerts have a label with the chat ID the alert notification will be forwarded to\n  that label content. Use the flag `--alert.label-chat-id` to customize the label name, by default\n  is `chat_id`.\n\nThe preference is in order from highest to lowest: Alert, URL, Default.\n\n### Can I use custom templates?\n\nYes!, use the flag `--notify.template-path`. You can check [testdata/templates](testdata/templates) for examples.\n\nThe templates are [HTML Go templates] with [Sprig] functions, so you can use these also.\n\nYou can use also the notification dry run mode to check your templates without the need\nto notify on telegram:\n\n```bash\nexport ALERTGRAM_TELEGRAM_API_TOKEN=fake\nexport ALERTGRAM_TELEGRAM_CHAT_ID=1234567890\n\ngo run ./cmd/alertgram/ --notify.template-path=./testdata/templates/simple.tmpl --debug --notify.dry-run\n```\n\nTo send an alert easily and check the template rendering without an alertmanager, prometheus, alerts... you can use the test alerts that are on [testdata/alerts](testdata/alerts):\n\n```bash\ncurl -i http://127.0.0.1:8080/alerts -d @./testdata/alerts/base.json\n```\n\n### Dead man's switch?\n\nA [dead man's switch][dms] (from now on, DMS) is a technique or process where at regular intervals a signal must be received\nso the DMS is disabled, if that signal is not received it will be activated.\n\nIn monitoring this would be: If an alert is not received at regular intervals, the switch will be activated and notify that we\nare not receiving alerts, this is mostly used to know that our alerting system is working.\n\nFor example we would set Prometheus triggering an alert continously, Alertmanager sending this specific alert\nevery `7m` to the DMS endpoint in Alertgram, and Alertgram would be configured with a `10m` interval DMS.\n\nWith this setup if Prometheus fails creating the alert, Alertmanager sending the alert to Alertgram, or Alertgram not receiving\nthis alert (e.g. network problems), Alertmanager will send an alert to Telegram to notify us that our monitoring system is broken.\n\nYou could use the same alertgram or another instance, usually in other machine, cluster... so if the cluster/machine fails, your\nis isolated and could notify you.\n\nTo Enable Alertgram's DMS use `--dead-mans-switch.enable` to enable. By default it will be listening in `/alert/dms`, with a\n`15m` interval and use the telegrams default notifier and chat ID. To customize this settings use:\n\n- `--dead-mans-switch.interval`: To configure the interval.\n- `--dead-mans-switch.chat-id`: To configure the notifier chat, is independent of the notifier\n  although at this moment is Telegram, if not set it will use the notifier default chat target.\n- `--alertmanager.dead-mans-switch-path` To configure the path the alertmanager can send the DMS alerts.\n\n[github-actions-image]: https://github.com/slok/alertgram/workflows/CI/badge.svg\n[github-actions-url]: https://github.com/slok/alertgram/actions\n[goreport-image]: https://goreportcard.com/badge/github.com/slok/alertgram\n[goreport-url]: https://goreportcard.com/report/github.com/slok/alertgram\n[prometheus alertmanager]: https://github.com/prometheus/alertmanager\n[prometheus]: https://prometheus.io/\n[telegram]: https://telegram.org/\n[telegram-token]: https://core.telegram.org/bots#6-botfather\n[telegram-chat-id]: https://github.com/GabrielRF/telegram-id\n[alertmanager-configuration]: docs/alertmanager\n[kubernetes-deployment]: docs/kubernetes\n[html go templates]: https://golang.org/pkg/html/template/\n[sprig]: http://masterminds.github.io/sprig\n[query string]: https://en.wikipedia.org/wiki/Query_string\n[k3s]: https://k3s.io/\n[dms]: https://en.wikipedia.org/wiki/Dead_man%27s_switch\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslok%2Falertgram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslok%2Falertgram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslok%2Falertgram/lists"}