alerta is the unified command-line tool, terminal GUI and Python SDKfor the alerta monitoring system.
It can be used to send and query alerts, tag alerts and change alert status,delete alerts, dump alert history or see the raw alert data. It can also beused to send heartbeats to the alerta server, and generate alerts based onmissing or slow heartbeats.
Installation
The alerta client tool can be installed using pip:
$ pip install alerta
Or, by cloning the git repository:
$ git clone https://github.com/alerta/python-alerta-client.git$ cd python-alerta-client$ pip install .
Configuration
Options can be set in a configuration file, as environment variables oron the command line. Profiles can be used to easily switch between differentconfiguration settings.
Option | Config File | Environment Variable | Optional Argument | Default |
|---|---|---|---|---|
file | n/a |
|
|
|
profile | profile |
|
| None |
endpoint | endpoint |
|
|
|
key | key |
| n/a | None |
timezone | timezone | n/a | n/a | Europe/London |
timeout | timeout | n/a | n/a | 5s TCP connection timeout |
ssl verify | sslverify |
| n/a | verify SSL certificates |
output | output | n/a |
| text |
color | color |
|
| color on |
debug | debug |
|
| no debug |
Note
The profile option can only be set in the [DEFAULT] section.
Example
Configuration file ~/.alerta.conf:
[DEFAULT]timezone = Australia/Sydneyoutput = json[profile development]endpoint = https://localhost:8443key = demo-keysslverify = offtimeout = 10.0debug = yes
Set environment variables:
$ export ALERTA_CONF_FILE=~/.alerta.conf$ export ALERTA_DEFAULT_PROFILE=production
Use production configuration settings by default:
$ alerta query
Switch to development configuration settings when required:
$ alerta --profile development query
Precedence
Command-line configuration options have precedence over environmentvariables, which have precedence over the configuration file. Withinthe configuration file, profile-specific sections have precedence overthe [DEFAULT] section.
Authentication
If the Alerta API enforces authentication, then the alerta command-linetool can be configured to present an API key or login to the API beforeaccessing secured endpoints.
API Keys
API keys can be generated in the web UI, or by an authenticated user usingthe alerta CLI, and should be added to the configuration file as the “key”setting as shown in the following example:
[profile production]endpoint = https://api.alerta.iokey = LMvzLsfJyGpSuLmaB9kp-8gCl4I3YZkV4i7IGb6S
OAuth Login
Alternatively, a user can “login” to the API and retrieve a Bearer token ifthe Alerta API is configured to use either basic, github, gitlabor google as the authentication provider. No additional settings arerequired but before running any commands the user must login first:
$ alerta login
Commands
The alerta tool is invoked by specifying a command using thefollowing format:
$ alerta [OPTIONS] COMMAND [ARGS]...
Alert Commands
The following group of commands are related to sending, querying and managingthe status of alerts.
send - Send an alert
Send an alert.
$ alerta send [OPTIONS]Options:-r, --resource RESOURCE Resource under alarm-e, --event EVENT Event name-E, --environment ENVIRONMENT Environment eg. Production, Development-s, --severity SEVERITY Severity eg. critical, major, minor, warning-C, --correlate EVENT List of related events eg. node_up, node_down-S, --service SERVICE List of affected services eg. app name, Web, Network, Storage, Database, Security-g, --group GROUP Group event by type eg. OS, Performance-v, --value VALUE Event value-t, --text DESCRIPTION Description of alert-T, --tag TAG List of tags eg. London, os:linux, AWS/EC2-A, --attributes KEY=VALUE List of attributes eg. priority=high-O, --origin ORIGIN Origin of alert in form app/host--type EVENT_TYPE Event type eg. exceptionAlert, performanceAlert, nagiosAlert--timeout SECONDS Seconds before an open alert will be expired--raw-data STRING Raw data of orignal alert eg. SNMP trap PDU. '@' to read from file, '-' to read from stdin--customer STRING Customer-h, --help Show this message and exit.
The only mandatory options are resource and event. All the others willbe set to sensible defaults.
Attention
If the reject plugin is enabled (which it is bydefault) then alerts must have an environment attribute thatis one of either Production or Development and it mustdefine a service attribute. For more information on configuringor disabling this plugin see plugin config.
Attribute | Default |
|---|---|
environment | empty string |
severity |
|
correlate | empty list |
status |
|
service | empty list |
group |
|
value |
|
text | empty string |
tags | empty list |
attributes | empty dictionary |
origin | program/host |
type |
|
timeout | 86400 (1 day) |
raw data | empty string |
Examples
To send a minor alert followed by a normal alert that correlates:
$ alerta send --resource web01 --event HttpError --correlate HttpOK --group Web --severity minor$ alerta send --resource web01 --event HttpOK --correlate HttpError --group Web --severity normal
To send an alert with custom attribute called region:
$ alerta send -r web01 -e HttpError -g Web -s major --attributes region="EU"
query - Search for alerts
Query for alerts based on search filter criteria.
Examples
To query for major and minor open alerts for the Production environment of the Mobile API service:
$ alerta query --filter severity=major --filter severity=minor --filter status=open --filter environment=Production --filter service="Mobile API"
To query for all alerts with “disk” in the alert text:
$ alerta query --filter text=~disk
ack - Acknowledge alerts
Acknowlege alerts ie. change alert status to ack
close - Close alerts
Close alerts ie. change alert status to closed.
unack - Un-acknowledge alerts
Unacknowledge alerts ie. change alert status to open.
shelve - Shelve alerts
Shelve alerts ie. change alert status to shelved which removes thealerts from the active console and prevents any further notifications.
unshelve - Un-shelve alerts
Unshelve alerts ie. change alert status to open which returns thealerts to the active console and does not prevent future notifications.
tag - Tag alerts
Add tags to alerts.
untag - Untag alerts
Remove tags from alerts.
update - Update alert attributes
Update alert attributes.
delete - Delete alerts
Delete alerts.
watch - Watch alerts
Watch for new alerts.
top - Show top offenders and stats
Display alerts like unix “top” command.
raw - Show alert raw data
Show raw data for alerts.
history - Show alert history
Show action, status, severity and value changes for alerts.
Blackout Commands
The following group of commands are related to creating andmanaging alert suppressions using blackouts.
blackout - Suppress alerts
blackout Suppress alerts
blackouts - List alert suppressions
blackouts List alert suppressions
Heartbeat Commands
The following group of commands are related to creating andmanaging heartbeats.
heartbeat - Send a heartbeat
Send or delete a heartbeat.
$ alerta heartbeat [OPTIONS]Options: -O, --origin ORIGIN Origin of heartbeat. -E, --environment ENVIRONMENT Environment eg. Production, Development -s, --severity SEVERITY Severity eg. critical, major, minor, warning -S, --service SERVICE List of affected services eg. app name, Web, Network, Storage, Database, Security -g, --group GROUP Group event by type eg. OS, Performance -T, --tag TAG List of tags eg. London, os:linux, AWS/EC2 --timeout SECONDS Seconds before heartbeat is stale --customer STRING Customer -D, --delete ID Delete hearbeat using ID -h, --help Show this message and exit.
Note
The “environment”, “severity”, “service” and “group” values are onlyused when heartbeat alerts are generated from slow or stale heartbeats.
heartbeats - List heartbeats
List heartbeats and generate heartbeat alerts.
$ alerta heartbeats [OPTIONS]Options: --alert Alert on stale or slow heartbeats -s, --severity SEVERITY Severity for stale heartbeat alerts --timeout SECONDS Seconds before a stale heartbeat alert will be expired --purge Delete all stale heartbeats -h, --help Show this message and exit.
Alerts can be generated from stale or slow heartbeats usingthe --alert option. It is expected that this would be runat regular intervals using a scheduling service such as cron.
Tags can be used to set the environment or group of a heartbeatalert using the format environment:[ENV] and group:[GRP]. Thesetags will be visible in the heartbeat but removed as tags from the alert.
Example
To send a major alert with an environment of Infra in the Networkgroup when a heartbeat is missed or slow for an origin called system1:
$ alerta heartbeat -O system1 -T environment:Infra -T group:Network --timeout 10(wait >10 seconds)$ alerta heartbeats --alert --severity major
API Key Commands
The following group of commands are related to creating andmanaging API keys.
key - Create API key
key Create API key
Important
To prevent privilege escalation it is not possible to create an API keywith associated roles that are greater than that with which that API keyhas.
keys - List API keys
keys List API keys
revoke - Revoke API key
revoke Revoke API key
User Commands
The following group of commands are related to creating andmanaging users.
user - Update user
user Update user
users - List users
users List users
me - Update current user
me Update current user
Permissions Commands
The following group of commands are related to creating andmanaging roles, permissions and access control.
perm - Add role-permission lookup
perm Add role-permission lookup
perms - List role-permission lookups
perms List role-permission lookups
Customer Commands
The following group of commands are related to creating andmanaging customers.
customer - Add customer lookup
customer Add customer lookup
customers - List customer lookups
customers List customer lookups
Auth Commands
The following group of commands are related to authentication.
signup - Sign-up new user
signup Sign-up new user
login - Login with user credentials
login Login with user credentials
logout - Clear login credentials
logout Clear login credentials
whoami - Display current logged in user
whoami Display current logged in user
token - Display current auth token
token Display current auth token
Admin Commands
The following group of commands are related to administration.
status - Display status and metrics
Display API server switch status and usage metrics.
$ alerta statusMETRIC TYPE NAME VALUE AVERAGE--------------------------- ------- ------------------------- ------- -----------Total alerts gauge alerts.total 993Rejected alerts counter alerts.rejected 22Alert queries timer alerts.queries 9132459 128.713Pre-receive plugins timer plugins.prereceive 10889 0.0383874Newly created alerts timer alerts.create 4442 5.06123Post-receive plugins timer plugins.postreceive 10867 0.0149995Received alerts timer alerts.received 15376 23.4729Duplicate alerts timer alerts.duplicate 9167 8.26061Correlated alerts timer alerts.correlate 429 20.9068Tagging alerts timer alerts.tagged 246 35.5935Alert status change timer alerts.status 687 88.2969Deleted alerts timer alerts.deleted 8 120.25Removing tags from alerts timer alerts.untagged 52 22.2308Count alerts timer alerts.counts 4388289 23.9553Alerta console auto-refresh text switch.auto-refresh-allow ONAPI alert submission text switch.sender-api-allow ON
config - Display remote client config
Display client config downloaded from API server.
$ alerta configaudio : {}auth_required : Trueclient_id : 736147134702-glkb1pesv716j1utg4llg7c3rr7nnhli.apps.googleusercontent.comcolors : {}customer_views : Truedates : {'longDate': 'EEEE, MMMM d, yyyy h:mm:ss.sss a (Z)', 'mediumDate': 'medium', 'shortTime': 'shortTime'}endpoint : https://api.alerta.devgithub_url : Nonegitlab_url : https://gitlab.comkeycloak_realm : Nonekeycloak_url : Nonepingfederate_url : Noneprovider : googlerefresh_interval : 5000severity : {'cleared': 5, 'critical': 1, 'debug': 7, 'indeterminate': 5, 'informational': 6, 'major': 2, 'minor': 3, 'normal': 5, 'ok': 5, 'security': 0, 'trace': 8, 'unknown': 9, 'warning': 4}signup_enabled : Truetracking_id : UA-44644195-5housekeeping - Expired and clears old alerts
Trigger the expiration and deletion of alerts.
uptime - Display server uptime
Show how long the Alerta API has been running.
$ alerta uptime01:06 up 0 days 16:15
version - Display version info
Show version information for alerta and dependencies.
$ alerta versionalerta 6.0.0alerta client 6.0.0requests 2.19.1click 7.0
Help Commands
help - Show this help
Show all OPTIONS, COMMANDS and some example FILTERS.
Bugs
Log any issues on GitHub or submit a pull request.
