guibranco / guibranco/logstream-server

[FEATURE] Metrics and statistics endpoint

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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.