n8n-mcp/TELEMETRY_QUICK_REFERENCE.md

Telemetry Quick Reference Guide

Quick lookup for telemetry data access, queries, and common analysis patterns.

---

Supabase Connection Details

Database

• URL: https://ydyufsohxdfpopqbubwk.supabase.co
• Project: n8n-mcp telemetry database
• Region: (inferred from URL)

Anon Key

Located in: /Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-types.ts (line 105)

Tables

Name	Rows	Purpose
telemetry_events	276K+	Discrete events (tool usage, errors, validation)
telemetry_workflows	6.5K+	Workflow metadata (structure, complexity)

Proposed Table

Name	Rows	Purpose
workflow_mutations	TBD	Before/instruction/after workflow snapshots

---

Event Types & Properties

High-Volume Events

tool_used (40-50% of traffic)

{
  "event": "tool_used",
  "properties": {
    "tool": "get_node_info",
    "success": true,
    "duration": 245
  }
}

Query: Find most used tools

SELECT properties->>'tool' as tool, COUNT(*) as count
FROM telemetry_events
WHERE event = 'tool_used' AND created_at >= NOW() - INTERVAL '7 days'
GROUP BY 1 ORDER BY 2 DESC;

tool_sequence (20-30% of traffic)

{
  "event": "tool_sequence",
  "properties": {
    "previousTool": "search_nodes",
    "currentTool": "get_node_info",
    "timeDelta": 1250,
    "isSlowTransition": false,
    "sequence": "search_nodes->get_node_info"
  }
}

Query: Find common tool sequences

SELECT properties->>'sequence' as flow, COUNT(*) as count
FROM telemetry_events
WHERE event = 'tool_sequence' AND created_at >= NOW() - INTERVAL '30 days'
GROUP BY 1 ORDER BY 2 DESC LIMIT 20;

---

Error & Validation Events

error_occurred (10-15% of traffic)

{
  "event": "error_occurred",
  "properties": {
    "errorType": "validation_error",
    "context": "Node config failed [KEY]",
    "tool": "config_validator",
    "error": "[SANITIZED] type error",
    "mcpMode": "stdio",
    "platform": "darwin"
  }
}

Query: Error frequency by type

SELECT
  properties->>'errorType' as error_type,
  COUNT(*) as frequency,
  COUNT(DISTINCT user_id) as affected_users
FROM telemetry_events
WHERE event = 'error_occurred' AND created_at >= NOW() - INTERVAL '24 hours'
GROUP BY 1 ORDER BY 2 DESC;

validation_details (5-10% of traffic)

{
  "event": "validation_details",
  "properties": {
    "nodeType": "nodes_base_httpRequest",
    "errorType": "required_field_missing",
    "errorCategory": "required_field_error",
    "details": { /* error details */ }
  }
}

Query: Validation errors by node type

SELECT
  properties->>'nodeType' as node_type,
  properties->>'errorType' as error_type,
  COUNT(*) as count
FROM telemetry_events
WHERE event = 'validation_details' AND created_at >= NOW() - INTERVAL '7 days'
GROUP BY 1, 2 ORDER BY 3 DESC;

---

Workflow Events

workflow_created

{
  "event": "workflow_created",
  "properties": {
    "nodeCount": 3,
    "nodeTypes": 2,
    "complexity": "simple",
    "hasTrigger": true,
    "hasWebhook": false
  }
}

Query: Workflow creation trends

SELECT
  DATE(created_at) as date,
  COUNT(*) as workflows_created,
  AVG((properties->>'nodeCount')::int) as avg_nodes,
  COUNT(*) FILTER(WHERE properties->>'complexity' = 'simple') as simple_count
FROM telemetry_events
WHERE event = 'workflow_created' AND created_at >= NOW() - INTERVAL '30 days'
GROUP BY 1 ORDER BY 1;

workflow_validation_failed

{
  "event": "workflow_validation_failed",
  "properties": {
    "nodeCount": 5
  }
}

Query: Validation failure rate

SELECT
  COUNT(*) FILTER(WHERE event = 'workflow_created') as successful,
  COUNT(*) FILTER(WHERE event = 'workflow_validation_failed') as failed,
  ROUND(100.0 * COUNT(*) FILTER(WHERE event = 'workflow_validation_failed')
        / NULLIF(COUNT(*), 0), 2) as failure_rate
FROM telemetry_events
WHERE created_at >= NOW() - INTERVAL '7 days'
  AND event IN ('workflow_created', 'workflow_validation_failed');

---

Session & System Events

session_start

{
  "event": "session_start",
  "properties": {
    "version": "2.22.15",
    "platform": "darwin",
    "arch": "arm64",
    "nodeVersion": "v18.17.0",
    "isDocker": false,
    "cloudPlatform": null,
    "mcpMode": "stdio",
    "startupDurationMs": 1234
  }
}

Query: Platform distribution

SELECT
  properties->>'platform' as platform,
  properties->>'arch' as arch,
  COUNT(*) as sessions,
  AVG((properties->>'startupDurationMs')::int) as avg_startup_ms
FROM telemetry_events
WHERE event = 'session_start' AND created_at >= NOW() - INTERVAL '30 days'
GROUP BY 1, 2 ORDER BY 3 DESC;

---

Workflow Metadata Table Queries

Workflow Complexity Distribution

SELECT
  complexity,
  COUNT(*) as count,
  AVG(node_count) as avg_nodes,
  MAX(node_count) as max_nodes
FROM telemetry_workflows
GROUP BY complexity
ORDER BY count DESC;

Most Common Node Type Combinations

SELECT
  node_types,
  COUNT(*) as frequency
FROM telemetry_workflows
GROUP BY node_types
ORDER BY frequency DESC
LIMIT 20;

Workflows with Triggers vs Webhooks

SELECT
  has_trigger,
  has_webhook,
  COUNT(*) as count,
  ROUND(100.0 * COUNT(*) / (SELECT COUNT(*) FROM telemetry_workflows), 2) as percentage
FROM telemetry_workflows
GROUP BY 1, 2;

Deduplicated Workflows (by hash)

SELECT
  COUNT(DISTINCT workflow_hash) as unique_workflows,
  COUNT(*) as total_rows,
  COUNT(DISTINCT user_id) as unique_users
FROM telemetry_workflows;

---

Common Analysis Patterns

1. User Journey Analysis

-- Tool usage patterns for a user (anonymized)
WITH user_events AS (
  SELECT
    user_id,
    event,
    properties->>'tool' as tool,
    created_at,
    LAG(event) OVER(PARTITION BY user_id ORDER BY created_at) as prev_event
  FROM telemetry_events
  WHERE event IN ('tool_used', 'tool_sequence')
    AND created_at >= NOW() - INTERVAL '7 days'
)
SELECT
  prev_event,
  event,
  COUNT(*) as transitions
FROM user_events
WHERE prev_event IS NOT NULL
GROUP BY 1, 2
ORDER BY 3 DESC
LIMIT 20;

2. Performance Trends

-- Tool execution performance over time
WITH perf_data AS (
  SELECT
    properties->>'tool' as tool,
    (properties->>'duration')::int as duration,
    DATE(created_at) as date
  FROM telemetry_events
  WHERE event = 'tool_used'
    AND created_at >= NOW() - INTERVAL '30 days'
)
SELECT
  date,
  tool,
  COUNT(*) as executions,
  AVG(duration)::INTEGER as avg_duration_ms,
  PERCENTILE_CONT(0.95) WITHIN GROUP(ORDER BY duration) as p95_duration_ms,
  MAX(duration) as max_duration_ms
FROM perf_data
GROUP BY date, tool
ORDER BY date DESC, tool;

3. Error Analysis with Context

-- Recent errors with affected tools
SELECT
  properties->>'errorType' as error_type,
  properties->>'tool' as affected_tool,
  properties->>'context' as context,
  COUNT(*) as occurrences,
  MAX(created_at) as most_recent,
  COUNT(DISTINCT user_id) as users_affected
FROM telemetry_events
WHERE event = 'error_occurred'
  AND created_at >= NOW() - INTERVAL '24 hours'
GROUP BY 1, 2, 3
ORDER BY 4 DESC, 5 DESC;

4. Node Configuration Patterns

-- Most configured nodes and their complexity
WITH config_data AS (
  SELECT
    properties->>'nodeType' as node_type,
    (properties->>'propertiesSet')::int as props_set,
    properties->>'usedDefaults' = 'true' as used_defaults
  FROM telemetry_events
  WHERE event = 'node_configuration'
    AND created_at >= NOW() - INTERVAL '30 days'
)
SELECT
  node_type,
  COUNT(*) as configurations,
  AVG(props_set)::INTEGER as avg_props_set,
  ROUND(100.0 * SUM(CASE WHEN used_defaults THEN 1 ELSE 0 END)
        / COUNT(*), 2) as default_usage_rate
FROM config_data
GROUP BY node_type
ORDER BY 2 DESC
LIMIT 20;

5. Search Effectiveness

-- Search queries and their success
SELECT
  properties->>'searchType' as search_type,
  COUNT(*) as total_searches,
  COUNT(*) FILTER(WHERE (properties->>'hasResults')::boolean) as with_results,
  ROUND(100.0 * COUNT(*) FILTER(WHERE (properties->>'hasResults')::boolean)
        / COUNT(*), 2) as success_rate,
  AVG((properties->>'resultsFound')::int) as avg_results
FROM telemetry_events
WHERE event = 'search_query'
  AND created_at >= NOW() - INTERVAL '7 days'
GROUP BY 1
ORDER BY 2 DESC;

---

Data Size Estimates

Current Data Volume

• Total Events: ~276K rows

• Size per Event: ~200 bytes (average)

• Total Size (events): ~55 MB

• Total Workflows: ~6.5K rows

• Size per Workflow: ~2 KB (sanitized)

• Total Size (workflows): ~13 MB

Total Current Storage: ~68 MB

Growth Projections

• Daily Events: ~1,000-2,000
• Monthly Growth: ~30-60 MB
• Annual Growth: ~360-720 MB

---

Helpful Constants

Event Type Values

tool_used
tool_sequence
error_occurred
validation_details
node_configuration
performance_metric
search_query
workflow_created
workflow_validation_failed
session_start
startup_completed
startup_error

Complexity Values

'simple'
'medium'
'complex'

Validation Status Values (for mutations)

'valid'
'invalid'
'unknown'

Instruction Type Values (for mutations)

'ai_generated'
'user_provided'
'auto_fix'
'validation_correction'

---

Tips & Tricks

Finding Zero-Result Searches

SELECT properties->>'query' as search_term, COUNT(*) as attempts
FROM telemetry_events
WHERE event = 'search_query'
  AND (properties->>'isZeroResults')::boolean = true
  AND created_at >= NOW() - INTERVAL '7 days'
GROUP BY 1 ORDER BY 2 DESC;

Identifying Slow Operations

SELECT
  properties->>'operation' as operation,
  COUNT(*) as count,
  PERCENTILE_CONT(0.99) WITHIN GROUP(ORDER BY (properties->>'duration')::int) as p99_ms
FROM telemetry_events
WHERE event = 'performance_metric'
  AND created_at >= NOW() - INTERVAL '7 days'
GROUP BY 1
HAVING PERCENTILE_CONT(0.99) WITHIN GROUP(ORDER BY (properties->>'duration')::int) > 1000
ORDER BY 3 DESC;

User Retention Analysis

-- Active users by week
WITH weekly_users AS (
  SELECT
    DATE_TRUNC('week', created_at) as week,
    COUNT(DISTINCT user_id) as active_users
  FROM telemetry_events
  WHERE created_at >= NOW() - INTERVAL '90 days'
  GROUP BY 1
)
SELECT week, active_users
FROM weekly_users
ORDER BY week DESC;

Platform Usage Breakdown

SELECT
  properties->>'platform' as platform,
  properties->>'arch' as architecture,
  COALESCE(properties->>'cloudPlatform', 'local') as deployment,
  COUNT(DISTINCT user_id) as unique_users
FROM telemetry_events
WHERE event = 'session_start'
  AND created_at >= NOW() - INTERVAL '30 days'
GROUP BY 1, 2, 3
ORDER BY 4 DESC;

---

File References for Development

Source Code

• Types: /Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-types.ts
• Manager: /Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/telemetry-manager.ts
• Tracker: /Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/event-tracker.ts
• Processor: /Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/src/telemetry/batch-processor.ts

Documentation

• Full Analysis: /Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/TELEMETRY_ANALYSIS.md
• Mutation Spec: /Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/TELEMETRY_MUTATION_SPEC.md
• This Guide: /Users/romualdczlonkowski/Pliki/n8n-mcp/n8n-mcp/TELEMETRY_QUICK_REFERENCE.md

---

Last Updated: November 12, 2025