[caronc]

Description

Related issue (if applicable): #

Adds Better Stack support. Apprise can now raise Better Stack incidents that alert whoever is on call, or send entries to a Better Stack log source.

Better Stack Notifications

• Source: https://betterstack.com
• Image Support: No
• Attachment Support: No
• Message Format: Plain Text
• Message Limit: 32768 characters

Better Stack combines uptime monitoring, on-call alerting and log management. Apprise supports two modes and picks one from the URL you use:

• Incidents raise an incident that alerts whoever is on call.
• Logs add an entry to a log source.

Account Setup

Incidents:

1. Sign in to Better Stack and open API tokens.
2. Select your team and copy (or create) a token in the Uptime API tokens section.
3. Better Stack also needs the e-mail address of a user on your account. It is shown as the person who requested the incident.

A global API token works across all of your teams. When you use one, name the team(s) in the URL.

Logs:

1. Sign in to Better Stack Telemetry and create (or open) a source of the type HTTP.
2. Copy the Source token and the Ingesting host shown for that source.

Syntax

Valid syntax is as follows:

• betterstack://{token}/{email}
• betterstack://{token}/{email}/{team}
• betterstack://{token}/{email}/{team1}/{team2}/{teamN}
• betterstack://{source_token}@{ingesting_host}

Parameter Breakdown

Variable	Required	Description
token	Yes	Your Better Stack API token (incidents) or source token (logs).
email	*Yes	The e-mail address of a user on your Better Stack account. Better Stack shows it as the person who requested the incident. Incidents only. You can also set it with ?from=.
team	No	The team that should receive the incident. Only needed with a global API token. Each team you list gets its own incident. You can also set teams with ?to=.
ingesting_host	Yes	The ingesting host shown on your log source, such as s1234.eu-nbg-2.betterstackdata.com. Logs only.
alert	No	How Better Stack alerts the on-call person. Use any of call, sms, email, push and critical, separated by commas. Methods you leave out are switched off. When this is not set, your team settings decide. Incidents only.
policy	No	The ID of the escalation policy to use. Incidents only.
team_wait	No	How many seconds to wait before alerting the whole team. Incidents only.

Examples

Raise an incident:

apprise -vv -t "Database down" -b "The primary database is not responding" \
    "betterstack://abc123def456/me@example.com"

Raise an incident for two teams using a global API token, and alert by phone call and SMS:

apprise -vv -t "Database down" -b "The primary database is not responding" \
    "betterstack://abc123def456/me@example.com/Operations/Database%20Team?alert=call,sms"

Send a log entry:

apprise -vv -t "Backup" -b "Nightly backup finished" \
    "betterstack://srcToken123@s1234.eu-nbg-2.betterstackdata.com"

New Service Completion Status

• apprise/plugins/betterstack.py
• pyproject.toml
• README.md
• packaging/redhat/python-apprise.spec

Checklist

• Documentation ticket created (if applicable): apprise-docs/153
• The change is tested and works locally.
• No commented-out code in this PR.
• No lint errors (use tox -e lint and optionally tox -e format).
• Test coverage added or updated (use tox -e qa).

Testing

Anyone can help test as follows:

# Create a virtual environment
python3 -m venv apprise

# Change into our new directory
cd apprise

# Activate our virtual environment
source bin/activate

# Install the branch
pip install git+https://github.com/caronc/apprise.git@better-stack-support

# If you have cloned the branch and have tox available to you:
tox -e apprise -- -t "Test Title" -b "Test Message" \
    "betterstack://{token}/{email}"

tox -e apprise -- -t "Test Title" -b "Test Message" \
    "betterstack://{source_token}@{ingesting_host}"

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (8b89b08) to head (eff5c4b).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##            master     #1819    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files          252       254     +2     
  Lines        40893     41207   +314     
  Branches      7040      7107    +67     
==========================================
+ Hits         40893     41207   +314     

Files with missing lines	Coverage Δ
apprise/plugins/betterstack.py	100.00% <100.00%> (ø)

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.