Lucas Berger
21e888c1ce
- Remove Claude API integration and intent parsing (04-02-PLAN) - REQ-08 (conversational queries) moved to out of scope - Phase 4 renamed from "Logs & Intelligence" to "Logs" (complete) - v1.0 now focuses on keyword-based container control Simple substring matching works well for container management. NLU adds complexity without proportional value for v1. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
131 lines
4.3 KiB
Markdown
131 lines
4.3 KiB
Markdown
---
|
|
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}×tamps=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*
|