guibranco / guibranco/logstream-server
[FEATURE] Client health monitoring and last-seen tracking
- Dominant language
- PHP
- Stars
- 1
- Forks
- 0
- Avg merge
- 1m
- Merged PRs (30d)
- 4
Description
## Summary
Track when each registered client last sent a log entry and expose a health status endpoint, enabling detection of silent or dead clients without external monitoring.
## Motivation
A client going silent is often an indicator of a deployment failure, crash, or misconfiguration. Currently there is no way to detect this from the logstream-server side.
## Proposed schema change
```sql
ALTER TABLE clients
ADD COLUMN last_seen_at DATETIME NULL DEFAULT NULL,
ADD COLUMN heartbeat_timeout_min INT UNSIGNED NULL DEFAULT NULL;
```
`last_seen_at` is updated on every successful ingestion (HTTP or UDP). `heartbeat_timeout_min` configures the silence threshold.
## New endpoint
```
GET /api/clients/{app_key}/health
Authorization: Bearer
```
Response:
```json
{
"app_key": "billing-api",
"status": "active",
"last_seen": "2026-04-17T16:45:00+00:00",
"last_seen_ago": "3m 22s",
"timeout_minutes": 10
}
```
Status values: `active` | `silent` | `never_seen`
## Alert integration
When `heartbeat_timeout_min` is set and the client goes silent, fire a webhook alert (if the alert system from #1 is configured).
## Acceptance criteria
- [ ] `last_seen_at` updated on every successful HTTP and UDP ingestion
- [ ] `GET /api/clients/{app_key}/health` returns correct status
- [ ] Status is `active`, `silent`, or `never_seen` based on `last_seen_at` and timeout
- [ ] `GET /api/clients` includes `last_seen_at` and `status` per client
- [ ] Integration with alert webhooks when silence threshold exceeded
- [ ] Migration adds new columns
- [ ] Unit tests for status calculation logic
Contributor guide
Research direction
Start by locating the client schema and migration, the HTTP and UDP ingestion entry points, the client-list and API routing code, and the alert webhook integration. Trace how successful ingestion is recorded and how client responses are built, then add focused tests for status calculation and verify each acceptance criterion, including migration and both ingestion paths.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- api, backend, databases
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100