{"id":13582095,"url":"https://github.com/mr-karan/calert","last_synced_at":"2025-04-09T10:02:22.992Z","repository":{"id":34896993,"uuid":"163198627","full_name":"mr-karan/calert","owner":"mr-karan","description":"🔔 Send alert notifications to Google Chat via Prometheus Alertmanager","archived":false,"fork":false,"pushed_at":"2024-10-08T09:22:20.000Z","size":6931,"stargazers_count":170,"open_issues_count":19,"forks_count":60,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-02T08:05:23.629Z","etag":null,"topics":["alerting","alertmanager","alertmanager-webhook","google-chat","monitoring","prometheus"],"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/mr-karan.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}},"created_at":"2018-12-26T16:33:21.000Z","updated_at":"2025-04-01T15:52:29.000Z","dependencies_parsed_at":"2023-11-20T04:33:24.879Z","dependency_job_id":"c1df153e-aee0-4246-b4d8-9201d32521b7","html_url":"https://github.com/mr-karan/calert","commit_stats":{"total_commits":105,"total_committers":23,"mean_commits":4.565217391304348,"dds":0.6857142857142857,"last_synced_commit":"ca63a8ebe5e85af7dff84b0060d4cdd85ff036be"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-karan%2Fcalert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-karan%2Fcalert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-karan%2Fcalert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-karan%2Fcalert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mr-karan","download_url":"https://codeload.github.com/mr-karan/calert/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248018032,"owners_count":21034045,"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","alertmanager","alertmanager-webhook","google-chat","monitoring","prometheus"],"created_at":"2024-08-01T15:02:25.538Z","updated_at":"2025-04-09T10:02:22.964Z","avatar_url":"https://github.com/mr-karan.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"\u003ca href=\"https://zerodha.tech\"\u003e\u003cimg src=\"https://zerodha.tech/static/images/github-badge.svg\" align=\"right\" /\u003e\u003c/a\u003e\n\n# calert\n\n_Send Alertmanager notifications to Google Chat (and more!)_\n\n![](docs/images/calert.png)\n\n`calert` uses Alertmanager [webhook receiver](https://prometheus.io/docs/alerting/configuration/#webhook_config) to receive alerts payload, and pushes this data to Google Chat [webhook](https://developers.google.com/hangouts/chat/how-tos/webhooks) endpoint.\n\n## Quickstart\n\n### Binary\n\nGrab the latest release from [Releases](https://github.com/mr-karan/calert/releases).\n\nTo run:\n\n```sh\n./calert.bin --config config.toml\n```\n\n### Docker\n\nYou can find the list of docker images [here](https://github.com/mr-karan/calert/pkgs/container/calert)\n\n```\ndocker pull ghcr.io/mr-karan/calert:latest\n```\n\nHere's an example `docker-compose` config with a custom `message.tmpl` mounted inside the container:\n\n```yml\n  calert:\n    image: ghcr.io/mr-karan/calert:latest\n    ports:\n      - \"6000:6000\"\n    volumes:\n      - ./message.tmpl:/etc/calert/message.tmpl\n```\n\n### Configuration\n\nRefer to [config.sample.toml](./config.sample.toml) for instructions on how to configure `calert`.\n\nAll the config variables can also be supplied as Environment Variables by prefixing `CALERT_` and replacing `.` (_period_) with `__` (_double underscores_).\n\nExample:\n\n- `app.address` would become `CALERT_APP__ADDRESS`\n\n#### App\n\n|  Key  \t|  Explanation \t| Default \t|\n|---\t| ---\t| --- |\n|  `app.address` \t| Address of the HTTP Server. \t| `0.0.0.0:6000`\t|\n|  `app.server_timeout` \t| Server timeout for HTTP requests.  \t| `5s` |\n|  `app.enable_request_logs` \t| Enable HTTP request logging.  \t| `true` |\n|  `app.log` \t| Use `debug` to enable verbose logging. Can be set to `info` otherwise.  \t| `info` |\n\n\n#### Providers\n\n`calert` can load a map of different _providers_. The unique identifier for the `provider` is the room name. Each provider has it's own configuration, based on it's `provider_type. Currently `calert` supports Google Chat but can support arbitary providers as well.\n\n|  Key  \t|  Explanation \t| Default \t|\n|---\t| ---\t| --- |\n|  `providers.\u003croom_name\u003e.type` \t| Provider type. Currently only `google_chat` is supported. \t| `google_chat`\t|\n|  `providers.\u003croom_name\u003e.endpoint` \t| Webhook URL to send alerts to.  \t| - |\n|  `providers.\u003croom_name\u003e.max_idle_conns` \t| Maximum Keep Alive connections to keep in the pool.  \t| `50` |\n|  `providers.\u003croom_name\u003e.timeout` \t| Timeout for making HTTP requests to the webhook URL.  \t| `7s` |\n|  `providers.\u003croom_name\u003e.template` \t| Template for rendering a formatted Alert notification.  \t| `static/message.tmpl` |\n|  `providers.\u003croom_name\u003e.thread_ttl` \t| Timeout to keep active alerts in memory. Once this TTL expires, a new thread will be created.\t| `12h` |\n\n## Alertmanager Integration\n\n-   Alertmanager has the ability of group similar alerts together and fire only one event, clubbing all the alerts data into one event. `calert` leverages this and sends all alerts in one message by looping over the alerts and passing data in the template. You can configure the rules for grouping the alerts in `alertmanager.yml` config. You can read more about it [here](https://github.com/prometheus/docs/blob/master/content/docs/alerting/alertmanager.md#grouping).\n\n- Configure Alertmanager config file (`alertmanager.yml`) and give the address of calert web-server. You can refer to the [official documentation](https://prometheus.io/docs/alerting/configuration/#webhook_config) for more details.\n\nYou can refer to the following config block to route webhook alerts to `calert`:\n\n```yml\nroute:\n    receiver: 'calert'\n    group_wait: 30s\n    group_interval: 60s\n    repeat_interval: 15m\n    group_by: ['room', 'alertName']\n\nreceivers:\n    - name: 'calert'\n      webhook_configs:\n      - url: 'http://calert:6000/dispatch'\n```\n\n## Threading Support in Google Chat\n\n`calert` ships with a basic support for sending multiple related alerts under a same thread, working around the limitations by Alertmanager.\n\nAlertmanager currently doesn't send any _Unique Identifier_ for each Alert. The use-case of sending related alerts under the same thread is helpful to triage similar alerts and see all their different states (_Firing_, _Resolved_) for people consuming these alerts. `calert` tries to solve this by:\n\n- Use the `fingerprint` field present in the Alert. This field is computed by hashing the labels for an alert.\n- Create a map of `active_alerts` in memory. Add an alert by it's fingerprint and generate a random `UUID.v4` and store that in the map (along with some more meta-data like `startAt` field).\n- Use `?threadKey=uuid` query param while making a request to Google Chat. This ensures that all alerts with same fingerprint (=_same labels_) go under the same thread.\n- A background worker runs _every hour_ which scans the map of `active_alerts`. It checks whether the alert's `startAt` field has crossed the TTL (as specified by `thread_ttl`). If the TTL is expired then the `alert` is removed from the map. This ensures that the map of `active_alerts` doesn't grow unbounded and after a certain TTL all alerts are sent to a new thread.\n\n## Prometheus Metrics\n\n`calert` exposes various metrics in the Prometheus exposition format.\n\nHere's a list of internal app metrics available at `/metrics`:\n\n|  Name  \t|  Description \t| Data type \t|\n|---\t| ---\t| --- |\n|  `calert_uptime_seconds` \t| Uptime of app (_in seconds_). \t| `counter`\t|\n|  `calert_start_timestamp` \t| UNIX timestamp since the app was booted.  \t| `gauge` |\n|  `calert_http_requests_total` \t| Number of HTTP requests, grouped with labels like `handler`.  \t| `counter` |\n|  `calert_http_request_duration_seconds_{sum,count,bucket}` \t| Duration of HTTP request (_in seconds_).  \t| `histogram` |\n|  `calert_alerts_dispatched_total` \t| Number of alerts dispatched to upstream providers, grouped with labels like `provider` and `room`.  \t| `counter` |\n|  `calert_alerts_dispatched_duration_seconds_{sum,count,bucket}` \t| Duration to send an alert to upstream provider.\t| `histogram` |\n\nIt also exposes Go process metrics in addition to app metrics, which you can use to monitor the performance of `calert`.\n\n## Migrating from v1 to v2\n\nA few notes on `v2` migration:\n\n### Config schema changes\n\n`v2` is a complete rewrite from scratch and **is a breaking release**. The configuration has changed extensively. Please refer to latest [`config.sample.toml`](config.sample.toml) for a complete working example of the config.\n\n### Dry Run Mode\n\nIn case you're simply experimenting with `calert` config changes and you don't wish to send _actual_ notifications, you can set `dry_run=true` in each provider.\n\n### Room Name for Google Chat\n\nApart from the config, `calert` now determines the `room` based on the `receiver` specified in Alertmanager config. Previously, the room was identified with `?room` query parameter in each HTTP request. However, since the Alert payload contains the `receiver` name, it's better to extract this information from the labels instead.\n\nHere's an example of how Alertmanager config looks like. Notice the value of `receiver` (`prod_alerts`) should match one of `provider.\u003croom_name\u003e` (eg `provider.prod_alerts`) in your `config.toml`):\n\n```yml\nreceivers:\n    - name: 'prod_alerts'\n      webhook_configs:\n      - url: 'http://calert:6000/dispatch'\n```\n\n## Contribution\n\nPRs on Feature Requests, Bug fixes are welcome. Feel free to open an issue and have a discussion first.\n\nFor deployment manifests like Helm, Kustomize, Nomad etc - they're placed under `contrib` folder and generally manintained by the community.\n\n## License\n\n[LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmr-karan%2Fcalert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmr-karan%2Fcalert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmr-karan%2Fcalert/lists"}