mirror of
https://github.com/czlonkowski/n8n-mcp.git
synced 2026-02-06 05:23:08 +00:00
feat: enhance workflow mutation telemetry for better AI responses (#419)
* 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>
This commit is contained in:
Romuald Członkowski
committed by
GitHub
GitHub
parent
77151e013e
commit
99c5907b71
369
src/telemetry/mutation-tracker.ts
Normal file
369
src/telemetry/mutation-tracker.ts
Normal file
@@ -0,0 +1,369 @@
|
||||
/**
|
||||
* Core mutation tracker for workflow transformations
|
||||
* Coordinates validation, classification, and metric calculation
|
||||
*/
|
||||
|
||||
import { DiffOperation } from '../types/workflow-diff.js';
|
||||
import {
|
||||
WorkflowMutationData,
|
||||
WorkflowMutationRecord,
|
||||
MutationChangeMetrics,
|
||||
MutationValidationMetrics,
|
||||
IntentClassification,
|
||||
} from './mutation-types.js';
|
||||
import { intentClassifier } from './intent-classifier.js';
|
||||
import { mutationValidator } from './mutation-validator.js';
|
||||
import { intentSanitizer } from './intent-sanitizer.js';
|
||||
import { WorkflowSanitizer } from './workflow-sanitizer.js';
|
||||
import { logger } from '../utils/logger.js';
|
||||
|
||||
/**
|
||||
* Tracks workflow mutations and prepares data for telemetry
|
||||
*/
|
||||
export class MutationTracker {
|
||||
private recentMutations: Array<{
|
||||
hashBefore: string;
|
||||
hashAfter: string;
|
||||
operations: DiffOperation[];
|
||||
}> = [];
|
||||
|
||||
private readonly RECENT_MUTATIONS_LIMIT = 100;
|
||||
|
||||
/**
|
||||
* Process and prepare mutation data for tracking
|
||||
*/
|
||||
async processMutation(data: WorkflowMutationData, userId: string): Promise<WorkflowMutationRecord | null> {
|
||||
try {
|
||||
// Validate data quality
|
||||
if (!this.validateMutationData(data)) {
|
||||
logger.debug('Mutation data validation failed');
|
||||
return null;
|
||||
}
|
||||
|
||||
// Sanitize workflows to remove credentials and sensitive data
|
||||
const workflowBefore = this.sanitizeFullWorkflow(data.workflowBefore);
|
||||
const workflowAfter = this.sanitizeFullWorkflow(data.workflowAfter);
|
||||
|
||||
// Sanitize user intent
|
||||
const sanitizedIntent = intentSanitizer.sanitize(data.userIntent);
|
||||
|
||||
// Check if should be excluded
|
||||
if (mutationValidator.shouldExclude(data)) {
|
||||
logger.debug('Mutation excluded from tracking based on quality criteria');
|
||||
return null;
|
||||
}
|
||||
|
||||
// Check for duplicates
|
||||
if (
|
||||
mutationValidator.isDuplicate(
|
||||
workflowBefore,
|
||||
workflowAfter,
|
||||
data.operations,
|
||||
this.recentMutations
|
||||
)
|
||||
) {
|
||||
logger.debug('Duplicate mutation detected, skipping tracking');
|
||||
return null;
|
||||
}
|
||||
|
||||
// Generate hashes
|
||||
const hashBefore = mutationValidator.hashWorkflow(workflowBefore);
|
||||
const hashAfter = mutationValidator.hashWorkflow(workflowAfter);
|
||||
|
||||
// Classify intent
|
||||
const intentClassification = intentClassifier.classify(data.operations, sanitizedIntent);
|
||||
|
||||
// Calculate metrics
|
||||
const changeMetrics = this.calculateChangeMetrics(data.operations);
|
||||
const validationMetrics = this.calculateValidationMetrics(
|
||||
data.validationBefore,
|
||||
data.validationAfter
|
||||
);
|
||||
|
||||
// Create mutation record
|
||||
const record: WorkflowMutationRecord = {
|
||||
userId,
|
||||
sessionId: data.sessionId,
|
||||
workflowBefore,
|
||||
workflowAfter,
|
||||
workflowHashBefore: hashBefore,
|
||||
workflowHashAfter: hashAfter,
|
||||
userIntent: sanitizedIntent,
|
||||
intentClassification,
|
||||
toolName: data.toolName,
|
||||
operations: data.operations,
|
||||
operationCount: data.operations.length,
|
||||
operationTypes: this.extractOperationTypes(data.operations),
|
||||
validationBefore: data.validationBefore,
|
||||
validationAfter: data.validationAfter,
|
||||
...validationMetrics,
|
||||
...changeMetrics,
|
||||
mutationSuccess: data.mutationSuccess,
|
||||
mutationError: data.mutationError,
|
||||
durationMs: data.durationMs,
|
||||
};
|
||||
|
||||
// Store in recent mutations for deduplication
|
||||
this.addToRecentMutations(hashBefore, hashAfter, data.operations);
|
||||
|
||||
return record;
|
||||
} catch (error) {
|
||||
logger.error('Error processing mutation:', error);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate mutation data
|
||||
*/
|
||||
private validateMutationData(data: WorkflowMutationData): boolean {
|
||||
const validationResult = mutationValidator.validate(data);
|
||||
|
||||
if (!validationResult.valid) {
|
||||
logger.warn('Mutation data validation failed:', validationResult.errors);
|
||||
return false;
|
||||
}
|
||||
|
||||
if (validationResult.warnings.length > 0) {
|
||||
logger.debug('Mutation data validation warnings:', validationResult.warnings);
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Calculate change metrics from operations
|
||||
*/
|
||||
private calculateChangeMetrics(operations: DiffOperation[]): MutationChangeMetrics {
|
||||
const metrics: MutationChangeMetrics = {
|
||||
nodesAdded: 0,
|
||||
nodesRemoved: 0,
|
||||
nodesModified: 0,
|
||||
connectionsAdded: 0,
|
||||
connectionsRemoved: 0,
|
||||
propertiesChanged: 0,
|
||||
};
|
||||
|
||||
for (const op of operations) {
|
||||
switch (op.type) {
|
||||
case 'addNode':
|
||||
metrics.nodesAdded++;
|
||||
break;
|
||||
case 'removeNode':
|
||||
metrics.nodesRemoved++;
|
||||
break;
|
||||
case 'updateNode':
|
||||
metrics.nodesModified++;
|
||||
if ('updates' in op && op.updates) {
|
||||
metrics.propertiesChanged += Object.keys(op.updates as any).length;
|
||||
}
|
||||
break;
|
||||
case 'addConnection':
|
||||
metrics.connectionsAdded++;
|
||||
break;
|
||||
case 'removeConnection':
|
||||
metrics.connectionsRemoved++;
|
||||
break;
|
||||
case 'rewireConnection':
|
||||
// Rewiring is effectively removing + adding
|
||||
metrics.connectionsRemoved++;
|
||||
metrics.connectionsAdded++;
|
||||
break;
|
||||
case 'replaceConnections':
|
||||
// Count how many connections are being replaced
|
||||
if ('connections' in op && op.connections) {
|
||||
metrics.connectionsRemoved++;
|
||||
metrics.connectionsAdded++;
|
||||
}
|
||||
break;
|
||||
case 'updateSettings':
|
||||
if ('settings' in op && op.settings) {
|
||||
metrics.propertiesChanged += Object.keys(op.settings as any).length;
|
||||
}
|
||||
break;
|
||||
case 'moveNode':
|
||||
case 'enableNode':
|
||||
case 'disableNode':
|
||||
case 'updateName':
|
||||
case 'addTag':
|
||||
case 'removeTag':
|
||||
case 'activateWorkflow':
|
||||
case 'deactivateWorkflow':
|
||||
case 'cleanStaleConnections':
|
||||
// These don't directly affect node/connection counts
|
||||
// but count as property changes
|
||||
metrics.propertiesChanged++;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
return metrics;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sanitize a full workflow while preserving structure
|
||||
* Removes credentials and sensitive data but keeps all nodes, connections, parameters
|
||||
*/
|
||||
private sanitizeFullWorkflow(workflow: any): any {
|
||||
if (!workflow) return workflow;
|
||||
|
||||
// Deep clone to avoid modifying original
|
||||
const sanitized = JSON.parse(JSON.stringify(workflow));
|
||||
|
||||
// Remove sensitive workflow-level fields
|
||||
delete sanitized.credentials;
|
||||
delete sanitized.sharedWorkflows;
|
||||
delete sanitized.ownedBy;
|
||||
delete sanitized.createdBy;
|
||||
delete sanitized.updatedBy;
|
||||
|
||||
// Sanitize each node
|
||||
if (sanitized.nodes && Array.isArray(sanitized.nodes)) {
|
||||
sanitized.nodes = sanitized.nodes.map((node: any) => {
|
||||
const sanitizedNode = { ...node };
|
||||
|
||||
// Remove credentials field
|
||||
delete sanitizedNode.credentials;
|
||||
|
||||
// Sanitize parameters if present
|
||||
if (sanitizedNode.parameters && typeof sanitizedNode.parameters === 'object') {
|
||||
sanitizedNode.parameters = this.sanitizeParameters(sanitizedNode.parameters);
|
||||
}
|
||||
|
||||
return sanitizedNode;
|
||||
});
|
||||
}
|
||||
|
||||
return sanitized;
|
||||
}
|
||||
|
||||
/**
|
||||
* Recursively sanitize parameters object
|
||||
*/
|
||||
private sanitizeParameters(params: any): any {
|
||||
if (!params || typeof params !== 'object') return params;
|
||||
|
||||
const sensitiveKeys = [
|
||||
'apiKey', 'api_key', 'token', 'secret', 'password', 'credential',
|
||||
'auth', 'authorization', 'privateKey', 'accessToken', 'refreshToken'
|
||||
];
|
||||
|
||||
const sanitized: any = Array.isArray(params) ? [] : {};
|
||||
|
||||
for (const [key, value] of Object.entries(params)) {
|
||||
const lowerKey = key.toLowerCase();
|
||||
|
||||
// Check if key is sensitive
|
||||
if (sensitiveKeys.some(sk => lowerKey.includes(sk.toLowerCase()))) {
|
||||
sanitized[key] = '[REDACTED]';
|
||||
} else if (typeof value === 'object' && value !== null) {
|
||||
// Recursively sanitize nested objects
|
||||
sanitized[key] = this.sanitizeParameters(value);
|
||||
} else if (typeof value === 'string') {
|
||||
// Sanitize string values that might contain sensitive data
|
||||
sanitized[key] = this.sanitizeStringValue(value);
|
||||
} else {
|
||||
sanitized[key] = value;
|
||||
}
|
||||
}
|
||||
|
||||
return sanitized;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sanitize string values that might contain sensitive data
|
||||
*/
|
||||
private sanitizeStringValue(value: string): string {
|
||||
if (!value || typeof value !== 'string') return value;
|
||||
|
||||
let sanitized = value;
|
||||
|
||||
// Redact URLs with authentication
|
||||
sanitized = sanitized.replace(/https?:\/\/[^:]+:[^@]+@[^\s/]+/g, '[REDACTED_URL_WITH_AUTH]');
|
||||
|
||||
// Redact long API keys/tokens (20+ alphanumeric chars)
|
||||
sanitized = sanitized.replace(/\b[A-Za-z0-9_-]{32,}\b/g, '[REDACTED_TOKEN]');
|
||||
|
||||
// Redact OpenAI-style keys
|
||||
sanitized = sanitized.replace(/\bsk-[A-Za-z0-9]{32,}\b/g, '[REDACTED_APIKEY]');
|
||||
|
||||
// Redact Bearer tokens
|
||||
sanitized = sanitized.replace(/Bearer\s+[^\s]+/gi, 'Bearer [REDACTED]');
|
||||
|
||||
return sanitized;
|
||||
}
|
||||
|
||||
/**
|
||||
* Calculate validation improvement metrics
|
||||
*/
|
||||
private calculateValidationMetrics(
|
||||
validationBefore: any,
|
||||
validationAfter: any
|
||||
): MutationValidationMetrics {
|
||||
// If validation data is missing, return nulls
|
||||
if (!validationBefore || !validationAfter) {
|
||||
return {
|
||||
validationImproved: null,
|
||||
errorsResolved: 0,
|
||||
errorsIntroduced: 0,
|
||||
};
|
||||
}
|
||||
|
||||
const errorsBefore = validationBefore.errors?.length || 0;
|
||||
const errorsAfter = validationAfter.errors?.length || 0;
|
||||
|
||||
const errorsResolved = Math.max(0, errorsBefore - errorsAfter);
|
||||
const errorsIntroduced = Math.max(0, errorsAfter - errorsBefore);
|
||||
|
||||
const validationImproved = errorsBefore > errorsAfter;
|
||||
|
||||
return {
|
||||
validationImproved,
|
||||
errorsResolved,
|
||||
errorsIntroduced,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract unique operation types from operations
|
||||
*/
|
||||
private extractOperationTypes(operations: DiffOperation[]): string[] {
|
||||
const types = new Set(operations.map((op) => op.type));
|
||||
return Array.from(types);
|
||||
}
|
||||
|
||||
/**
|
||||
* Add mutation to recent list for deduplication
|
||||
*/
|
||||
private addToRecentMutations(
|
||||
hashBefore: string,
|
||||
hashAfter: string,
|
||||
operations: DiffOperation[]
|
||||
): void {
|
||||
this.recentMutations.push({ hashBefore, hashAfter, operations });
|
||||
|
||||
// Keep only recent mutations
|
||||
if (this.recentMutations.length > this.RECENT_MUTATIONS_LIMIT) {
|
||||
this.recentMutations.shift();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear recent mutations (useful for testing)
|
||||
*/
|
||||
clearRecentMutations(): void {
|
||||
this.recentMutations = [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Get statistics about tracked mutations
|
||||
*/
|
||||
getRecentMutationsCount(): number {
|
||||
return this.recentMutations.length;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Singleton instance for easy access
|
||||
*/
|
||||
export const mutationTracker = new MutationTracker();
|
||||
Reference in New Issue
Block a user