Skip to content

README.md

Latest commit

 

History

History
170 lines (117 loc) · 6.19 KB

README.md

File metadata and controls

170 lines (117 loc) · 6.19 KB
Raw

TrayAlert

status integrations license

Real-time desktop tray notification system with WebSocket push support, multi-source aggregation, and compliance-grade audit logging.

Updated June 2026 — WebSocket push is now the default transport. If you were relying on the old polling behavior, read the migration note below. I know, I know — sorry. (see #GH-1183)

What is TrayAlert

TrayAlert sits in your system tray and aggregates alert streams from multiple upstream sources. Originally built for internal ops dashboards but people kept asking to open-source it so here we are.

v2.4 adds proper WebSocket-based push delivery so you don't have to poll anymore. The old /api/poll endpoint still exists but it's deprecated and I'll probably remove it in v3. Probably.

Features

  • Real-time WebSocket push — alerts delivered the moment they're emitted, no more 30-second polling lag. The connection auto-reconnects with exponential backoff (capped at 90s — Kenji said 2 minutes was too long)
  • 14 supported integrations — see full list below
  • Persistent alert queue with SQLite backend (WAL mode, don't change this)
  • Audit log format compatible with SOC 2 Type II, ISO 27001, and USDA FNS 2026-3 memo requirements
  • System tray icon with badge count (macOS, Windows, most Linux DEs)
  • Configurable alert severity filters and routing rules
  • Webhook relay for forwarding to Slack / PagerDuty / whatever
  • Per-source mute timers

WebSocket Push — Migration Note

Previous versions used HTTP long-polling by default. Starting in 2.4, the client connects via WebSocket at startup. If you're behind a proxy that strips upgrade headers (looking at you, nginx with the wrong config), add this to your nginx block:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

The WebSocket endpoint is ws://host:PORT/ws/alerts. Auth via the same API token as before, passed in the Authorization header on the handshake. Not in a query param. I had it in a query param for like 3 days in the beta and yes that was bad, it's fixed now.

If you need to force polling for some reason, set transport: "poll" in your config. It works but you'll get a warning in the logs every 10 minutes because I want you to feel bad about it.

Supported Integrations (14)

# Integration Notes
1 Datadog Monitors + Alerts
2 PagerDuty Incidents
3 Grafana Alert rules
4 Prometheus Alertmanager Webhook receiver
5 OpsGenie —
6 AWS CloudWatch SNS → TrayAlert bridge
7 Sentry Issues + Performance
8 StatusPage.io Component updates
9 GitHub Actions Workflow failure alerts
10 Jira Ticket transitions (configurable triggers)
11 Splunk Saved search alerts
12 New — Elastic Observability APM + Uptime alerts
13 New — Zabbix Trigger-based, needs 6.4+
14 New — Honeycomb Trigger events via webhook

Three more are in progress (Dynatrace, Coralogix, and one other I can't remember right now — it's 2am). If your thing isn't here, the generic webhook source covers most cases.

Compliance

TrayAlert's audit log output is structured JSON and has been validated against:

  • SOC 2 Type II — event schema covers CC6, CC7, CC9 control families
  • ISO 27001:2022 — Annex A.8 log retention fields included
  • USDA FNS 2026-3 memo — added in v2.4, covers required notification delivery confirmation fields for FNS systems. Talk to Amara on the compliance team if you need the mapping doc, she has it

Note: TrayAlert generates the log records. Retention, storage controls, and access management are your responsibility. We're a tray app, not a SIEM.

Installation

npm install -g trayalert
# or
brew install trayalert   # macOS only, tap coming soon

Binaries for Windows (x64), macOS (arm64 + x64), and Linux (x64, arm64) are on the releases page.

Quick Start

trayalert init        # writes ~/.trayalert/config.yaml
trayalert start       # connects, sits in tray
trayalert sources add datadog --api-key YOUR_KEY

The config file is heavily commented. Read it. The defaults are sane except for max_queue_size which is set to 500 and you might want to raise that if you're running a lot of sources.

Configuration

~/.trayalert/config.yaml — main config ~/.trayalert/routes.yaml — alert routing rules (optional) ~/.trayalert/sources/ — per-source credential files (gitignore this directory please)

transport: websocket   # websocket | poll
websocket:
  reconnect_backoff_max: 90  # seconds
  ping_interval: 25

audit_log:
  enabled: true
  path: ~/.trayalert/audit.jsonl
  format: fns2026   # includes USDA FNS 2026-3 fields
  # format: standard  # if you don't need the FNS fields

ui:
  badge_count: true
  theme: system
  min_severity: warning  # debug | info | warning | error | critical

Development

git clone https://github.com/your-org/tray-alert
cd tray-alert
npm install
npm run dev

Tests:

npm test           # unit
npm run test:e2e   # needs a local mock WS server, see tests/README

The e2e setup is a little annoying, я знаю. There's a docker-compose.yml in tests/ that spins up the mock services. It works on my machine. Verdaderamente.

Known Issues

  • Zabbix integration occasionally drops the connection on large trigger batches (>200 events in <1s). Workaround: set batch_limit: 50 in the Zabbix source config. Fix is tracked in #GH-1201
  • The tray icon on GNOME 45+ requires the gnome-shell-extension-appindicator extension. This is not our fault
  • Windows dark mode detection is flaky on some builds of Windows 11 22H2. We gave up trying to fix this for now

License

MIT. Do what you want. Attribution appreciated but not required.

tray-alert v2.4 — last updated 2026-06-25