<!--
hoody-proxyLogs Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-05-06T18:26:37.898Z
Model: mimo-v2.5-pro
Mode: http


Tokens: 4806

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-proxyLogs Subskill

## Overview

**Service**: `hoody-proxyLogs`
**Purpose**: Provides access to request/response and event logs for a Hoody Kit container service. Enables log searching, filtering, statistics retrieval, and real-time log streaming via Server-Sent Events (SSE).

### When to Use

- **Debugging**: Inspect incoming requests and outgoing responses to diagnose issues with your container service.
- **Monitoring**: Stream logs in real-time to observe traffic patterns and errors as they occur.
- **Analytics**: Retrieve log statistics to understand request volume, error rates, and performance metrics.
- **Auditing**: Search historical logs for specific requests, status codes, or time ranges.

### How It Fits Hoody Philosophy

The proxyLogs service embodies Hoody's observability-first approach. Every request routed through Hoody Proxy is automatically logged, giving you full visibility into your service's traffic without modifying application code. This service runs alongside your container as a sidecar, capturing proxy-level telemetry that complements application-level logging.

### Service Architecture

```
Client Request
      │
      ▼
┌─────────────┐
│ Hoody Proxy  │──── Logs written ────►┌──────────────────┐
│  (Router)    │                        │ hoody-proxyLogs  │
└─────┬───────┘                        │  (Log Store)     │
      │                                └────────┬─────────┘
      ▼                                         │
┌─────────────┐                          GET /_logs
│ Your Container│                        GET /_logs/stats
│   Service    │                         GET /_logs/stream
└─────────────┘
```

### Base URL

All requests use this base URL pattern:

```
https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu
```

**Components**:
- `{projectId}` — Your Hoody project identifier
- `{containerId}` — The container instance identifier
- `{serviceId}` — The proxyLogs service identifier
- `{node}` — The Hoody node (e.g., `us-east-1`)

> **Note**: Obtain the exact base URL from your Hoody project dashboard or via the Hoody API container discovery endpoints (see core SKILL.md).

---

## Common Workflows

### Workflow 1: Fetch Recent Logs

Retrieve the most recent log entries from your service.

**Step 1**: Call the `/_logs` endpoint.

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs"
```

**Expected Response**:

```
{
  "logs": [
    {
      "id": "log_abc123",
      "timestamp": "2025-11-05T14:32:01.000Z",
      "method": "GET",
      "path": "/api/users",
      "statusCode": 200,
      "duration": 45,
      "clientIp": "203.0.113.42"
    }
  ],
  "total": 1,
  "hasMore": false
}
```

**Step 2**: Verify the response contains a `logs` array. If `hasMore` is `true`, paginate or filter to narrow results.

---

### Workflow 2: Filter Logs by Status Code

Search for error responses to identify failing requests.

**Step 1**: Query `/_logs` with a status code filter.

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs?statusCode=500"
```

**Expected Response**:

```
{
  "logs": [
    {
      "id": "log_err001",
      "timestamp": "2025-11-05T14:35:12.000Z",
      "method": "POST",
      "path": "/api/orders",
      "statusCode": 500,
      "duration": 1203,
      "clientIp": "198.51.100.10"
    }
  ],
  "total": 1,
  "hasMore": false
}
```

**Step 2**: Use the `id` and `timestamp` from each log entry to correlate with application-level logs for deeper debugging.

---

### Workflow 3: Retrieve Log Statistics

Get aggregate statistics about your service's traffic.

**Step 1**: Call the `/_logs/stats` endpoint.

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs/stats"
```

**Expected Response**:

```
{
  "totalRequests": 15420,
  "totalErrors": 23,
  "averageDuration": 87,
  "statusBreakdown": {
    "200": 14800,
    "404": 597,
    "500": 23
  }
}
```

**Step 2**: Review `statusBreakdown` to identify error patterns. A high `404` count may indicate routing misconfiguration; `500` errors point to application failures.

---

### Workflow 4: Stream Logs in Real-Time

Open a persistent SSE connection to watch logs as they arrive.

**Step 1**: Connect to the `/_logs/stream` endpoint.

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs/stream"
```

**Expected SSE Stream**:

```
id: 10001
data: {"id":"log_live01","timestamp":"2025-11-05T14:40:00.000Z","method":"GET","path":"/health","statusCode":200,"duration":12,"clientIp":"203.0.113.42"}

id: 10002
data: {"id":"log_live02","timestamp":"2025-11-05T14:40:01.500Z","method":"POST","path":"/api/data","statusCode":201,"duration":230,"clientIp":"198.51.100.10"}

id: 10003
data: {"id":"log_live03","timestamp":"2025-11-05T14:40:03.200Z","method":"GET","path":"/api/users","statusCode":500,"duration":5012,"clientIp":"203.0.113.42"}
```

**Step 2**: Parse each SSE frame. The `id` field contains the `ringSeq` (ring buffer sequence number), which you can use to resume the stream after a disconnect.

**Step 3**: On disconnect, reconnect with the last received `ringSeq` to avoid gaps.

---

### Workflow 5: Reconnect and Resume Streaming

Resume a dropped SSE stream from where you left off.

**Step 1**: After a disconnect, reconnect using the last `ringSeq` as a query parameter.

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs/stream?lastId=10003"
```

**Expected SSE Stream** (resumes from sequence 10004):

```
id: 10004
data: {"id":"log_live04","timestamp":"2025-11-05T14:40:05.000Z","method":"DELETE","path":"/api/items/42","statusCode":204,"duration":55,"clientIp":"198.51.100.10"}
```

**Step 2**: Verify the first `id` in the new stream is greater than your last known `ringSeq`. If it matches or is lower, the server has already delivered those frames.

---

## Advanced Operations

### Multi-Step: Debug a Failing Endpoint

Combine log search and stats to diagnose a problematic endpoint.

**Step 1**: Get overall stats to confirm error volume.

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs/stats"
```

**Step 2**: Filter logs for 5xx errors on the suspected path.

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs?statusCode=500"
```

**Step 3**: Open a real-time stream to watch for new errors while you trigger test requests.

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs/stream"
```

**Step 4**: In a separate terminal, send a test request to your container service directly or through the proxy. Observe the log entry appear in the stream with the matching path and status code.

**Step 5**: Correlate the proxy log's `timestamp` and `duration` with your application logs to pinpoint where the failure occurs (proxy timeout vs. application error).

---

### Error Recovery: Handling Stream Interruptions

SSE streams can drop due to network issues, proxy timeouts, or server restarts. Implement a resilient streaming pattern:

**Pattern**:

```
1. Connect to /_logs/stream
2. Store each received `id` (ringSeq)
3. On disconnect:
   a. Wait with exponential backoff (1s, 2s, 4s, max 30s)
   b. Reconnect to /_logs/stream?lastId={lastRingSeq}
   c. Verify first received id > lastRingSeq
4. If reconnect fails 3 times, fall back to polling /_logs
```

**Fallback Polling Example**:

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs"
```

---

### Performance Considerations

| Concern | Recommendation |
|---------|----------------|
| **High-volume services** | Use `/_logs/stream` instead of polling `/_logs` to reduce request overhead. |
| **Large log payloads** | Filter aggressively using query parameters to limit response size. |
| **Long-running streams** | Set `--max-time` appropriately; SSE connections may need periodic reconnection. |
| **Stats freshness** | `/_logs/stats` reflects aggregate data; for real-time counts, parse the stream. |
| **Network resilience** | Always implement reconnection logic with backoff for SSE consumers. |

---

### Multi-Step: Monitor Deployment Health

Use logs and stats together to verify a deployment rollout.

**Step 1**: Record baseline stats before deployment.

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs/stats"
```

**Step 2**: Deploy your updated container (via Hoody API — see core SKILL.md).

**Step 3**: Open a log stream to watch for errors in real-time.

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs/stream"
```

**Step 4**: After a stabilization period, compare new stats against the baseline.

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs/stats"
```

**Step 5**: If error rate increased, filter for 5xx logs and roll back if necessary.

---

## Quick Reference

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/_logs` | Search and filter stored request/response and event logs |
| `GET` | `/_logs/stats` | Retrieve aggregate log statistics |
| `GET` | `/_logs/stream` | Open persistent SSE connection for real-time log streaming |

### Base URL

```
https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu
```

### SSE Frame Format

```
id: <ringSeq>
data: <LogEntry JSON>

```

### Reconnect Parameter

```
/_logs/stream?lastId=<ringSeq>
```

### Typical Log Entry Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique log entry identifier |
| `timestamp` | string (ISO 8601) | When the request was received |
| `method` | string | HTTP method (GET, POST, etc.) |
| `path` | string | Request path |
| `statusCode` | number | HTTP response status code |
| `duration` | number | Request processing time in milliseconds |
| `clientIp` | string | Client IP address |

### Essential curl Pattern

```
curl -s \
  "https://{projectId}-{containerId}-proxy-logs-{serviceId}.{node}.containers.hoody.icu/_logs"
```

> **Reminder**: Always use `-s` (silent) flag to suppress curl progress output. Always use `--max-time` to prevent hanging connections, especially for SSE streams.