📡 Telemetry Events Specification¶

🎯 Eventos a Trackear¶

🔌 Plugin Lifecycle¶

plugin_loaded

{
  "event": "plugin_loaded",
  "timestamp": "2025-01-15T10:30:00Z",
  "plugin_version": "1.2.3",
  "plugin_format": "VST3",
  "host_daw": "Reaper",
  "host_version": "6.70",
  "os": "Windows 11",
  "os_version": "22H2",
  "cpu_arch": "x64",
  "sample_rate": 48000,
  "buffer_size": 512,
  "user_id": "a7f3c8e9d2b1..."  // SHA256 hash - anonimizado
}

plugin_unloaded

{
  "event": "plugin_unloaded",
  "timestamp": "2025-01-15T11:00:00Z",
  "session_duration_seconds": 1800,
  "user_id": "a7f3c8e9d2b1..."
}

plugin_activated

{
  "event": "plugin_activated",
  "timestamp": "2025-01-15T10:30:05Z",
  "activation_time_ms": 127,
  "user_id": "a7f3c8e9d2b1..."
}

plugin_deactivated

{
  "event": "plugin_deactivated",
  "timestamp": "2025-01-15T11:00:00Z",
  "processing_time_total_seconds": 1795,
  "user_id": "a7f3c8e9d2b1..."
}

preset_changed

{
  "event": "preset_changed",
  "timestamp": "2025-01-15T10:35:00Z",
  "preset_name": "Dark Reverb",  // OK si no contiene PII
  "preset_category": "Reverbs",
  "preset_source": "factory",    // factory | user | downloaded
  "user_id": "a7f3c8e9d2b1..."
}

parameter_changed

{
  "event": "parameter_changed",
  "timestamp": "2025-01-15T10:36:00Z",
  "parameter_id": "cutoff_frequency",
  "parameter_value_normalized": 0.75,  // 0-1 normalized (no exact values)
  "change_source": "ui",              // ui | automation | midi
  "user_id": "a7f3c8e9d2b1..."
}

feature_used

{
  "event": "feature_used",
  "timestamp": "2025-01-15T10:40:00Z",
  "feature": "eq_band_3",
  "action": "enabled",  // enabled | disabled | reset
  "user_id": "a7f3c8e9d2b1..."
}

ui_element_clicked

{
  "event": "ui_element_clicked",
  "timestamp": "2025-01-15T10:41:00Z",
  "element": "visualizer_tab",
  "section": "analyzer",
  "user_id": "a7f3c8e9d2b1..."
}

💥 Errors & Crashes¶

crash

{
  "event": "crash",
  "timestamp": "2025-01-15T10:50:00Z",
  "error_code": "E_OUT_OF_MEMORY",
  "error_message": "Failed to allocate buffer",  // Sanitized
  "stack_trace": [
    "AudioProcessor::process()+0x42",  // No absolute paths
    "PluginHost::processBlock()+0x1A",
    "main()+0x8F"
  ],
  "plugin_version": "1.2.3",
  "os": "Windows 11",
  "available_memory_mb": 1024,
  "user_id": "a7f3c8e9d2b1..."
}

error_occurred

{
  "event": "error_occurred",
  "timestamp": "2025-01-15T10:45:00Z",
  "error_category": "file_io",
  "error_code": "E_FILE_NOT_FOUND",
  "severity": "warning",  // info | warning | error | fatal
  "recoverable": true,
  "user_id": "a7f3c8e9d2b1..."
}

assertion_failed

{
  "event": "assertion_failed",
  "timestamp": "2025-01-15T10:47:00Z",
  "assertion": "buffer != nullptr",
  "file": "AudioProcessor.cpp",  // Filename only, no full path
  "line": 127,
  "plugin_version": "1.2.3",
  "user_id": "a7f3c8e9d2b1..."
}

⚡ Performance Metrics¶

performance_sample

{
  "event": "performance_sample",
  "timestamp": "2025-01-15T10:55:00Z",
  "cpu_usage_percent": 42.5,
  "memory_usage_mb": 256,
  "buffer_underruns": 0,
  "processing_time_us": 3200,  // Microseconds per buffer
  "sample_rate": 48000,
  "buffer_size": 512,
  "user_id": "a7f3c8e9d2b1..."
}

latency_measured

{
  "event": "latency_measured",
  "timestamp": "2025-01-15T10:56:00Z",
  "total_latency_samples": 1024,
  "plugin_latency_samples": 512,
  "user_id": "a7f3c8e9d2b1..."
}

🎫 License Events¶

license_activated

{
  "event": "license_activated",
  "timestamp": "2025-01-15T09:00:00Z",
  "license_type": "pro",  // trial | basic | pro | enterprise
  "activation_method": "online",  // online | offline
  "user_id": "a7f3c8e9d2b1..."
  // ❌ NO incluir license key
}

license_validation_failed

{
  "event": "license_validation_failed",
  "timestamp": "2025-01-15T09:01:00Z",
  "failure_reason": "expired",  // expired | invalid | network_error
  "user_id": "a7f3c8e9d2b1..."
}

trial_started

{
  "event": "trial_started",
  "timestamp": "2025-01-15T09:00:00Z",
  "trial_duration_days": 14,
  "user_id": "a7f3c8e9d2b1..."
}

trial_expired

{
  "event": "trial_expired",
  "timestamp": "2025-01-29T09:00:00Z",
  "days_used": 14,
  "user_id": "a7f3c8e9d2b1..."
}

📊 Analytics Events¶

session_started

{
  "event": "session_started",
  "timestamp": "2025-01-15T10:30:00Z",
  "session_id": "b9e4f7a2...",  // Unique session identifier
  "user_id": "a7f3c8e9d2b1..."
}

session_ended

{
  "event": "session_ended",
  "timestamp": "2025-01-15T11:30:00Z",
  "session_id": "b9e4f7a2...",
  "duration_seconds": 3600,
  "events_count": 42,
  "user_id": "a7f3c8e9d2b1..."
}

update_checked

{
  "event": "update_checked",
  "timestamp": "2025-01-15T10:30:10Z",
  "current_version": "1.2.3",
  "latest_version": "1.3.0",
  "update_available": true,
  "user_id": "a7f3c8e9d2b1..."
}

update_installed

{
  "event": "update_installed",
  "timestamp": "2025-01-15T11:00:00Z",
  "previous_version": "1.2.3",
  "new_version": "1.3.0",
  "user_id": "a7f3c8e9d2b1..."
}

🚫 NEVER Track¶

❌ Prohibited Data¶

Data Type	Why Prohibited	Example
User email	PII - GDPR violation	`john.doe@example.com`
User name	PII - GDPR violation	`John Doe`
License keys	Security risk	`ABC-123-DEF-456`
Full file paths	Contains username (PII)	`C:\Users\John\Documents\...`
IP addresses	PII without consent	`192.168.1.100`
MAC addresses	Device identifier (PII)	`00:1B:44:11:3A:B7`
Exact coordinates	Location tracking	`40.7128° N, 74.0060° W`
Audio content	User creative work	Waveform data, samples
Project files	User creative work	DAW project contents
Chat/messages	Private communication	Support chat transcripts
Credit card info	PCI-DSS violation	Any payment details

✅ Allowed Alternatives¶

Prohibited	Allowed Alternative
User email	SHA256 hash of email
User name	SHA256 hash of user ID
License key	License type (trial/pro/etc.)
Full file path	Filename only or relative path
IP address	Country/region only (via GeoIP)
MAC address	SHA256 hash
Exact GPS	City-level location only
Audio content	Metadata only (sample rate, length, format)

📋 Event Schema¶

Base Event Structure¶

All events must include these base fields:

{
  "event": "event_name",           // Required: Event type
  "timestamp": "ISO8601",          // Required: When it occurred
  "session_id": "uuid",            // Required: Session identifier
  "user_id": "sha256_hash",        // Required: Anonymized user ID
  "plugin_version": "semver",      // Required: Plugin version
  "schema_version": "1.0"          // Required: Event schema version
}

Optional Context Fields¶

{
  "os": "Windows 11",              // Operating system
  "os_version": "22H2",            // OS version
  "cpu_arch": "x64",               // CPU architecture
  "host_daw": "Reaper",            // DAW name
  "host_version": "6.70",          // DAW version
  "sample_rate": 48000,            // Audio sample rate
  "buffer_size": 512,              // Audio buffer size
  "locale": "en_US"                // User locale (language/region)
}

Events are categorized by consent level:

Crash reports (for stability)
License validation (for anti-piracy)
Critical errors

Analytics (Requires opt-in)¶

Feature usage
Performance metrics
Session analytics

Marketing (Requires explicit opt-in)¶

A/B testing
Feature discovery
User behavior analysis

Implementation¶

enum class ConsentLevel {
    Necessary = 0,  // Always allowed
    Analytics = 1,  // Opt-in
    Marketing = 2   // Explicit opt-in
};

struct TelemetryEvent {
    std::string event;
    ConsentLevel required_consent;
    nlohmann::json data;
};

// Example
TelemetryEvent crash_event{
    .event = "crash",
    .required_consent = ConsentLevel::Necessary,
    .data = {/* ... */}
};

TelemetryEvent feature_event{
    .event = "feature_used",
    .required_consent = ConsentLevel::Analytics,
    .data = {/* ... */}
};

📊 Event Frequency Limits¶

To avoid telemetry spam:

Event Type	Max Frequency	Batching
crash	Immediate	No batch
error_occurred	10/minute	Batch 5 min
performance_sample	1/minute	Batch 5 min
parameter_changed	1/second (per param)	Batch 5 min
session_started	1/session	Immediate
session_ended	1/session	Immediate

🧪 Testing Events¶

For development/testing, use test_mode flag:

{
  "event": "plugin_loaded",
  "test_mode": true,  // Filtered out in production analytics
  "timestamp": "...",
  // ... rest of event
}