---
phase: 04-logs-intelligence
plan: 01
subsystem: logs
tags: [docker-logs, telegram-bot, n8n, log-streaming]

# Dependency graph
requires:
  - phase: 02-docker-integration
    provides: Docker API integration and container matching patterns
  - phase: 03-container-actions
    provides: Action command routing and fuzzy container matching
provides:
  - Container log retrieval via Telegram commands
  - Configurable line count (default 50, max 1000)
  - Binary stream decoder for Docker logs API
  - Formatted log output with monospace display
affects: [04-02-claude-analysis]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Docker logs API multiplexed stream decoding"
    - "Telegram message truncation for long content"

key-files:
  created: []
  modified:
    - n8n-workflow.json

key-decisions:
  - "Use Docker logs API with tail parameter for line-limited retrieval"
  - "Strip 8-byte binary headers from Docker multiplexed stream"
  - "Truncate at 3800 chars to stay within Telegram 4096 limit"
  - "Default to 50 lines when not specified, cap at 1000 max"

patterns-established:
  - "Binary stream decoding: check charCodeAt(0) <= 2 for header presence"
  - "Log formatting: <pre> tags for monospace, HTML parse mode"

# Metrics
duration: 3min
completed: 2026-01-30
---

# Phase 04 Plan 01: Container Log Retrieval Summary

**Container log retrieval via Telegram with Docker API binary stream decoding and configurable line limits**

## Performance

- **Duration:** 3 min
- **Started:** 2026-01-31T02:40:38Z
- **Completed:** 2026-01-31T02:43:37Z
- **Tasks:** 3
- **Files modified:** 1

## Accomplishments
- Users can request logs for any container by name via Telegram
- Configurable line count (default 50, max 1000 lines)
- Docker logs API binary stream format properly decoded
- Logs displayed in readable monospace format with truncation for Telegram limits

## Task Commits

Implementation was atomic - all tasks completed in single commit:

1. **Tasks 1-3: Complete logs implementation** - `93c40fe` (feat)
   - Task 1: Logs command routing
   - Task 2: Docker logs API integration
   - Task 3: Binary stream format handling

**Note:** All three tasks were interdependent and completed together in a single atomic commit since they form a cohesive feature implementation.

## Files Created/Modified
- `n8n-workflow.json` - Added 11 new nodes for complete logs workflow:
  - Parse Logs Command: Extract container name and line count from user message
  - Docker List for Logs: Fetch containers for matching
  - Match Logs Container: Fuzzy match container name
  - Check Logs Match Count: Route based on match results
  - Build Logs Command: Construct Docker API curl with tail parameter
  - Execute Logs: Call Docker logs API
  - Format Logs: Decode binary stream, truncate, add monospace formatting
  - Send Logs Response: Reply to user via Telegram
  - Error handlers: No match, multiple matches, Docker errors

## Decisions Made

**1. Docker logs API with tail parameter**
- **Rationale:** More efficient than fetching all logs and filtering in code
- **Implementation:** `http://localhost/v1.47/containers/{id}/logs?stdout=1&stderr=1&tail={lines}&timestamps=1`

**2. Binary stream header detection via charCodeAt(0)**
- **Rationale:** Docker multiplexed stream uses byte 0 values 1 (stdout) or 2 (stderr)
- **Implementation:** Check if `charCodeAt(0) <= 2` and length > 8, then strip first 8 bytes
- **Robustness:** Works even if some lines lack headers (mixed format tolerance)

**3. Default 50 lines, cap at 1000**
- **Rationale:** Balance between useful context and Telegram message limits
- **Safety:** 1000 line cap prevents excessive API calls and message truncation

**4. Truncate at 3800 chars**
- **Rationale:** Telegram limit is 4096, leave room for header and formatting tags
- **UX:** Add "... (truncated)" indicator when limit hit

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None - Docker logs API worked as expected, binary stream format handled correctly.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

Ready for Phase 04 Plan 02 (Claude log analysis):
- Log retrieval working and tested
- Format suitable for Claude API input
- Error handling in place for edge cases

Logs are now available programmatically for Claude to analyze in next plan.

---
*Phase: 04-logs-intelligence*
*Completed: 2026-01-30*