guibranco / guibranco/logstream-server

[FEATURE] Client health monitoring and last-seen tracking

Open
#62 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

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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.