n8n-mcp/TELEMETRY_ANALYSIS_README.md

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.