# Telemetry Analysis Documentation Index **Comprehensive Analysis of N8N-MCP Telemetry Infrastructure** **Analysis Date:** November 12, 2025 **Status:** Complete and Ready for Implementation --- ## Quick Start If you only have 5 minutes: - Read the summary section below If you have 30 minutes: - Read TELEMETRY_N8N_FIXER_DATASET.md (master summary) If you have 2+ hours: - Start with TELEMETRY_ANALYSIS.md (main reference) - Follow with TELEMETRY_MUTATION_SPEC.md (implementation guide) - Use TELEMETRY_QUICK_REFERENCE.md for queries/patterns --- ## One-Sentence Summary The n8n-mcp telemetry system successfully tracks 276K+ user interactions across a production Supabase backend, but lacks workflow mutation capture needed for building an n8n-fixer dataset. The solution requires a new table plus 3-4 weeks of integration work. --- ## Document Guide ### PRIMARY DOCUMENTS (Created November 12, 2025) #### 1. TELEMETRY_ANALYSIS.md (23 KB, 720 lines) **Your main reference for understanding current state** Contains: - Complete table schemas (telemetry_events, telemetry_workflows) - All 12 event types with JSON examples - Current workflow tracking capabilities - Data samples from production - Gap analysis for n8n-fixer requirements - Proposed schema additions - Privacy & security analysis - Data capture pipeline architecture When to read: You need the complete picture of what exists and what's missing Read time: 20-30 minutes --- #### 2. TELEMETRY_MUTATION_SPEC.md (26 KB, 918 lines) **Your implementation blueprint** Contains: - Complete SQL schema for workflow_mutations table with 20 indexes - TypeScript interfaces and type definitions - Integration point specifications - Mutation analyzer service code structure - Batch processor extensions - Code examples for tools to instrument - Validation rules and data quality checks - Query patterns for dataset analysis - 4-phase implementation roadmap When to read: You're ready to start building the mutation tracking system Read time: 30-40 minutes --- #### 3. TELEMETRY_QUICK_REFERENCE.md (11 KB, 503 lines) **Your developer quick lookup guide** Contains: - Supabase connection details - Event type quick reference - Common SQL query patterns - Performance optimization tips - User journey analysis examples - Platform distribution queries - File references and code locations - Helpful constants and values When to read: You need to query existing data or reference specific details Read time: 10-15 minutes --- #### 4. TELEMETRY_N8N_FIXER_DATASET.md (13 KB, 340 lines) **Your executive summary and master planning document** Contains: - Overview of analysis findings - Documentation map (what to read in what order) - Current state summary - Recommended 4-phase implementation path - Key metrics you'll collect - Storage requirements and cost estimates - Risk assessment - Success criteria for each phase - Questions to answer before starting When to read: Planning implementation or presenting to stakeholders Read time: 15-20 minutes --- ### SUPPORTING DOCUMENTS (Created November 8, 2025) #### TELEMETRY_ANALYSIS_REPORT.md (26 KB) - Executive summary with visualizations - Event distribution statistics - Usage patterns and trends - Performance metrics - User activity analysis #### TELEMETRY_EXECUTIVE_SUMMARY.md (10 KB) - High-level overview for executives - Key statistics and metrics - Business impact assessment - Recommendation summary #### TELEMETRY_TECHNICAL_DEEP_DIVE.md (18 KB) - Architecture and design patterns - Component interactions - Data flow diagrams - Implementation details - Performance considerations #### TELEMETRY_DATA_FOR_VISUALIZATION.md (18 KB) - Sample datasets for dashboards - Query results and aggregations - Visualization recommendations - Chart and graph specifications #### TELEMETRY_ANALYSIS_INDEX.md (15 KB) - Index of all analyses - Cross-references - Topic mappings - Search guide --- ## Recommended Reading Order ### For Implementation Teams 1. TELEMETRY_N8N_FIXER_DATASET.md (15 min) - Understand the plan 2. TELEMETRY_ANALYSIS.md (30 min) - Understand current state 3. TELEMETRY_MUTATION_SPEC.md (40 min) - Get implementation details 4. TELEMETRY_QUICK_REFERENCE.md (10 min) - Reference during coding **Total Time:** 95 minutes ### For Product Managers 1. TELEMETRY_EXECUTIVE_SUMMARY.md (10 min) 2. TELEMETRY_N8N_FIXER_DATASET.md (15 min) 3. TELEMETRY_ANALYSIS_REPORT.md (20 min) **Total Time:** 45 minutes ### For Data Analysts 1. TELEMETRY_ANALYSIS.md (30 min) 2. TELEMETRY_QUICK_REFERENCE.md (10 min) 3. TELEMETRY_ANALYSIS_REPORT.md (20 min) **Total Time:** 60 minutes ### For Architects 1. TELEMETRY_TECHNICAL_DEEP_DIVE.md (20 min) 2. TELEMETRY_MUTATION_SPEC.md (40 min) 3. TELEMETRY_N8N_FIXER_DATASET.md (15 min) **Total Time:** 75 minutes --- ## Key Findings Summary ### What Exists Today - **276K+ telemetry events** tracked in Supabase - **6.5K+ unique workflows** analyzed - **12 event types** covering tool usage, errors, validation, workflow creation - **Production-grade infrastructure** with batching, retry logic, rate limiting - **Privacy-focused design** with sanitization, anonymization, encryption ### Critical Gaps for N8N-Fixer - No workflow mutation/modification tracking - No before/after workflow snapshots - No instruction/transformation capture - No mutation success metrics - No validation improvement tracking ### Proposed Solution - New `workflow_mutations` table (with 20 indexes) - Extended telemetry system to capture mutations - Instrumentation of 3-4 key tools - 4-phase implementation (3-4 weeks) ### Data Volume Estimates - Per mutation: 25 KB (with compression) - Monthly: 250 MB - 1.2 GB - Annual: 3-14 GB - Cost: $10-200/month (depending on volume) ### Implementation Effort - Phase 1 (Infrastructure): 40-60 hours - Phase 2 (Core Integration): 40-60 hours - Phase 3 (Tool Integration): 20-30 hours - Phase 4 (Validation): 20-30 hours - **Total:** 120-180 hours (3-4 weeks) --- ## Critical Data ### Supabase Connection ``` URL: https://ydyufsohxdfpopqbubwk.supabase.co Database: PostgreSQL Auth: Anon key (in telemetry-types.ts) Tables: telemetry_events, telemetry_workflows ``` ### Event Types (by volume) 1. tool_used (40-50%) 2. tool_sequence (20-30%) 3. error_occurred (10-15%) 4. validation_details (5-10%) 5. Others (workflow, session, performance) (5-10%) ### Node Files - Source types: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-types.ts` - Main manager: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-manager.ts` - Event tracker: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/event-tracker.ts` - Batch processor: `/Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/batch-processor.ts` --- ## Implementation Checklist ### Before Starting - [ ] Read TELEMETRY_N8N_FIXER_DATASET.md - [ ] Read TELEMETRY_ANALYSIS.md - [ ] Answer 6 questions (see TELEMETRY_N8N_FIXER_DATASET.md) - [ ] Get stakeholder approval for 4-phase plan - [ ] Assign implementation team ### Phase 1: Infrastructure (Weeks 1-2) - [ ] Create workflow_mutations table in Supabase - [ ] Add 20+ indexes per specification - [ ] Define TypeScript types - [ ] Build mutation validator - [ ] Write unit tests ### Phase 2: Core Integration (Weeks 2-3) - [ ] Add trackWorkflowMutation() to TelemetryManager - [ ] Extend EventTracker with mutation queue - [ ] Extend BatchProcessor for mutations - [ ] Write integration tests - [ ] Code review and merge ### Phase 3: Tool Integration (Week 4) - [ ] Instrument n8n_autofix_workflow - [ ] Instrument n8n_update_partial_workflow - [ ] Instrument validation engine (if applicable) - [ ] Manual end-to-end testing - [ ] Code review and merge ### Phase 4: Validation (Week 5) - [ ] Collect 100+ sample mutations - [ ] Verify data quality - [ ] Run analysis queries - [ ] Assess dataset readiness - [ ] Begin production collection --- ## Storage & Cost Planning ### Conservative Estimate (10K mutations/month) - Storage: 250 MB/month - Cost: $10-20/month - Dataset: 1K mutations in 3-4 days ### Moderate Estimate (30K mutations/month) - Storage: 750 MB/month - Cost: $50-100/month - Dataset: 10K mutations in 10 days ### High Estimate (50K mutations/month) - Storage: 1.2 GB/month - Cost: $100-200/month - Dataset: 100K mutations in 2 months **With 90-day retention policy, costs stay at lower end.** --- ## Questions Before Implementation 1. **Data Retention:** Keep mutations for 90 days? 1 year? Indefinite? 2. **Storage Budget:** Monthly budget for telemetry storage? 3. **Workflow Size:** Max workflow size to store? Compression required? 4. **Dataset Timeline:** When do you need first dataset? (1K? 10K? 100K?) 5. **Privacy:** Additional PII to sanitize beyond current approach? 6. **User Consent:** Separate opt-in for mutation tracking vs. general telemetry? --- ## Risk Assessment ### Low Risk - No breaking changes to existing system - Fully backward compatible - Optional feature (can disable if needed) - No version bump required ### Medium Risk - Storage growth if >1.2 GB/month - Performance impact if workflows >10 MB - Mitigation: Compression + retention policy ### High Risk - None identified --- ## Success Criteria When you can answer "yes" to all: - [ ] 100+ workflow mutations collected - [ ] Data hash verification passes 100% - [ ] Sample queries execute <100ms - [ ] Deduplication working correctly - [ ] Before/after states properly stored - [ ] Validation improvements tracked accurately - [ ] No performance regression in tools - [ ] Team ready for large-scale collection --- ## Next Steps ### Immediate (This Week) 1. Review this README 2. Read TELEMETRY_N8N_FIXER_DATASET.md 3. Read TELEMETRY_ANALYSIS.md 4. Schedule team review meeting ### Short-term (Next 1-2 Weeks) 1. Answer the 6 questions 2. Get stakeholder approval 3. Assign implementation lead 4. Create Jira tickets for Phase 1 ### Medium-term (Weeks 3-6) 1. Execute Phase 1 (Infrastructure) 2. Execute Phase 2 (Core Integration) 3. Execute Phase 3 (Tool Integration) 4. Execute Phase 4 (Validation) ### Long-term (Week 7+) 1. Begin production dataset collection 2. Monitor storage and costs 3. Run analysis queries 4. Iterate based on findings --- ## Contact & Questions **Analysis Completed By:** Telemetry Data Analyst **Date:** November 12, 2025 **Status:** Ready for team review and implementation For questions or clarifications: 1. Review the specific document for your question 2. Check TELEMETRY_QUICK_REFERENCE.md for common lookups 3. Refer to source files in src/telemetry/ --- ## Document Statistics | Document | Size | Lines | Read Time | Purpose | |----------|------|-------|-----------|---------| | TELEMETRY_ANALYSIS.md | 23 KB | 720 | 20-30 min | Main reference | | TELEMETRY_MUTATION_SPEC.md | 26 KB | 918 | 30-40 min | Implementation guide | | TELEMETRY_QUICK_REFERENCE.md | 11 KB | 503 | 10-15 min | Developer lookup | | TELEMETRY_N8N_FIXER_DATASET.md | 13 KB | 340 | 15-20 min | Executive summary | | TELEMETRY_ANALYSIS_REPORT.md | 26 KB | 732 | 20-30 min | Statistics & trends | | TELEMETRY_EXECUTIVE_SUMMARY.md | 10 KB | 345 | 10-15 min | Executive brief | | TELEMETRY_TECHNICAL_DEEP_DIVE.md | 18 KB | 654 | 20-25 min | Architecture | | TELEMETRY_DATA_FOR_VISUALIZATION.md | 18 KB | 468 | 15-20 min | Dashboard data | | TELEMETRY_ANALYSIS_INDEX.md | 15 KB | 447 | 10-15 min | Topic index | | **TOTAL** | **160 KB** | **5,237** | **150-180 min** | Full analysis | --- ## Version History | Date | Version | Changes | |------|---------|---------| | Nov 8, 2025 | 1.0 | Initial analysis and reports | | Nov 12, 2025 | 2.0 | Core documentation + mutation spec + this README | --- ## License & Attribution These analysis documents are part of the n8n-mcp project. Conceived by Romuald Członkowski - www.aiadvisors.pl/en --- **END OF README** For additional information, start with one of the primary documents above based on your role and available time.