guibranco / guibranco/logstream-server
[FEATURE] Context field search
- Dominant language
- PHP
- Stars
- 1
- Forks
- 0
- Avg merge
- 1m
- Merged PRs (30d)
- 4
Description
## Summary
Enable searching inside the structured `context` JSON field on log entries, which is currently stored opaque and excluded from all filter operations.
## Motivation
The `context` field carries the most valuable structured data — invoice IDs, user IDs, error codes, request IDs — but it cannot be queried. This is the most common limitation encountered when using the log viewer for debugging.
## Proposed query interface
```
GET /api/logs?context[invoice_id]=1234
GET /api/logs?context[code]=card_declined
GET /api/logs?context_search=card_declined
```
## Implementation
### MariaDB storage
```sql
ALTER TABLE log_entries
ADD COLUMN context_text TEXT GENERATED ALWAYS AS (JSON_UNQUOTE(context)) VIRTUAL,
ADD FULLTEXT INDEX ft_context (context_text);
```
Specific key lookups use `JSON_EXTRACT`:
```sql
WHERE JSON_EXTRACT(context, '$.invoice_id') = :value
```
### File storage
Parse `context` JSON during the search scan. Slower but functional. Document that MariaDB is recommended for context-heavy workloads.
## Acceptance criteria
- [ ] `context[key]=value` filter works for exact key-value matches (MariaDB)
- [ ] `context_search=term` fulltext search across all context values (MariaDB)
- [ ] File storage supports context filtering via JSON parse per entry
- [ ] Migration adds generated column and fulltext index
- [ ] Unit tests for context filter logic
- [ ] Integration tests for both backends
- [ ] OpenAPI spec updated with new query parameters
Contributor guide
Research direction
Start at the GET /api/logs filtering entry point and trace the MariaDB and file-storage search paths. Review the migration, OpenAPI spec, and existing unit and integration tests before deciding where the context filters belong. Done means both query forms work on MariaDB, key filtering works for file storage, the schema change is applied, and tests cover both backends.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- mariadb, php
- Domain
- api, backend, databases, testing
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100