Package: prom2teams
prom2teams: Prometheus Alertmanager/Microsoft Teams integrationprom2teamsis a service built with Python that receives alert notifications from a previously configuredPrometheus Alertmanagerinstance and forwards it toMicrosoft Teamsusing defined connectors.It presents grouping of alerts, labels/annotations exclusion and a Teams' alert retry policy among its key features.Getting StartedPrerequisitiesInstallingUsageDocker ImageHelm ChartConfig fileConfiguring PrometheusTemplatingDocumentationSwagger UITestingBuilt WithVersioningAuthorsLicenseContributingGetting StartedPrerequisitesThe application has been tested withPrometheus 2.2.1,Python 3.8.0andpip 9.0.1.Newer versions ofPrometheus/Python/pipshould work but could also present issues.Installingprom2teams is present onPyPI, so could be installed using pip3:$pip3installprom2teamsNote:Works since v1.1.1UsageImportant:Config path must be provided with at least one Microsoft Teams Connector. Check the options to know how you can supply it.# To start the server (enable metrics, config file path , group alerts by, log file path, log level and Jinja2 template path are optional arguments):$prom2teams[--enablemetrics][--configpath<configfilepath>][--groupalertsby("name"|"description"|"instance"|"severity"|"summary")][--logfilepath<logfilepath>][--loglevel(DEBUG|INFO|WARNING|ERROR|CRITICAL)][--templatepath<Jinja2templatefilepath>]# To show the help message:$prom2teams--helpOther options to start the service are:exportAPP_CONFIG_FILE=<configfilepath>
$prom2teamsNote:Grouping alerts works since v2.2.1Docker imageEvery new Prom2teams release, a new Docker image is built in ourDockerhub. We strongly recommend you to use the images with the version tag, though it will be possible to use them without it.There are two things you need to bear in mind when creating a Prom2teams container:The connector URL must be passed as the environment variablePROM2TEAMS_CONNECTORIn case you want to group alerts, you need to pass the field as the environment variablePROM2TEAMS_GROUP_ALERTS_BYYou need to map container's Prom2teams port to one on your host.So a sample Docker run command would be:$dockerrun-it-d-ePROM2TEAMS_GROUP_ALERTS_BY=FIELD_YOU_WANT_TO_GROUP_BY-ePROM2TEAMS_CONNECTOR="CONNECTOR_URL"-p8089:8089idealista/prom2teams:VERSIONProvide custom config fileIf 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:$dockerrun-it-d-vpathToTheLocalConfigFile:/opt/prom2teams/config.ini-p8089:8089idealista/prom2teams:VERSIONHelm chartInstalling the ChartTo install the chart with the release namemy-releaserun:$helminstall--namemy-release/location/of/prom2teams_ROOT/helmAfter a few seconds, Prom2Teams should be running.Tip: List all releases usinghelm list, a release is a name used to track a specific deploymentUninstalling the ChartTo uninstall/delete themy-releasedeployment:Helm 2$helmdeletemy-releaseTip: Use helm delete --purge my-release to completely remove the release from Helm internal storageThe command removes all the Kubernetes components associated with the chart and deletes the release.Helm 3$helmuninstallmy-releaseThe command removes all the Kubernetes components associated with the chart and deletes the release.ConfigurationThe following table lists the configurable parameters of the Prom2teams chart and their default values.ParameterDescriptionDefaultimage.repositoryThe image repository to pull fromidealista/prom2teamsimage.tagThe image tag to pull<empty>image.pullPolicyThe image pull policyIfNotPresentresources.requests.cpuCPU requested for being run in a node100mresources.requests.memoryMemory requested for being run in a node128Miresources.limits.cpuCPU limit200mresources.limits.memoryMemory limit200Miservice.typeService Map (NodePort/ClusterIP)ClusterIPservice.portService Port8089prom2teams.hostIP to bind to0.0.0.0prom2teams.portPort to bind to8089prom2teams.connectorConnector URL<empty>prom2teams.connectorsA map where the keys are the connector names and the values are the connector webhook urls{}prom2teams.group_alerts_byGroup_alerts_by field<empty>prom2teams.loglevelLoglevelINFOprom2teams.templatepathCustom Template path (files/teams.j2)/opt/prom2teams/helmconfig/teams.j2prom2teams.configConfig (specific to Helm)/opt/prom2teams/helmconfig/config.iniprom2teams.extraEnvDictionary of arbitrary additional environment variables for deployment (eg.HTTP_PROXY)<empty>ProductionFor production environments you should prefer using a WSGI server.uWSGIdependency is installed for an easy usage. Some considerations must be taken to use it:The binaryprom2teams_uwsgilaunches the app using the uwsgi server. Due to some incompatibilities withwheelyou must installprom2teamsusingsudo pip install --no-binary :all: prom2teams(https://github.com/pypa/wheel/issues/92)$prom2teams_uwsgi<pathtouwsgiiniconfig>Anduwsgiwould look like:[uwsgi]
master = true
processes = 5
#socket = 0.0.0.0:8001
#protocol = http
socket = /tmp/prom2teams.sock
chmod-socket = 777
vacuum = true
env = APP_ENVIRONMENT=pro
env = APP_CONFIG_FILE=/etc/default/prom2teams.iniConsider not providechdirproperty neithermoduleproperty.Also you can set themodulefile, by doing a symbolic link:sudo mkdir -p /usr/local/etc/prom2teams/ && 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)Another approach is to provide yourself themodulefilemodule exampleand thebinuwsgi calluwsgi exampleNote:default log level is DEBUG. Messages are redirected to stdout. To enable file log, set the env APP_ENVIRONMENT=(pro|pre)Config fileThe config file is anINI fileand should have the structure described below:[Microsoft Teams]# At least one connector is required hereConnector:<webhook url>AnotherConnector:<webhook url>...[HTTP Server]Host:<host ip># default: localhostPort:<host port># default: 8089[Log]Level:<loglevel (DEBUG|INFO|WARNING|ERROR|CRITICAL)># default: DEBUGPath:<log file path># default: /var/log/prom2teams/prom2teams.log[Template]Path:<Jinja2 template path># default: app resources default template (./prom2teams/resources/templates/teams.j2)[Group Alerts]Field:<Field to group alerts by># alerts won't be grouped by default[Labels]Excluded:<Comma separated list of labels to ignore>[Annotations]Excluded:<Comma separated list of annotations to ignore>[Teams Client]RequestTimeout:<Configures the request timeout># defaults to 30 secsRetryEnable:<Enables teams client retry policy># defaults to falseRetryWaitTime:<Wait time between retries># default: 60 secsMaxPayload:<Teams client payload limit in bytes># default: 24KBNote:Grouping alerts works since v2.2.0Configuring PrometheusThewebhook receiverin Prometheus allows configuring a prom2teams server.The url is formed by the host and port defined in the previous step.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.// The prom2teams endpoint to send HTTP POST requests to.
url: 0.0.0.0:8089/v2/<Connector1>Prom2teams Prometheus metricsProm2teams uses Flask and, to have the service monitored, we use @rycus66'sPrometheus Flask Exporter. This will enable an endpoint in/metricswhere you could find interesting metrics to monitor such as number of responses with a certain status. To enable this endpoint, just either:Use the--enablemetricsor-mflag when launching prom2teams.Set the environment variablePROM2TEAMS_PROMETHEUS_METRICS=true.Templatingprom2teams provides adefault templatebuilt withJinja2to render messages in Microsoft Teams. This template could be overrided using the 'templatepath' argument ('--templatepath ') during the application start.Some fields are considered mandatory when received from Alert Manager.
If such a field is not included a default value of 'unknown' is assigned.All non-mandatory labels not in excluded list are injected inextra_labelskey. All non-mandatory annotations not in excluded list are injected inextra_annotationskey.Alertmanager fingerprints are available in thefingerprintkey.  Fingerprints
are supported by Alertmanager 0.19.0 or greater.DocumentationSwagger UIAccessing to<Host>:<Port>(e.g.localhost:8089) in a web browser shows the API v1 documentation.Accessing to<Host>:<Port>/v2(e.g.localhost:8089/v2) in a web browser shows the API v2 documentation.TestingTo run the test suite you should type the following://Aftercloningprom2teams:)$pipinstall-rrequirements.txt
$python3-munittestdiscovertests
$cdtests/e2e
$./test.shBuilt WithVersioningFor the versions available, see thetags on this repository.Additionaly you can see what change in each version in theCHANGELOG.mdfile.AuthorsIdealista-Work with-idealistaSee also the list ofcontributorswho participated in this project.LicenseThis project is licensed under theApache 2.0license - see theLICENSEfile for details.ContributingPlease readCONTRIBUTING.mdfor details on our code of conduct, and the process for submitting pull requests to us.