guibranco / guibranco/logstream-server

[FEATURE] Threshold alerts via webhook

Open
#55 0 comments 0 reactions 0 assignees View on GitHub
✨ feature enhancement good first issue hacktoberfest help wanted
Dominant language
PHP
Stars
1
Forks
0
Avg merge
1m
Merged PRs (30d)
4

Description

## Summary

Trigger an outbound HTTP `POST` to a configured URL when a log condition is met, turning logstream-server from a passive store into an active monitoring tool.

## Motivation

Currently there is no way to know when something goes wrong without manually checking the UI or polling the API. Webhook alerts enable proactive incident response.

## Proposed triggers

- More than **N** `error` / `critical` entries from an `app_key` in the last **X** minutes
- A registered client goes silent for more than **Y** minutes (dead client / heartbeat detection)
- Any entry whose `message` matches a configured **PCRE regex**

## Proposed configuration

```json
{
"alerts": [
{
"name": "billing-errors",
"app_key": "billing-api",
"level": "error",
"threshold": 5,
"window_minutes": 5,
"webhook_url": "https://hooks.slack.com/..."
},
{
"name": "pii-pattern",
"message_regex": ".*@hotmail\\.com",
"threshold": 1,
"window_minutes": 1,
"webhook_url": "https://example.com/security-alert"
}
]
}
```

## Webhook payload

```json
{
"alert": "billing-errors",
"triggered": "2026-04-17T16:00:00+00:00",
"count": 7,
"window": "5m",
"app_key": "billing-api",
"sample": {}
}
```

## Implementation notes

- ReactPHP periodic timer (every 30 s) checks aggregate counts
- `ALERT_CONFIG=./alerts.json` env var to enable
- `POST /api/alerts/test/{name}` endpoint to fire a test webhook
- Alert cooldown to prevent repeated firing within the same window

## Acceptance criteria

- [ ] Alert config loaded from `alerts.json` at startup
- [ ] Threshold-based alerts fire correctly
- [ ] Dead client detection fires after configurable silence period
- [ ] Regex-based alerts fire on matching entries
- [ ] Webhook payload contains alert name, timestamp, count, and a sample entry
- [ ] Cooldown prevents repeated alerts within the same window
- [ ] `POST /api/alerts/test/{name}` fires a test payload
- [ ] Unit tests for alert evaluation logic
- [ ] Documentation in `docs/user-guide/alerts.md`

Contributor guide

Open the contributing guide

Research direction

Start by locating the existing configuration and API entry points before designing the alert flow; the issue names ALERT_CONFIG=./alerts.json, a ReactPHP periodic timer, and POST /api/alerts/test/{name}. Done means all listed trigger types, cooldown behavior, webhook payload fields, unit tests, and docs/user-guide/alerts.md are implemented.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
api, backend, observability
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.