# hoody-proxyLogs Subskill ## Overview ### What This Service Does The `hoody-proxyLogs` service provides access to proxy request/response logs and event logs generated by the Hoody Proxy layer. It enables searching, filtering, and real-time streaming of all traffic that passes through the proxy for a given container. **Core Capabilities:** - **Log Search & Filter** — Query stored request/response and event logs with flexible filtering - **Log Statistics** — Retrieve aggregated metrics and statistics about logged traffic - **Real-time Streaming** — Open persistent SSE connections to receive new log entries as they occur ### When to Use This Service | Scenario | Use This Service | |----------|-----------------| | Debugging failed requests to a container | ✅ Yes | | Monitoring real-time traffic to a service | ✅ Yes | | Analyzing request patterns and response codes | ✅ Yes | | Auditing proxy-level events | ✅ Yes | | Accessing application-level logs | ❌ No — use container logs | | Managing container lifecycle | ❌ No — use hoody containers | ### How It Fits Into Hoody Philosophy The proxy-logs service embodies Hoody's observability-first approach: - **Zero Configuration** — Logs are automatically captured by the proxy layer; no instrumentation required in your application - **Container-Scoped** — All log operations target a specific container, ensuring tenant isolation - **Standardized Interface** — Uses the same `hoody ` pattern as all other Hoody services - **Authenticated Access** — All log access goes through Hoody's authentication layer ### Service Architecture ``` Client Request → Hoody Proxy → Container Service │ ▼ Log Capture Layer │ ┌────────────┼────────────┐ ▼ ▼ ▼ /_logs /_logs/stats /_logs/stream (stored) (aggregated) (real-time SSE) ``` --- ## Common Workflows ### Workflow 1: View Recent Logs for a Container **Goal:** Retrieve and inspect stored request/response logs for a specific container. **Step 1: Identify your container** ``` hoody containers list ``` ``` [ { "id": "cnt_abc123def456", "name": "my-api-service", "status": "ready" } ] ``` **Step 2: List recent logs** ``` hoody logs list -c cnt_abc123def456 ``` ``` [ { "id": "log_001", "timestamp": "2025-11-05T10:30:00Z", "method": "GET", "path": "/api/users", "statusCode": 200, "duration": 45 }, { "id": "log_002", "timestamp": "2025-11-05T10:30:05Z", "method": "POST", "path": "/api/users", "statusCode": 201, "duration": 120 } ] ``` **Step 3: Get machine-readable output for scripting** ``` hoody logs list -c cnt_abc123def456 -o json ``` ### Workflow 2: Check Log Statistics **Goal:** Retrieve aggregated metrics about traffic patterns for a container. **Step 1: Get log statistics** ``` hoody logs stats -c cnt_abc123def456 ``` ``` { "totalRequests": 15420, "avgDuration": 85, "statusBreakdown": { "2xx": 14800, "3xx": 320, "4xx": 250, "5xx": 50 } } ``` **Step 2: Export stats for monitoring** ``` hoody logs stats -c cnt_abc123def456 -o json > /tmp/container-stats.json ``` ### Workflow 3: Stream Logs in Real-Time **Goal:** Monitor live traffic to a container as requests arrive. **Step 1: Start a log stream** ``` hoody logs stream -c cnt_abc123def456 ``` The stream returns Server-Sent Events (SSE) with the following frame format: ``` id: 12345 data: {"timestamp":"2025-11-05T10:31:00Z","method":"GET","path":"/health","statusCode":200,"duration":12} id: 12346 data: {"timestamp":"2025-11-05T10:31:02Z","method":"POST","path":"/api/data","statusCode":201,"duration":95} ``` **Step 2: Stream with JSON output for piping** ``` hoody logs stream -c cnt_abc123def456 -o json | jq '.statusCode' ``` ### Workflow 4: Debug a Failing Service **Goal:** Investigate 5xx errors by combining stats and filtered logs. **Step 1: Check error rate via stats** ``` hoody logs stats -c cnt_abc123def456 ``` ``` { "totalRequests": 15420, "avgDuration": 85, "statusBreakdown": { "2xx": 14800, "3xx": 320, "4xx": 250, "5xx": 50 } } ``` **Step 2: List logs to find error patterns** ``` hoody logs list -c cnt_abc123def456 ``` **Step 3: Stream logs while reproducing the issue** ``` hoody logs stream -c cnt_abc123def456 ``` **Step 4: Verify fix by monitoring stream** ``` hoody logs stream -c cnt_abc123def456 -o json ``` ### Workflow 5: Using Environment Variables for Container Targeting **Goal:** Avoid repeating `-c` flag when working with a single container. **Step 1: Set the container environment variable** ``` export HOODY_CONTAINER=cnt_abc123def456 ``` **Step 2: Run commands without explicit `-c` flag** ``` hoody logs list hoody logs stats hoody logs stream ``` --- ## Advanced Operations ### Multi-Container Log Monitoring **Scenario:** Monitor logs across multiple containers simultaneously. **Step 1: List all containers** ``` hoody containers list -o json ``` ``` [ { "id": "cnt_abc123def456", "name": "api-service", "status": "ready" }, { "id": "cnt_xyz789ghi012", "name": "worker-service", "status": "ready" } ] ``` **Step 2: Stream from multiple containers in parallel** ``` # Terminal 1 hoody logs stream -c cnt_abc123def456 # Terminal 2 hoody logs stream -c cnt_xyz789ghi012 ``` ### SSE Stream Reconnection **Scenario:** Handle stream interruptions gracefully. The SSE stream uses `id: ` framing for each event. When reconnecting, the client can use the last received `id` to resume from where it left off, avoiding duplicate entries. **Connection pattern:** ``` id: 12345 data: {"timestamp":"2025-11-05T10:31:00Z","method":"GET","path":"/health","statusCode":200} id: 12346 data: {"timestamp":"2025-11-05T10:31:02Z","method":"POST","path":"/api/data","statusCode":201} ``` **Reconnect behavior:** - Client stores last received `id` value - On reconnection, stream resumes from that sequence point - No duplicate log entries are delivered ### Log Analysis Pipeline **Scenario:** Build an automated analysis pipeline using CLI output. **Step 1: Capture stats snapshot** ``` hoody logs stats -c cnt_abc123def456 -o json > stats-snapshot.json ``` **Step 2: Stream logs to file for batch analysis** ``` hoody logs stream -c cnt_abc123def456 -o json > logs-capture.jsonl ``` **Step 3: Process with standard tools** ``` cat logs-capture.jsonl | jq 'select(.statusCode >= 500)' ``` ### Error Recovery Patterns **Scenario:** Log commands fail or return unexpected results. **Check 1: Verify container exists and is running** ``` hoody containers list ``` ``` [ { "id": "cnt_abc123def456", "name": "my-service", "status": "ready" } ] ``` **Check 2: Verify authentication** ``` hoody auth login ``` **Check 3: Use explicit token if stored credentials are stale** ``` hoody logs list -c cnt_abc123def456 --token ``` **Check 4: Verify container ID is correct** ``` hoody containers list -o json | jq '.[].id' ``` ### Performance Considerations | Operation | Performance Impact | Recommendation | |-----------|-------------------|----------------| | `logs list` | Low — queries stored logs | Use freely for debugging | | `logs stats` | Low — pre-aggregated | Safe for dashboards | | `logs stream` | Medium — persistent connection | Limit to active debugging sessions | **Best Practices:** - Close SSE streams when not actively monitoring - Use `logs stats` for dashboards instead of parsing `logs list` output - Target specific containers rather than attempting broad queries - Use `-o json` for machine processing; default table output for human reading --- ## Quick Reference ### Commands | Command | Description | Example | |---------|-------------|---------| | `hoody logs list` | Search and filter stored logs | `hoody logs list -c cnt_abc123` | | `hoody logs stats` | Get aggregated log statistics | `hoody logs stats -c cnt_abc123` | | `hoody logs stream` | Real-time SSE log stream | `hoody logs stream -c cnt_abc123` | ### Common Flags | Flag | Short | Description | |------|-------|-------------| | `--container` | `-c` | Target container ID (required unless `HOODY_CONTAINER` set) | | `--output` | `-o` | Output format: `table`, `json`, `yaml`, `wide`, `raw` | | `--token` | `-t` | API token override | | `--username` | `-u` | Username for authentication | | `--password` | `-p` | Password for authentication | ### Environment Variables | Variable | Description | |----------|-------------| | `HOODY_CONTAINER` | Default container ID (replaces `-c` flag) | | `HOODY_TOKEN` | API authentication token | ### SSE Stream Frame Format ``` id: data: ``` ### Typical Response Shapes **`logs list` response:** ``` [ { "id": "log_001", "timestamp": "2025-11-05T10:30:00Z", "method": "GET", "path": "/api/users", "statusCode": 200, "duration": 45 } ] ``` **`logs stats` response:** ``` { "totalRequests": 15420, "avgDuration": 85, "statusBreakdown": { "2xx": 14800, "3xx": 320, "4xx": 250, "5xx": 50 } } ``` **`logs stream` frame:** ``` id: 12345 data: {"timestamp":"2025-11-05T10:31:00Z","method":"GET","path":"/health","statusCode":200,"duration":12} ``` ### Authentication Quick Start ``` # Option 1: Interactive login hoody auth login # Option 2: Token flag hoody logs list -c cnt_abc123 -t # Option 3: Environment variable export HOODY_TOKEN= hoody logs list -c cnt_abc123 ```