guibranco / guibranco/logstream-server
[FEATURE] Metrics and statistics endpoint
- Dominant language
- PHP
- Stars
- 1
- Forks
- 0
- Avg merge
- 1m
- Merged PRs (30d)
- 4
Description
## Summary
Add a `GET /api/stats` endpoint that returns log counts aggregated over configurable time windows, enabling a dashboard overview screen in the UI without loading raw entries.
## Motivation
The current API returns individual log entries. There is no way to get an overview — errors in the last hour, which applications are most active, ingestion rate — without pulling and counting entries client-side.
## Proposed response
```json
{
"period": "1h",
"total": 9342,
"by_level": { "debug": 8000, "info": 1200, "warning": 100, "error": 42 },
"by_app_key": { "billing-api": 3100, "auth-service": 7142 },
"by_source": { "http": 4842, "udp": 4500 },
"top_categories": [["payments", 980], ["auth", 412], ["jobs", 201]],
"ingestion_rate_per_minute": 155.7
}
```
## Query parameters
| Param | Default | Description |
|-------|---------|-------------|
| `period` | `1h` | Time window: `15m`, `1h`, `6h`, `24h`, `7d` |
| `app_key` | (all) | Restrict to a single application |
## Implementation notes
- **File storage**: scan JSONL files for the period and count in PHP
- **MariaDB storage**: `SELECT level, COUNT(*) ... GROUP BY level WHERE timestamp > :from`
- Cache results for 60 seconds to avoid repeated full-table scans
- Auth: `Authorization: Bearer `
## Acceptance criteria
- [ ] `GET /api/stats` returns correct counts for all periods
- [ ] Works for both file and MariaDB storage backends
- [ ] `app_key` filter correctly scopes results
- [ ] Response includes counts by level, app_key, source (http/udp), and top categories
- [ ] Results cached for 60 seconds
- [ ] Unit tests for aggregation logic
- [ ] Integration tests for both storage backends
Contributor guide
Research direction
Start by locating the existing API route registration and the file and MariaDB storage backends, then trace how timestamps, authentication, and caching are handled. Use the proposed response and period/app_key rules as the contract; add unit tests for aggregation and integration tests for both backends. Done means all acceptance criteria pass for both storage modes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- mariadb, php
- Domain
- api, databases, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100