Merge pull request #811 from Chris0Jeky/feature/error-tracking-analytics

OBS-02: Error tracking and product analytics foundation

Author: Chris0Jeky

backend/src/Taskdeck.Api/Controllers/TelemetryController.cs

@@ -0,0 +1,120 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Taskdeck.Application.Services;
+
+namespace Taskdeck.Api.Controllers;
+
+/// <summary>
+/// Endpoints for opt-in product telemetry event recording and client configuration.
+/// All telemetry is disabled by default and requires explicit opt-in.
+/// </summary>
+[ApiController]
+[Route("api/telemetry")]
+[Authorize]
+public class TelemetryController : ControllerBase
+{
+    private readonly ITelemetryEventService _telemetryEventService;
+    private readonly SentrySettings _sentrySettings;
+    private readonly AnalyticsSettings _analyticsSettings;
+    private readonly TelemetrySettings _telemetrySettings;
+
+    public TelemetryController(
+        ITelemetryEventService telemetryEventService,
+        SentrySettings sentrySettings,
+        AnalyticsSettings analyticsSettings,
+        TelemetrySettings telemetrySettings)
+    {
+        _telemetryEventService = telemetryEventService;
+        _sentrySettings = sentrySettings;
+        _analyticsSettings = analyticsSettings;
+        _telemetrySettings = telemetrySettings;
+    }
+
+    /// <summary>
+    /// Returns client-side telemetry configuration. The frontend uses this to
+    /// determine which integrations are available and how to initialize them.
+    /// DSNs and script URLs are only returned when the corresponding integration
+    /// is enabled. No secrets or API keys are exposed.
+    /// </summary>
+    [HttpGet("config")]
+    [AllowAnonymous]
+    public IActionResult GetConfig()
+    {
+        return Ok(new ClientTelemetryConfigResponse
+        {
+            Sentry = new SentryClientConfig
+            {
+                Enabled = _sentrySettings.Enabled,
+                Dsn = _sentrySettings.Enabled ? _sentrySettings.Dsn : string.Empty,
+                Environment = _sentrySettings.Environment,
+                TracesSampleRate = _sentrySettings.TracesSampleRate,
+            },
+            Analytics = new AnalyticsClientConfig
+            {
+                Enabled = _analyticsSettings.Enabled,
+                Provider = _analyticsSettings.Enabled ? _analyticsSettings.Provider : string.Empty,
+                ScriptUrl = _analyticsSettings.Enabled ? _analyticsSettings.ScriptUrl : string.Empty,
+                SiteId = _analyticsSettings.Enabled ? _analyticsSettings.SiteId : string.Empty,
+            },
+            Telemetry = new TelemetryClientConfig
+            {
+                Enabled = _telemetrySettings.Enabled,
+            },
+        });
+    }
+
+    /// <summary>
+    /// Records a batch of product telemetry events. Requires authentication.
+    /// Events are validated against the taxonomy naming convention and rejected
+    /// if telemetry is disabled on the server.
+    /// </summary>
+    [HttpPost("events")]
+    public IActionResult RecordEvents([FromBody] TelemetryBatchRequest? request)
+    {
+        if (!_telemetryEventService.IsEnabled)
+        {
+            return Ok(new { recorded = 0, message = "Telemetry is disabled on this server." });
+        }
+
+        if (request == null || request.Events == null || request.Events.Count == 0)
+        {
+            return BadRequest(new { error = "No events provided." });
+        }
+
+        var recorded = _telemetryEventService.RecordEvents(request.Events);
+        return Ok(new { recorded });
+    }
+}
+
+public sealed class ClientTelemetryConfigResponse
+{
+    public SentryClientConfig Sentry { get; set; } = new();
+    public AnalyticsClientConfig Analytics { get; set; } = new();
+    public TelemetryClientConfig Telemetry { get; set; } = new();
+}
+
+public sealed class SentryClientConfig
+{
+    public bool Enabled { get; set; }
+    public string Dsn { get; set; } = string.Empty;
+    public string Environment { get; set; } = string.Empty;
+    public double TracesSampleRate { get; set; }
+}
+
+public sealed class AnalyticsClientConfig
+{
+    public bool Enabled { get; set; }
+    public string Provider { get; set; } = string.Empty;
+    public string ScriptUrl { get; set; } = string.Empty;
+    public string SiteId { get; set; } = string.Empty;
+}
+
+public sealed class TelemetryClientConfig
+{
+    public bool Enabled { get; set; }
+}
+
+public sealed class TelemetryBatchRequest
+{
+    public List<TelemetryEvent> Events { get; set; } = new();
+}

backend/src/Taskdeck.Api/Extensions/SentryRegistration.cs

@@ -0,0 +1,126 @@
+using System.Text.RegularExpressions;
+using Taskdeck.Application.Services;
+
+namespace Taskdeck.Api.Extensions;
+
+public static class SentryRegistration
+{
+    // Patterns for PII that may leak through exception messages
+    private static readonly Regex EmailPattern = new(
+        @"[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}",
+        RegexOptions.Compiled);
+
+    private static readonly Regex JwtPattern = new(
+        @"eyJ[a-zA-Z0-9_\-]+\.eyJ[a-zA-Z0-9_\-]+\.[a-zA-Z0-9_\-]+",
+        RegexOptions.Compiled);
+
+    /// <summary>
+    /// Adds Sentry error tracking when enabled via configuration.
+    /// Disabled by default — requires Sentry:Enabled=true and a valid DSN.
+    /// PII is never sent (SendDefaultPii is always forced to false).
+    /// </summary>
+    public static WebApplicationBuilder AddTaskdeckSentry(
+        this WebApplicationBuilder builder,
+        SentrySettings sentrySettings)
+    {
+        if (!sentrySettings.Enabled)
+        {
+            return builder;
+        }
+
+        if (string.IsNullOrWhiteSpace(sentrySettings.Dsn))
+        {
+            return builder;
+        }
+
+        builder.WebHost.UseSentry(options =>
+        {
+            options.Dsn = sentrySettings.Dsn;
+            options.Environment = sentrySettings.Environment;
+            options.TracesSampleRate = sentrySettings.TracesSampleRate;
+
+            // Hard privacy guardrail: never send PII regardless of config.
+            // This prevents usernames, emails, IP addresses, and request
+            // bodies from being included in Sentry events.
+            options.SendDefaultPii = false;
+
+            // Prevent hostname leakage
+            options.ServerName = string.Empty;
+
+            // Scrub PII from exception messages and event data before sending.
+            // Exception messages may contain emails, JWT tokens, or usernames
+            // that were interpolated into error strings.
+            options.SetBeforeSend((sentryEvent, _) =>
+            {
+                if (sentryEvent.Message?.Formatted != null)
+                {
+                    sentryEvent.Message = new Sentry.SentryMessage
+                    {
+                        Formatted = ScrubPii(sentryEvent.Message.Formatted)
+                    };
+                }
+
+                // Scrub PII from captured exception values. The Sentry SDK copies
+                // exception messages into SentryException objects with a Value property.
+                if (sentryEvent.SentryExceptions != null)
+                {
+                    foreach (var sentryException in sentryEvent.SentryExceptions)
+                    {
+                        if (!string.IsNullOrEmpty(sentryException.Value))
+                        {
+                            sentryException.Value = ScrubPii(sentryException.Value);
+                        }
+                    }
+                }
+
+                return sentryEvent;
+            });
+
+            // Strip sensitive data from breadcrumbs. Sentry breadcrumb Data
+            // is read-only, so we filter by dropping HTTP breadcrumbs that
+            // carry authorization or cookie information.
+            options.SetBeforeBreadcrumb(breadcrumb =>
+            {
+                if (breadcrumb.Category == "http" && breadcrumb.Data != null)
+                {
+                    var sensitiveKeys = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
+                    {
+                        "Authorization", "Cookie", "Set-Cookie", "X-Api-Key"
+                    };
+                    foreach (var key in breadcrumb.Data.Keys)
+                    {
+                        if (sensitiveKeys.Contains(key))
+                        {
+                            // Data contains sensitive headers — drop entire breadcrumb
+                            // to prevent PII leakage. The breadcrumb is replaced with
+                            // a sanitized version without data.
+                            return new Sentry.Breadcrumb(
+                                message: breadcrumb.Message ?? string.Empty,
+                                type: breadcrumb.Type ?? string.Empty,
+                                data: null,
+                                category: breadcrumb.Category,
+                                level: breadcrumb.Level);
+                        }
+                    }
+                }
+
+                return breadcrumb;
+            });
+        });
+
+        return builder;
+    }
+
+    /// <summary>
+    /// Scrubs known PII patterns (emails, JWTs) from a string.
+    /// </summary>
+    internal static string ScrubPii(string input)
+    {
+        if (string.IsNullOrEmpty(input)) return input;
+
+        var result = EmailPattern.Replace(input, "[email-redacted]");
+        result = JwtPattern.Replace(result, "[jwt-redacted]");
+        return result;
+    }
+
+}

backend/src/Taskdeck.Api/Extensions/SettingsRegistration.cs

@@ -11,7 +11,10 @@ public static IServiceCollection AddTaskdeckSettings(
         out ObservabilitySettings observabilitySettings,
         out RateLimitingSettings rateLimitingSettings,
         out JwtSettings jwtSettings,
-        out GitHubOAuthSettings gitHubOAuthSettings)
+        out GitHubOAuthSettings gitHubOAuthSettings,
+        out SentrySettings sentrySettings,
+        out TelemetrySettings telemetrySettings,
+        out AnalyticsSettings analyticsSettings)
     {
         observabilitySettings = configuration
             .GetSection("Observability")
@@ -49,6 +52,24 @@ public static IServiceCollection AddTaskdeckSettings(
         sandboxSettings.Enabled = sandboxSettings.Enabled && environment.IsDevelopment();
         services.AddSingleton(sandboxSettings);
 
+        sentrySettings = configuration
+            .GetSection("Sentry")
+            .Get<SentrySettings>() ?? new SentrySettings();
+        services.AddSingleton(sentrySettings);
+
+        telemetrySettings = configuration
+            .GetSection("Telemetry")
+            .Get<TelemetrySettings>() ?? new TelemetrySettings();
+        services.AddSingleton(telemetrySettings);
+
+        analyticsSettings = configuration
+            .GetSection("Analytics")
+            .Get<AnalyticsSettings>() ?? new AnalyticsSettings();
+        services.AddSingleton(analyticsSettings);
+
+        // Register telemetry event service (opt-in guard is internal to the service)
+        services.AddSingleton<ITelemetryEventService, TelemetryEventService>();
+
         return services;
     }
 }

backend/src/Taskdeck.Api/Program.cs

@@ -156,14 +156,17 @@
     }
 });
 
-// Bind configuration settings (observability, rate limiting, security headers, JWT, etc.)
+// Bind configuration settings (observability, rate limiting, security headers, JWT, Sentry, telemetry, analytics)
 builder.Services.AddTaskdeckSettings(
     builder.Configuration,
     builder.Environment,
     out var observabilitySettings,
     out var rateLimitingSettings,
     out var jwtSettings,
-    out var gitHubOAuthSettings);
+    out var gitHubOAuthSettings,
+    out var sentrySettings,
+    out _,  // telemetrySettings — registered in DI by AddTaskdeckSettings
+    out _); // analyticsSettings — registered in DI by AddTaskdeckSettings
 
 // Add Infrastructure (DbContext, Repositories)
 builder.Services.AddInfrastructure(builder.Configuration);
@@ -196,6 +199,9 @@
 // Add OpenTelemetry observability
 builder.Services.AddTaskdeckObservability(observabilitySettings);
 
+// Add Sentry error tracking (config-gated, disabled by default)
+builder.AddTaskdeckSentry(sentrySettings);
+
 // Add worker services (LLM queue, proposal housekeeping, outbound webhooks)
 builder.Services.AddTaskdeckWorkers(builder.Configuration, builder.Environment);
 

backend/src/Taskdeck.Api/Taskdeck.Api.csproj

@@ -35,6 +35,7 @@
     <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.15.1" />
     <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.15.1" />
     <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.15.0" />
+    <PackageReference Include="Sentry.AspNetCore" Version="5.6.0" />
     <PackageReference Include="Swashbuckle.AspNetCore" Version="10.1.7" />
   </ItemGroup>
 

backend/src/Taskdeck.Api/appsettings.json

@@ -38,6 +38,23 @@
     "EnableConsoleExporter": false,
     "MetricExportIntervalSeconds": 30
   },
+  "Sentry": {
+    "Enabled": false,
+    "Dsn": "",
+    "Environment": "production",
+    "TracesSampleRate": 0.1,
+    "SendDefaultPii": false
+  },
+  "Telemetry": {
+    "Enabled": false,
+    "MaxBatchSize": 100
+  },
+  "Analytics": {
+    "Enabled": false,
+    "Provider": "",
+    "ScriptUrl": "",
+    "SiteId": ""
+  },
   "RateLimiting": {
     "Enabled": true,
     "AuthPerIp": {

backend/src/Taskdeck.Application/Services/AnalyticsSettings.cs

@@ -0,0 +1,29 @@
+namespace Taskdeck.Application.Services;
+
+/// <summary>
+/// Configuration for self-hosted web analytics (Plausible or Umami).
+/// Disabled by default — the frontend reads these settings from a config endpoint
+/// and injects the analytics script only when configured.
+/// </summary>
+public sealed class AnalyticsSettings
+{
+    /// <summary>
+    /// Master switch. Default: false (opt-in only).
+    /// </summary>
+    public bool Enabled { get; set; }
+
+    /// <summary>
+    /// Analytics provider: "plausible" or "umami". Case-insensitive.
+    /// </summary>
+    public string Provider { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Full URL to the analytics script (e.g. "https://plausible.example.com/js/script.js").
+    /// </summary>
+    public string ScriptUrl { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Site identifier / website ID used by the analytics provider.
+    /// </summary>
+    public string SiteId { get; set; } = string.Empty;
+}