docs: expand documentation with comprehensive tools and development guides
- Add detailed documentation for various tools and management interfaces - Create development best practices and interface documentation - Expand tools section with device management, automation, and event subscription guides - Include configuration, usage examples, and error handling for each tool - Update MkDocs navigation to reflect new documentation structure
This commit is contained in:
jango-blockchained
251
docs/tools/events/sse-stats.md
Normal file
251
docs/tools/events/sse-stats.md
Normal file
@@ -0,0 +1,251 @@
|
||||
# SSE Statistics Tool
|
||||
|
||||
The SSE Statistics tool provides functionality to monitor and analyze Server-Sent Events (SSE) connections and performance in your Home Assistant MCP instance.
|
||||
|
||||
## Features
|
||||
|
||||
- Monitor active SSE connections
|
||||
- Track connection statistics
|
||||
- Analyze event delivery
|
||||
- Monitor resource usage
|
||||
- Connection management
|
||||
- Performance metrics
|
||||
- Historical data
|
||||
- Alert configuration
|
||||
|
||||
## Usage
|
||||
|
||||
### REST API
|
||||
|
||||
```typescript
|
||||
GET /api/sse/stats
|
||||
GET /api/sse/connections
|
||||
GET /api/sse/connections/{connection_id}
|
||||
GET /api/sse/metrics
|
||||
GET /api/sse/history
|
||||
```
|
||||
|
||||
### WebSocket
|
||||
|
||||
```typescript
|
||||
// Get SSE stats
|
||||
{
|
||||
"type": "get_sse_stats"
|
||||
}
|
||||
|
||||
// Get connection details
|
||||
{
|
||||
"type": "get_sse_connection",
|
||||
"connection_id": "required_connection_id"
|
||||
}
|
||||
|
||||
// Get performance metrics
|
||||
{
|
||||
"type": "get_sse_metrics",
|
||||
"period": "1h|24h|7d|30d"
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Get Current Statistics
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/sse/stats', {
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token'
|
||||
}
|
||||
});
|
||||
const stats = await response.json();
|
||||
```
|
||||
|
||||
### Get Connection Details
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/sse/connections/conn_123', {
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token'
|
||||
}
|
||||
});
|
||||
const connection = await response.json();
|
||||
```
|
||||
|
||||
### Get Performance Metrics
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/sse/metrics?period=24h', {
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token'
|
||||
}
|
||||
});
|
||||
const metrics = await response.json();
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
### Statistics Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"active_connections": 42,
|
||||
"total_events_sent": 12345,
|
||||
"events_per_second": 5.2,
|
||||
"memory_usage": 128974848,
|
||||
"cpu_usage": 2.5,
|
||||
"uptime": "PT24H",
|
||||
"event_backlog": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Connection Details Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"connection": {
|
||||
"id": "conn_123",
|
||||
"client_id": "client_456",
|
||||
"user_id": "user_789",
|
||||
"connected_at": "2024-02-05T12:00:00Z",
|
||||
"last_event_at": "2024-02-05T12:05:00Z",
|
||||
"events_sent": 150,
|
||||
"subscriptions": [
|
||||
{
|
||||
"event_type": "state_changed",
|
||||
"entity_id": "light.living_room"
|
||||
}
|
||||
],
|
||||
"state": "active",
|
||||
"ip_address": "192.168.1.100",
|
||||
"user_agent": "Mozilla/5.0 ..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Metrics Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"metrics": {
|
||||
"connections": {
|
||||
"current": 42,
|
||||
"max": 100,
|
||||
"average": 35.5
|
||||
},
|
||||
"events": {
|
||||
"total": 12345,
|
||||
"rate": {
|
||||
"current": 5.2,
|
||||
"max": 15.0,
|
||||
"average": 4.8
|
||||
}
|
||||
},
|
||||
"latency": {
|
||||
"p50": 15,
|
||||
"p95": 45,
|
||||
"p99": 100
|
||||
},
|
||||
"resources": {
|
||||
"memory": {
|
||||
"current": 128974848,
|
||||
"max": 536870912
|
||||
},
|
||||
"cpu": {
|
||||
"current": 2.5,
|
||||
"max": 10.0,
|
||||
"average": 3.2
|
||||
}
|
||||
}
|
||||
},
|
||||
"period": "24h",
|
||||
"timestamp": "2024-02-05T12:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Error Codes
|
||||
|
||||
- `404`: Connection not found
|
||||
- `401`: Unauthorized
|
||||
- `400`: Invalid request parameters
|
||||
- `503`: Service overloaded
|
||||
|
||||
### Error Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Error description",
|
||||
"error_code": "ERROR_CODE"
|
||||
}
|
||||
```
|
||||
|
||||
## Monitoring Metrics
|
||||
|
||||
### Connection Metrics
|
||||
- Active connections
|
||||
- Connection duration
|
||||
- Connection state
|
||||
- Client information
|
||||
- Geographic distribution
|
||||
- Protocol version
|
||||
|
||||
### Event Metrics
|
||||
- Events per second
|
||||
- Event types distribution
|
||||
- Delivery success rate
|
||||
- Event latency
|
||||
- Queue size
|
||||
- Backlog size
|
||||
|
||||
### Resource Metrics
|
||||
- Memory usage
|
||||
- CPU usage
|
||||
- Network bandwidth
|
||||
- Disk I/O
|
||||
- Connection pool status
|
||||
- Thread pool status
|
||||
|
||||
## Alert Thresholds
|
||||
|
||||
- Connection limits
|
||||
- Event rate limits
|
||||
- Resource usage limits
|
||||
- Latency thresholds
|
||||
- Error rate thresholds
|
||||
- Backlog thresholds
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Monitor connection health
|
||||
2. Track resource usage
|
||||
3. Set up alerts
|
||||
4. Analyze usage patterns
|
||||
5. Optimize performance
|
||||
6. Plan capacity
|
||||
7. Implement failover
|
||||
8. Regular maintenance
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
- Connection pooling
|
||||
- Event batching
|
||||
- Resource throttling
|
||||
- Load balancing
|
||||
- Cache optimization
|
||||
- Connection cleanup
|
||||
|
||||
## See Also
|
||||
|
||||
- [Event Subscription](subscribe-events.md)
|
||||
- [Device Control](../device-management/control.md)
|
||||
- [Automation Management](../automation/automation.md)
|
||||
253
docs/tools/events/subscribe-events.md
Normal file
253
docs/tools/events/subscribe-events.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# Event Subscription Tool
|
||||
|
||||
The Event Subscription tool provides functionality to subscribe to and monitor real-time events from your Home Assistant instance.
|
||||
|
||||
## Features
|
||||
|
||||
- Subscribe to Home Assistant events
|
||||
- Monitor specific entities
|
||||
- Domain-based monitoring
|
||||
- Event filtering
|
||||
- Real-time updates
|
||||
- Event history
|
||||
- Custom event handling
|
||||
- Connection management
|
||||
|
||||
## Usage
|
||||
|
||||
### REST API
|
||||
|
||||
```typescript
|
||||
POST /api/events/subscribe
|
||||
DELETE /api/events/unsubscribe
|
||||
GET /api/events/subscriptions
|
||||
GET /api/events/history
|
||||
```
|
||||
|
||||
### WebSocket
|
||||
|
||||
```typescript
|
||||
// Subscribe to events
|
||||
{
|
||||
"type": "subscribe_events",
|
||||
"event_type": "optional_event_type",
|
||||
"entity_id": "optional_entity_id",
|
||||
"domain": "optional_domain"
|
||||
}
|
||||
|
||||
// Unsubscribe from events
|
||||
{
|
||||
"type": "unsubscribe_events",
|
||||
"subscription_id": "required_subscription_id"
|
||||
}
|
||||
```
|
||||
|
||||
### Server-Sent Events (SSE)
|
||||
|
||||
```typescript
|
||||
GET /api/events/stream?event_type=state_changed&entity_id=light.living_room
|
||||
```
|
||||
|
||||
## Event Types
|
||||
|
||||
- `state_changed`: Entity state changes
|
||||
- `automation_triggered`: Automation executions
|
||||
- `scene_activated`: Scene activations
|
||||
- `device_registered`: New device registrations
|
||||
- `service_registered`: New service registrations
|
||||
- `homeassistant_start`: System startup
|
||||
- `homeassistant_stop`: System shutdown
|
||||
- Custom events
|
||||
|
||||
## Examples
|
||||
|
||||
### Subscribe to All State Changes
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/events/subscribe', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token',
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
"event_type": "state_changed"
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
### Monitor Specific Entity
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/events/subscribe', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token',
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
"event_type": "state_changed",
|
||||
"entity_id": "light.living_room"
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
### Domain-Based Monitoring
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/events/subscribe', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token',
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
"event_type": "state_changed",
|
||||
"domain": "light"
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
### SSE Connection Example
|
||||
|
||||
```typescript
|
||||
const eventSource = new EventSource(
|
||||
'http://your-ha-mcp/api/events/stream?event_type=state_changed&entity_id=light.living_room',
|
||||
{
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token'
|
||||
}
|
||||
}
|
||||
);
|
||||
|
||||
eventSource.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('Event received:', data);
|
||||
};
|
||||
|
||||
eventSource.onerror = (error) => {
|
||||
console.error('SSE error:', error);
|
||||
eventSource.close();
|
||||
};
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
### Subscription Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"subscription_id": "sub_123",
|
||||
"event_type": "state_changed",
|
||||
"entity_id": "light.living_room",
|
||||
"created_at": "2024-02-05T12:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Event Message Format
|
||||
|
||||
```json
|
||||
{
|
||||
"event_type": "state_changed",
|
||||
"entity_id": "light.living_room",
|
||||
"data": {
|
||||
"old_state": {
|
||||
"state": "off",
|
||||
"attributes": {},
|
||||
"last_changed": "2024-02-05T11:55:00Z"
|
||||
},
|
||||
"new_state": {
|
||||
"state": "on",
|
||||
"attributes": {
|
||||
"brightness": 255
|
||||
},
|
||||
"last_changed": "2024-02-05T12:00:00Z"
|
||||
}
|
||||
},
|
||||
"origin": "LOCAL",
|
||||
"time_fired": "2024-02-05T12:00:00Z",
|
||||
"context": {
|
||||
"id": "context_123",
|
||||
"parent_id": null,
|
||||
"user_id": "user_123"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Subscriptions List Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"subscriptions": [
|
||||
{
|
||||
"id": "sub_123",
|
||||
"event_type": "state_changed",
|
||||
"entity_id": "light.living_room",
|
||||
"created_at": "2024-02-05T12:00:00Z",
|
||||
"last_event": "2024-02-05T12:05:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Error Codes
|
||||
|
||||
- `404`: Event type not found
|
||||
- `401`: Unauthorized
|
||||
- `400`: Invalid subscription parameters
|
||||
- `409`: Subscription already exists
|
||||
- `429`: Too many subscriptions
|
||||
|
||||
### Error Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Error description",
|
||||
"error_code": "ERROR_CODE"
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
- Default limits:
|
||||
- Maximum subscriptions: 100 per client
|
||||
- Maximum event rate: 1000 events per minute
|
||||
- Configurable through environment variables:
|
||||
- `EVENT_SUB_MAX_SUBSCRIPTIONS`
|
||||
- `EVENT_SUB_RATE_LIMIT`
|
||||
- `EVENT_SUB_RATE_WINDOW`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Use specific event types when possible
|
||||
2. Implement proper error handling
|
||||
3. Handle connection interruptions
|
||||
4. Process events asynchronously
|
||||
5. Implement backoff strategies
|
||||
6. Monitor subscription health
|
||||
7. Clean up unused subscriptions
|
||||
8. Handle rate limiting gracefully
|
||||
|
||||
## Connection Management
|
||||
|
||||
- Implement heartbeat monitoring
|
||||
- Use reconnection strategies
|
||||
- Handle connection timeouts
|
||||
- Monitor connection quality
|
||||
- Implement fallback mechanisms
|
||||
- Clean up resources properly
|
||||
|
||||
## See Also
|
||||
|
||||
- [SSE Statistics](sse-stats.md)
|
||||
- [Device Control](../device-management/control.md)
|
||||
- [Automation Management](../automation/automation.md)
|
||||
Reference in New Issue
Block a user