{"id":22845452,"url":"https://github.com/idealista/prom2teams","last_synced_at":"2025-05-15T17:02:21.919Z","repository":{"id":37492937,"uuid":"101161310","full_name":"idealista/prom2teams","owner":"idealista","description":"prom2teams is an HTTP server built with Python that receives alert notifications from a previously configured Prometheus Alertmanager instance and forwards it to Microsoft Teams using defined connectors","archived":false,"fork":false,"pushed_at":"2024-09-24T17:12:49.000Z","size":705,"stargazers_count":281,"open_issues_count":3,"forks_count":89,"subscribers_count":29,"default_branch":"develop","last_synced_at":"2025-05-12T23:48:06.033Z","etag":null,"topics":["alerting","alertmanager","devops","docker","docker-image","helm-chart","kubernetes","microsoft-teams","monitoring","prom2teams","prometheus","prometheus-alertmanager","prometheus-alerts","prometheus-monitoring","webhook"],"latest_commit_sha":null,"homepage":"","language":"Python","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/idealista.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","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":"2017-08-23T09:12:49.000Z","updated_at":"2025-04-17T12:10:05.000Z","dependencies_parsed_at":"2023-12-16T16:05:11.926Z","dependency_job_id":"9b8eea49-0bd1-4e6a-855c-a324b072454b","html_url":"https://github.com/idealista/prom2teams","commit_stats":{"total_commits":363,"total_committers":41,"mean_commits":8.853658536585366,"dds":0.8044077134986226,"last_synced_commit":"4a12f96e9c84e44626fd55fa134e4e710402cb89"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idealista%2Fprom2teams","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idealista%2Fprom2teams/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idealista%2Fprom2teams/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idealista%2Fprom2teams/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/idealista","download_url":"https://codeload.github.com/idealista/prom2teams/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384937,"owners_count":22062421,"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","devops","docker","docker-image","helm-chart","kubernetes","microsoft-teams","monitoring","prom2teams","prometheus","prometheus-alertmanager","prometheus-alerts","prometheus-monitoring","webhook"],"created_at":"2024-12-13T03:17:19.095Z","updated_at":"2025-05-15T17:02:21.876Z","avatar_url":"https://github.com/idealista.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg alt=\"logo\" src=\"https://raw.githubusercontent.com/idealista/prom2teams/master/logo.gif\"\u003e\n\n  [![Build Status](https://travis-ci.com/idealista/prom2teams.svg?branch=master)](https://travis-ci.com/idealista/prom2teams)\n  [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=idealista_prom2teams\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=idealista_prom2teams)\n  [![Docker Build Status](https://img.shields.io/docker/build/idealista/prom2teams.svg)](https://hub.docker.com/r/idealista/prom2teams/) \n  [![Docker Hub Pulls](https://img.shields.io/docker/pulls/idealista/prom2teams.svg)](https://hub.docker.com/r/idealista/prom2teams/)\n\u003c/div\u003e\n\n# prom2teams: Prometheus Alertmanager/Microsoft Teams integration\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/idealista/prom2teams/master/assets/example.png\" alt=\"Alert example\" style=\"width: 600px;\"/\u003e\n\u003c/p\u003e\n\n**prom2teams** is a service built with Python that receives alert notifications from a previously configured [Prometheus Alertmanager](https://github.com/prometheus/alertmanager) instance and forwards it to [Microsoft Teams](https://teams.microsoft.com/) using defined connectors.\n\nIt presents grouping of alerts, labels/annotations exclusion and a Teams' alert retry policy among its key features.\n\n\n- [Getting Started](#getting-started)\n\t- [Prerequisities](#prerequisites)\n\t- [Installing](#installing)\n- [Usage](#usage)\n  - [Docker Image](#docker-image)\n  - [Helm Chart](#helm-chart)\n  - [Config file](#config-file)\n\t- [Configuring Prometheus](#configuring-prometheus)\n\t- [Templating](#templating)\n- [Documentation](#documentation)\n  - [Swagger UI](#swagger-ui)\n- [Testing](#testing)\n- [Built With](#built-with)\n- [Versioning](#versioning)\n- [Authors](#authors)\n- [License](#license)\n- [Contributing](#contributing)\n\n## Getting Started\n\n### Prerequisites\n\nThe application has been tested with _Prometheus 2.2.1_, _Python 3.8.0_ and _pip 9.0.1_.\n\nNewer versions of _Prometheus/Python/pip_ should work but could also present issues.\n\n### Installing\n\nprom2teams is present on [PyPI](https://pypi.python.org/pypi/prom2teams), so could be installed using pip3:\n\n```bash\n$ pip3 install prom2teams\n```\n\n**Note:** Works since v1.1.1\n\n## Usage\n\n**Important:** Config path must be provided with at least one Microsoft Teams Connector. Check the options to know how you can supply it.\n\n```bash\n# To start the server (enable metrics, config file path , group alerts by, log file path, log level and Jinja2 template path are optional arguments):\n$ prom2teams [--enablemetrics] [--configpath \u003cconfig file path\u003e] [--groupalertsby (\"name\"|\"description\"|\"instance\"|\"severity\"|\"summary\")] [--logfilepath \u003clog file path\u003e] [--loglevel (DEBUG|INFO|WARNING|ERROR|CRITICAL)] [--templatepath \u003cJinja2 template file path\u003e]\n\n# To show the help message:\n$ prom2teams --help\n```\nOther options to start the service are:\n\n```bash\nexport APP_CONFIG_FILE=\u003cconfig file path\u003e\n$ prom2teams\n```\n**Note:** Grouping alerts works since v2.2.1\n\n### Docker image\n\nEvery new Prom2teams release, a new Docker image is built in our [Dockerhub](https://hub.docker.com/r/idealista/prom2teams). We strongly recommend you to use the images with the version tag, though it will be possible to use them without it.\n\nThere are two things you need to bear in mind when creating a Prom2teams container:\n\n- The connector URL must be passed as the environment variable `PROM2TEAMS_CONNECTOR`\n- In case you want to group alerts, you need to pass the field as the environment variable `PROM2TEAMS_GROUP_ALERTS_BY`\n- You need to map container's Prom2teams port to one on your host.\n\nSo a sample Docker run command would be:\n\n```bash\n$ docker run -it -d -e PROM2TEAMS_GROUP_ALERTS_BY=FIELD_YOU_WANT_TO_GROUP_BY -e PROM2TEAMS_CONNECTOR=\"CONNECTOR_URL\" -p 8089:8089 idealista/prom2teams:VERSION\n```\n\n#### Provide custom config file\n\nIf you prefer to use your own config file, you just need to provide it as a Docker volume to the container and map it to `/opt/prom2teams/config.ini`. Sample:\n\n```bash\n$ docker run -it -d -v pathToTheLocalConfigFile:/opt/prom2teams/config.ini -p 8089:8089 idealista/prom2teams:VERSION\n```\n\n### Helm chart\n\n#### Installing the Chart\n\nTo install the chart with the release name `my-release` run:\n\n```bash\n$ helm install --name my-release /location/of/prom2teams_ROOT/helm\n```\n\nAfter a few seconds, Prom2Teams should be running.\n\n\u003e **Tip**: List all releases using `helm list`, a release is a name used to track a specific deployment\n\n#### Uninstalling the Chart\n\nTo uninstall/delete the `my-release` deployment:\n\n##### Helm 2\n\n```bash\n$ helm delete my-release\n```\n\u003e **Tip**: Use helm delete --purge my-release to completely remove the release from Helm internal storage\n\nThe command removes all the Kubernetes components associated with the chart and deletes the release.\n\n##### Helm 3\n\n```bash\n$ helm uninstall my-release\n```\n\nThe command removes all the Kubernetes components associated with the chart and deletes the release.\n\n#### Configuration\n\nThe following table lists the configurable parameters of the Prom2teams chart and their default values.\n\n| Parameter                                       | Description                                                                                                        | Default\n| ---                                             | ---                                                                                                                | ---\n| `image.repository`                              | The image repository to pull from                                                                                  | `idealista/prom2teams`\n| `image.tag`                                     | The image tag to pull                                                                                              | `\u003cempty\u003e`\n| `image.pullPolicy`                              | The image pull policy                                                                                              | `IfNotPresent`\n| `resources.requests.cpu`                        | CPU requested for being run in a node                                                                              | `100m`\n| `resources.requests.memory`                     | Memory requested for being run in a node                                                                           | `128Mi`\n| `resources.limits.cpu`                          | CPU limit                                                                                                          | `200m`\n| `resources.limits.memory`                       | Memory limit                                                                                                       | `200Mi`\n| `service.type`                                  | Service Map (NodePort/ClusterIP)                                                                                   | `ClusterIP`\n| `service.port`                                  | Service Port                                                                                                       | `8089`\n| `prom2teams.host`                               | IP to bind to                                                                                                      | `0.0.0.0`\n| `prom2teams.port`                               | Port to bind to                                                                                                    | `8089`\n| `prom2teams.connector`                          | Connector URL                                                                                                      | `\u003cempty\u003e`\n| `prom2teams.connectors`                         | A map where the keys are the connector names and the values are the connector webhook urls                         | `{}`\n| `prom2teams.group_alerts_by`                    | Group_alerts_by field                                                                                              | `\u003cempty\u003e`\n| `prom2teams.loglevel`                           | Loglevel                                                                                                           | `INFO`\n| `prom2teams.templatepath`                       | Custom Template path (files/teams.j2)                                                                              | `/opt/prom2teams/helmconfig/teams.j2`\n| `prom2teams.config`                             | Config (specific to Helm)                                                                                          | `/opt/prom2teams/helmconfig/config.ini`\n| `prom2teams.extraEnv`                           | Dictionary of arbitrary additional environment variables for deployment (eg. `HTTP_PROXY`)                         | `\u003cempty\u003e`\n\n### Production\n\nFor production environments you should prefer using a WSGI server. [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/)\ndependency is installed for an easy usage. Some considerations must be taken to use it:\n\nThe binary `prom2teams_uwsgi` launches the app using the uwsgi server. Due to some incompatibilities with [wheel](https://github.com/pypa/wheel)\nyou must install `prom2teams` using `sudo pip install --no-binary :all: prom2teams` (https://github.com/pypa/wheel/issues/92)\n\n```bash\n$ prom2teams_uwsgi \u003cpath to uwsgi ini config\u003e\n```\n\nAnd `uwsgi` would look like:\n\n```\n[uwsgi]\nmaster = true\nprocesses = 5\n#socket = 0.0.0.0:8001\n#protocol = http\nsocket = /tmp/prom2teams.sock\nchmod-socket = 777\nvacuum = true\nenv = APP_ENVIRONMENT=pro\nenv = APP_CONFIG_FILE=/etc/default/prom2teams.ini\n```\n\nConsider not provide `chdir` property neither `module` property.\n\nAlso you can set the `module` file, by doing a symbolic link: `sudo mkdir -p /usr/local/etc/prom2teams/ \u0026\u0026 sudo ln -sf /usr/local/lib/python3.7/dist-packages/usr/local/etc/prom2teams/wsgi.py /usr/local/etc/prom2teams/wsgi.py` (check your dist-packages folder)\n\nAnother approach is to provide yourself the `module` file [module example](bin/wsgi.py) and the `bin` uwsgi call [uwsgi example](bin/prom2teams_uwsgi)\n\n**Note:** default log level is DEBUG. Messages are redirected to stdout. To enable file log, set the env APP_ENVIRONMENT=(pro|pre)\n\n\n### Config file\n\nThe config file is an [INI file](https://docs.python.org/3/library/configparser.html#supported-ini-file-structure) and should have the structure described below:\n\n```ini\n[Microsoft Teams]\n# At least one connector is required here\nConnector: \u003cwebhook url\u003e\nAnotherConnector: \u003cwebhook url\u003e   \n...\n\n[HTTP Server]\nHost: \u003chost ip\u003e # default: localhost\nPort: \u003chost port\u003e # default: 8089\n\n[Log]\nLevel: \u003cloglevel (DEBUG|INFO|WARNING|ERROR|CRITICAL)\u003e # default: DEBUG\nPath: \u003clog file path\u003e  # default: /var/log/prom2teams/prom2teams.log\n\n[Template]\nPath: \u003cJinja2 template path\u003e # default: app resources default template (./prom2teams/resources/templates/teams.j2)\n\n[Group Alerts]\nField: \u003cField to group alerts by\u003e # alerts won't be grouped by default\n\n[Labels]\nExcluded: \u003cComma separated list of labels to ignore\u003e\n\n[Annotations]\nExcluded: \u003cComma separated list of annotations to ignore\u003e\n\n[Teams Client]\nRequestTimeout: \u003cConfigures the request timeout\u003e # defaults to 30 secs\nRetryEnable: \u003cEnables teams client retry policy\u003e # defaults to false\nRetryWaitTime: \u003cWait time between retries\u003e # default: 60 secs\nMaxPayload: \u003cTeams client payload limit in bytes\u003e # default: 24KB\n```\n\n**Note:** Grouping alerts works since v2.2.0\n\n### Configuring Prometheus\n\nThe [webhook receiver](https://prometheus.io/docs/alerting/configuration/#\u003cwebhook_config\u003e) in Prometheus allows configuring a prom2teams server.\n\nThe url is formed by the host and port defined in the previous step.\n\n**Note:** In order to keep compatibility with previous versions, v2.0 keep attending the default connector (\"Connector\") in the endpoint 0.0.0.0:8089. This will be removed in future versions.   \n\n```\n// The prom2teams endpoint to send HTTP POST requests to.\nurl: 0.0.0.0:8089/v2/\u003cConnector1\u003e\n```\n\n### Prom2teams Prometheus metrics\n\nProm2teams uses Flask and, to have the service monitored, we use @rycus66's [Prometheus Flask Exporter](https://github.com/rycus86/prometheus_flask_exporter). This will enable an endpoint in `/metrics` where you could find interesting metrics to monitor such as number of responses with a certain status. To enable this endpoint, just either:\n\n- Use the `--enablemetrics` or `-m` flag when launching prom2teams.\n- Set the environment variable `PROM2TEAMS_PROMETHEUS_METRICS=true`.\n\n### Templating\n\nprom2teams provides a [default template](prom2teams/resources/templates/teams.j2) built with [Jinja2](http://jinja.pocoo.org/docs/2.10/) to render messages in Microsoft Teams. This template could be overrided using the 'templatepath' argument ('--templatepath \u003cJinja2 template file path\u003e') during the application start.\n\nSome fields are considered mandatory when received from Alert Manager.\nIf such a field is not included a default value of 'unknown' is assigned.\n\nAll non-mandatory labels not in excluded list are injected in `extra_labels` key. All non-mandatory annotations not in excluded list are injected in `extra_annotations` key.\n\nAlertmanager fingerprints are available in the `fingerprint` key.  Fingerprints\nare supported by Alertmanager 0.19.0 or greater.\n\n## Documentation\n### Swagger UI\n\nAccessing to `\u003cHost\u003e:\u003cPort\u003e` (e.g. `localhost:8089`) in a web browser shows the API v1 documentation.\n\n\u003cimg src=\"https://raw.githubusercontent.com/idealista/prom2teams/master/assets/swagger_v1.png\" alt=\"Swagger UI\" style=\"width: 600px;\"/\u003e\n\nAccessing to `\u003cHost\u003e:\u003cPort\u003e/v2` (e.g. `localhost:8089/v2`) in a web browser shows the API v2 documentation.\n\n\u003cimg src=\"https://raw.githubusercontent.com/idealista/prom2teams/master/assets/swagger_v2.png\" alt=\"Swagger UI\" style=\"width: 600px;\"/\u003e\n\n## Testing\n\nTo run the test suite you should type the following:\n\n```bash\n// After cloning prom2teams :)\n$ pip install -r requirements.txt\n$ python3 -m unittest discover tests\n$ cd tests/e2e\n$ ./test.sh\n```\n\n## Built With\n![Python 3.8.0](https://img.shields.io/badge/Python-3.8.0-green.svg)\n![pip 9.0.1](https://img.shields.io/badge/pip-9.0.1-green.svg)\n\n## Versioning\n\nFor the versions available, see the [tags on this repository](https://github.com/idealista/prom2teams/tags).\n\nAdditionaly you can see what change in each version in the [CHANGELOG.md](CHANGELOG.md) file.\n\n## Authors\n\n* **Idealista** - *Work with* - [idealista](https://github.com/idealista)\n\nSee also the list of [contributors](https://github.com/idealista/prom2teams/contributors) who participated in this project.\n\n## License\n\n![Apache 2.0 License](https://img.shields.io/hexpm/l/plug.svg)\n\nThis project is licensed under the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) license - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](.github/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidealista%2Fprom2teams","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fidealista%2Fprom2teams","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidealista%2Fprom2teams/lists"}