* feat: add comprehensive telemetry for partial workflow updates
Implement telemetry infrastructure to track workflow mutations from
partial update operations. This enables data-driven improvements to
partial update tooling by capturing:
- Workflow state before and after mutations
- User intent and operation patterns
- Validation results and improvements
- Change metrics (nodes/connections modified)
- Success/failure rates and error patterns
New Components:
- Intent classifier: Categorizes mutation patterns
- Intent sanitizer: Removes PII from user instructions
- Mutation validator: Ensures data quality before tracking
- Mutation tracker: Coordinates validation and metric calculation
Extended Components:
- TelemetryManager: New trackWorkflowMutation() method
- EventTracker: Mutation queue management
- BatchProcessor: Mutation data flushing to Supabase
MCP Tool Enhancements:
- n8n_update_partial_workflow: Added optional 'intent' parameter
- n8n_update_full_workflow: Added optional 'intent' parameter
- Both tools now track mutations asynchronously
Database Schema:
- New workflow_mutations table with 20+ fields
- Comprehensive indexes for efficient querying
- Supports deduplication and data analysis
This telemetry system is:
- Privacy-focused (PII sanitization, anonymized users)
- Non-blocking (async tracking, silent failures)
- Production-ready (batching, retries, circuit breaker)
- Backward compatible (all parameters optional)
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* fix: correct SQL syntax for expression index in workflow_mutations schema
The expression index for significant changes needs double parentheses
around the arithmetic expression to be valid PostgreSQL syntax.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* fix: enable RLS policies for workflow_mutations table
Enable Row-Level Security and add policies:
- Allow anonymous (anon) inserts for telemetry data collection
- Allow authenticated reads for data analysis and querying
These policies are required for the telemetry system to function
correctly with Supabase, as the MCP server uses the anon key to
insert mutation data.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* fix: reduce mutation auto-flush threshold from 5 to 2
Lower the auto-flush threshold for workflow mutations from 5 to 2 to ensure
more timely data persistence. Since mutations are less frequent than regular
telemetry events, a lower threshold provides:
- Faster data persistence (don't wait for 5 mutations)
- Better testing experience (easier to verify with fewer operations)
- Reduced risk of data loss if process exits before threshold
- More responsive telemetry for low-volume mutation scenarios
This complements the existing 5-second periodic flush and process exit
handlers, ensuring mutations are persisted promptly.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* fix: improve mutation telemetry error logging and diagnostics
Changes:
- Upgrade error logging from debug to warn level for better visibility
- Add diagnostic logging to track mutation processing
- Log telemetry disabled state explicitly
- Add context info (sessionId, intent, operationCount) to error logs
- Remove 'await' from telemetry calls to make them truly non-blocking
This will help identify why mutations aren't being persisted to the
workflow_mutations table despite successful workflow operations.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
* feat: enhance workflow mutation telemetry for better AI responses
Improve workflow mutation tracking to capture comprehensive data that helps provide better responses when users update workflows. This enhancement collects workflow state, user intent, and operation details to enable more context-aware assistance.
Key improvements:
- Reduce auto-flush threshold from 5 to 2 for more reliable mutation tracking
- Add comprehensive workflow and credential sanitization to mutation tracker
- Document intent parameter in workflow update tools for better UX
- Fix mutation queue handling in telemetry manager (flush now handles 3 queues)
- Add extensive unit tests for mutation tracking and validation (35 new tests)
Technical changes:
- mutation-tracker.ts: Multi-layer sanitization (workflow, node, parameter levels)
- batch-processor.ts: Support mutation data flushing to Supabase
- telemetry-manager.ts: Auto-flush mutations at threshold 2, track mutations queue
- handlers-workflow-diff.ts: Track workflow mutations with sanitized data
- Tests: 13 tests for mutation-tracker, 22 tests for mutation-validator
The intent parameter messaging emphasizes user benefit ("helps to return better response") rather than technical implementation details.
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* chore: bump version to 2.22.16 with telemetry changelog
Updated package.json and package.runtime.json to version 2.22.16.
Added comprehensive CHANGELOG entry documenting workflow mutation
telemetry enhancements for better AI-powered workflow assistance.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: resolve TypeScript lint errors in telemetry tests
Fixed type issues in mutation-tracker and mutation-validator tests:
- Import and use MutationToolName enum instead of string literals
- Fix ValidationResult.errors to use proper object structure
- Add UpdateNodeOperation type assertion for operation with nodeName
All TypeScript errors resolved, lint now passes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Added isDocker and cloudPlatform fields to session_start telemetry events to enable measurement of the v2.17.1 user ID stability fix.
Changes:
- Added detectCloudPlatform() method to event-tracker.ts
- Updated trackSessionStart() to include isDocker and cloudPlatform
- Added 16 comprehensive unit tests for environment detection
- Tests for all 8 cloud platforms (Railway, Render, Fly, Heroku, AWS, K8s, GCP, Azure)
- Tests for Docker detection, local env, and combined scenarios
- Version bumped to 2.18.1
- Comprehensive CHANGELOG entry
Impact:
- Enables validation of v2.17.1 boot_id-based user ID stability
- Allows segmentation of metrics by environment
- 100% backward compatible - only adds new fields
- All tests passing, TypeScript compilation successful
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Fix event validator to not filter out generic 'key' property
- Handle compound key terms (apikey, api_key) while allowing standalone 'key'
- Fix batch processor test expectations to account for circuit breaker limits
- Adjust dead letter queue test to expect 25 items due to circuit breaker opening after 5 failures
- Fix test mocks to fail for all retry attempts before adding to dead letter queue
All 252 telemetry tests now passing with 90.75% code coverage
Major improvements to telemetry system addressing code review findings:
Architecture & Modularization:
- Split 636-line TelemetryManager into 7 focused modules
- Separated concerns: event tracking, batch processing, validation, rate limiting
- Lazy initialization pattern to avoid early singleton creation
- Clean separation of responsibilities
Security & Privacy:
- Added comprehensive input validation with Zod schemas
- Sanitization of sensitive data (URLs, API keys, emails)
- Expanded sensitive key detection patterns (25+ patterns)
- Row Level Security on Supabase backend
- Added data deletion contact info (romuald@n8n-mcp.com)
Performance & Reliability:
- Sliding window rate limiter (100 events/minute)
- Circuit breaker pattern for network failures
- Dead letter queue for failed events
- Exponential backoff with jitter for retries
- Performance monitoring with overhead tracking (<5%)
- Memory-safe array limits in rate limiter
Testing:
- Comprehensive test coverage (87%+ for core modules)
- Unit tests for all new modules
- Integration tests for MCP telemetry
- Fixed test isolation issues
Data Management:
- Clear user consent in welcome message
- Batch processing with deduplication
- Automatic workflow flushing
BREAKING CHANGE: TelemetryManager constructor is now private, use getInstance()
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
