Skip to content

Commit 93c9f3f

Browse files
gmathy2104claude
gmathy2104
and
claude
committed
docs(v2.8.1): comprehensive documentation for system logs API
Complete documentation suite for the new system logs endpoints: ## Documentation Updates ### 1. README.md - Added v2.8.1 feature announcement at the top - Added "Advanced Features (v2.8.1)" section with: * System Logs API overview * Log retrieval endpoint examples (curl) * Real-time streaming endpoint examples (JavaScript) * Complete response format documentation * Use cases for remote debugging and monitoring ### 2. docs/api-reference.md - Updated API version to v2.8.1 - Added comprehensive documentation for both endpoints: * GET /v1/system/logs - with query parameters, examples in bash/Python * GET /v1/system/logs/stream - with SSE examples in JavaScript/Python/curl - Included usage notes about EventSource limitations - Updated support section with new log access options ### 3. docs/examples.md (NEW) - Created comprehensive examples document with: * Quick start examples * System monitoring scripts (Python temperature/WiFi monitoring) * Camera control examples (night mode, resolution switching) * Log monitoring examples (error alerts, web dashboard) * Complete use cases: - 24/7 security camera with health monitoring - Timelapse with auto-exposure * Best practices for error handling and resource cleanup ### 4. pi-camera-api-collection.json (NEW) - Created Postman/Insomnia API collection with: * Environment variables for base_url and api_key * Complete system endpoints folder with all logs endpoints * Camera status, streaming, configuration folders * Pre-configured examples for: - Get system logs with various filters - Stream logs in real-time - Error log filtering - Log search patterns * Detailed descriptions for each endpoint ### 5. CHANGELOG.md - Added v2.8.1 release entry with: * Feature overview and problem/solution/impact * Detailed endpoint documentation * Implementation details * Benefits and use cases * Code examples in bash/JavaScript/Python * Documentation updates list ## Why This Documentation Matters For developers (human or AI) working on this project: - **Quick Start**: README provides immediate examples - **API Reference**: Complete technical specifications - **Examples**: Real-world integration patterns - **Collection**: Instant API testing capability - **Changelog**: Historical context and usage patterns ## Documentation Quality - ✅ Consistent formatting across all files - ✅ Working code examples (bash, Python, JavaScript) - ✅ Use case scenarios with complete scripts - ✅ Best practices and gotchas documented - ✅ Cross-references between documents - ✅ Suitable for both human developers and AI assistants 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent f2184d3 commit 93c9f3f

File tree

5 files changed

+1490
-8
lines changed

5 files changed

+1490
-8
lines changed

‎CHANGELOG.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,120 @@ All notable changes to Pi Camera Service will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [2.8.1] - 2025-11-23
9+
10+
### Added
11+
12+
#### System Logs API with Real-Time Streaming
13+
- **NEW FEATURE**: Remote access to service logs via HTTP API without requiring SSH access
14+
- **Problem Solved**: Debugging and monitoring required SSH access to Raspberry Pi, limiting remote troubleshooting capabilities
15+
- **Solution**: HTTP API endpoints for log retrieval with filtering and real-time streaming via Server-Sent Events (SSE)
16+
- **Impact**: Full remote debugging and monitoring capabilities for production deployments
17+
18+
#### New System Logs Endpoints
19+
20+
**1. `GET /v1/system/logs` - Log Retrieval with Filtering**
21+
- Query recent logs (1-10,000 lines, default: 100)
22+
- Filter by log level: INFO, WARNING, ERROR
23+
- Search by keyword/pattern
24+
- Returns JSON with log lines, count, and service name
25+
- Examples:
26+
- `?lines=50` - Get last 50 lines
27+
- `?level=ERROR&lines=100` - Filter ERROR logs
28+
- `?search=resolution&lines=200` - Search for pattern
29+
- `?lines=500&level=ERROR&search=camera` - Combined filters
30+
31+
**2. `GET /v1/system/logs/stream` - Real-Time Log Streaming (SSE)**
32+
- Server-Sent Events for continuous log monitoring
33+
- Same filtering capabilities as retrieval endpoint (level, search)
34+
- Auto-cleanup on client disconnect (no orphaned processes)
35+
- Perfect for live debugging dashboards
36+
- Examples:
37+
- Stream all logs in real-time
38+
- Stream only ERROR logs: `?level=ERROR`
39+
- Stream logs matching pattern: `?search=camera`
40+
41+
#### Implementation Details
42+
- Uses `journalctl` to read systemd service logs
43+
- No `sudo` required (service can read its own logs)
44+
- Async subprocess management using `asyncio.create_subprocess_exec`
45+
- Proper cleanup to prevent orphaned `journalctl` processes
46+
- Added `LogsResponse` Pydantic model for structured responses
47+
- Fixed `StreamingResponse` import conflict (renamed to `FastAPIStreamingResponse`)
48+
49+
### Changed
50+
- API version bumped from 2.8.0 to 2.8.1
51+
- `camera_service/api.py`:
52+
- Added `asyncio`, `subprocess` imports
53+
- Added `Query` parameter support
54+
- Renamed `StreamingResponse` import to avoid conflict with Pydantic model
55+
- Added `LogsResponse` model
56+
- Added two new system endpoints for logs
57+
58+
### Benefits
59+
- **Remote Debugging**: Access logs from anywhere without SSH
60+
- **Real-Time Monitoring**: Build live monitoring dashboards
61+
- **Error Detection**: Filter and alert on ERROR logs instantly
62+
- **Audit Trail**: Track camera operations and configuration changes
63+
- **Client Integration**: Embed log viewers in web/mobile apps
64+
65+
### Use Cases
66+
67+
**1. Remote Debugging**:
68+
```bash
69+
# Get last 100 ERROR logs
70+
curl -H "X-API-Key: your-key" \
71+
"http://<PI_IP>:8000/v1/system/logs?level=ERROR&lines=100"
72+
```
73+
74+
**2. Live Log Monitoring (JavaScript)**:
75+
```javascript
76+
const eventSource = new EventSource('http://<PI_IP>:8000/v1/system/logs/stream?level=ERROR');
77+
eventSource.onmessage = (event) => {
78+
console.log('New error:', event.data);
79+
// Send alert, update UI, etc.
80+
};
81+
```
82+
83+
**3. Search Configuration Changes**:
84+
```bash
85+
# Find all resolution changes
86+
curl -H "X-API-Key: your-key" \
87+
"http://<PI_IP>:8000/v1/system/logs?search=resolution&lines=500"
88+
```
89+
90+
**4. Monitor Service Health**:
91+
```python
92+
# Python script to monitor and alert on errors
93+
import requests
94+
95+
url = "http://<PI_IP>:8000/v1/system/logs/stream"
96+
params = {"level": "ERROR"}
97+
headers = {"X-API-Key": "your-key"}
98+
99+
with requests.get(url, headers=headers, params=params, stream=True) as response:
100+
for line in response.iter_lines():
101+
if line and line.startswith(b'data: '):
102+
log_line = line[6:].decode('utf-8')
103+
send_alert(log_line) # Your alert function
104+
```
105+
106+
### Documentation
107+
- Updated README.md with v2.8.1 feature announcement
108+
- Enhanced `docs/api-reference.md` with comprehensive logs endpoint documentation
109+
- Created `docs/examples.md` with practical use cases and integration examples
110+
- Created `pi-camera-api-collection.json` (Postman/Insomnia collection)
111+
112+
### Technical Details
113+
- Zero breaking changes - all new endpoints are additions
114+
- Logs endpoint uses journalctl (standard on systemd systems)
115+
- SSE streaming uses async I/O for efficient resource usage
116+
- Proper subprocess cleanup on client disconnect
117+
- Works with or without API key authentication
118+
- Fully backwards compatible with existing clients
119+
120+
---
121+
8122
## [2.8.0] - 2025-11-23
9123

10124
### Added

‎README.md‎

Lines changed: 68 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,17 @@
22

33
Production-ready **FastAPI** microservice for controlling Raspberry Pi Camera (libcamera/Picamera2) with **H.264 streaming** to **MediaMTX** via RTSP.
44

5-
**Version 2.8.0** - Camera configuration transparency with advanced controls status tracking!
5+
**Version 2.8.1** - System logs API with real-time streaming for remote debugging!
66

7-
[![Version](https://img.shields.io/badge/version-2.8.0-blue.svg)](https://github.com/gmathy2104/pi-camera-service/releases)
7+
[![Version](https://img.shields.io/badge/version-2.8.1-blue.svg)](https://github.com/gmathy2104/pi-camera-service/releases)
88
[![Python](https://img.shields.io/badge/python-3.9+-green.svg)](https://www.python.org/)
99
[![FastAPI](https://img.shields.io/badge/FastAPI-0.121+-teal.svg)](https://fastapi.tiangolo.com/)
1010
[![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)
1111
[![Tests](https://github.com/gmathy2104/pi-camera-service/workflows/Tests/badge.svg)](https://github.com/gmathy2104/pi-camera-service/actions)
1212

13-
> 🔥 **New in v2.8.0**: **Advanced Controls Status Tracking** - Camera status endpoint now exposes all advanced control settings in real-time (EV compensation, noise reduction mode, AE constraint/exposure modes). Perfect for debugging and monitoring camera configuration!
13+
> 🔥 **New in v2.8.1**: **System Logs API** - Remote log access via `/v1/system/logs` with filtering (lines, level, search) + real-time streaming via Server-Sent Events (SSE) at `/v1/system/logs/stream`. Perfect for remote debugging and monitoring!
14+
>
15+
> 🔥 **v2.8.0**: **Advanced Controls Status Tracking** - Camera status endpoint now exposes all advanced control settings in real-time (EV compensation, noise reduction mode, AE constraint/exposure modes). Perfect for debugging and monitoring camera configuration!
1416
>
1517
> 🔥 **v2.7.0**: **Wide-Angle Camera Detection** - Automatic detection of Camera Module 3 Wide (120° FOV). Intelligent sensor mode selection preserves full wide-angle field of view at all resolutions. New API fields expose camera type, sensor modes, and recommended resolutions!
1618
>
@@ -336,6 +338,69 @@ Monitor your Raspberry Pi's health in real-time alongside camera operations:
336338
- Track resource usage for optimization
337339
- Verify system stability for 24/7 deployments
338340

341+
### Advanced Features (v2.8.1) 🆕
342+
343+
#### 📋 System Logs API with Real-Time Streaming
344+
345+
Remote access to service logs for debugging and monitoring without SSH access:
346+
347+
- **Log Retrieval with Filtering**
348+
- Query recent logs (1-10,000 lines, default: 100)
349+
- Filter by log level (INFO, WARNING, ERROR)
350+
- Search by keyword/pattern
351+
- Returns JSON with log lines and metadata
352+
- **Endpoint**: `GET /v1/system/logs`
353+
354+
- **Real-Time Log Streaming (SSE)**
355+
- Server-Sent Events for continuous log monitoring
356+
- Same filtering capabilities as retrieval endpoint
357+
- Auto-cleanup on client disconnect
358+
- Perfect for live debugging dashboards
359+
- **Endpoint**: `GET /v1/system/logs/stream`
360+
361+
**Example - Get last 50 logs**:
362+
```bash
363+
curl "http://<PI_IP>:8000/v1/system/logs?lines=50"
364+
```
365+
366+
**Example - Filter ERROR logs**:
367+
```bash
368+
curl "http://<PI_IP>:8000/v1/system/logs?level=ERROR&lines=100"
369+
```
370+
371+
**Example - Search for specific events**:
372+
```bash
373+
curl "http://<PI_IP>:8000/v1/system/logs?search=resolution&lines=200"
374+
```
375+
376+
**Example - Real-time streaming (JavaScript)**:
377+
```javascript
378+
const eventSource = new EventSource('http://<PI_IP>:8000/v1/system/logs/stream?level=ERROR');
379+
eventSource.onmessage = (event) => {
380+
console.log('Log:', event.data);
381+
// Update UI with new log entries
382+
};
383+
```
384+
385+
**Response Format**:
386+
```json
387+
{
388+
"logs": [
389+
"Nov 23 17:41:20 picam pi-camera-service[21852]: 2025-11-23 17:41:20,623 - camera_service.api - INFO - === Pi Camera Service Starting ===",
390+
"Nov 23 17:41:20 picam pi-camera-service[21852]: 2025-11-23 17:41:20,754 - camera_service.streaming_manager - INFO - Starting RTSP streaming to rtsp://127.0.0.1:8554/cam"
391+
],
392+
"total_lines": 2,
393+
"service": "pi-camera-service"
394+
}
395+
```
396+
397+
**Use Cases**:
398+
- Remote debugging without SSH access
399+
- Monitor service health and errors in real-time
400+
- Build monitoring dashboards with live log feeds
401+
- Troubleshoot issues from web/mobile apps
402+
- Audit camera operations and configuration changes
403+
339404
The video stream is published to MediaMTX, which then serves it via **RTSP / WebRTC / HLS**.
340405

341406
---

0 commit comments

Comments
 (0)