@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/dotnet/logging.md

@@ -0,0 +1,556 @@
+# Logging — Sentry .NET SDK
+
+> **Minimum SDK: `Sentry` ≥ 6.0.0** for the stable native `SentrySdk.Logger` +
+> `EnableLogs` (shipped experimental behind `options.Experimental` in 5.14.0–5.x)\
+> Integration packages (`Sentry.Extensions.Logging`, `Sentry.Serilog`, `Sentry.NLog`,
+> `Sentry.Log4Net`) are long-established\
+> Native structured logs forwarded through integrations: requires SDK ≥ 6.0.0, and only
+> for `Sentry.Extensions.Logging`, `Sentry.AspNetCore`, `Sentry.Maui`,
+> `Sentry.Google.Cloud.Functions`, and `Sentry.Serilog` (NLog and log4net do **not**
+> forward structured logs)
+
+---
+
+## Enabling Native Structured Logs
+
+`EnableLogs` must be set to `true` — logging is **disabled by default**:
+
+```csharp
+SentrySdk.Init(options =>
+{
+    options.Dsn = "https://examplePublicKey@o0.ingest.sentry.io/0";
+    options.EnableLogs = true; // Required — logs are silently no-ops without this
+});
+```
+
+Without `EnableLogs = true`, all `SentrySdk.Logger.*` calls are silently discarded.
+
+---
+
+## Native Logger API — Six Levels
+
+The native logger type is `SentryStructuredLogger`, accessed via `SentrySdk.Logger`:
+
+```csharp
+SentrySdk.Logger.LogTrace("Entering method Foo");
+SentrySdk.Logger.LogDebug("Loaded {0} items", itemCount);
+SentrySdk.Logger.LogInfo("Order created successfully");
+SentrySdk.Logger.LogWarning("Cache miss for key {0}", cacheKey);
+SentrySdk.Logger.LogError("A {0} error occurred", "critical");
+SentrySdk.Logger.LogFatal("Unrecoverable error — shutting down");
+```
+
+| Level     | Method         | Typical Use                                                          |
+| --------- | -------------- | -------------------------------------------------------------------- |
+| `Trace`   | `LogTrace()`   | Ultra-granular method entry/exit; high-volume — filter in production |
+| `Debug`   | `LogDebug()`   | Development diagnostics, cache hits/misses                           |
+| `Info`    | `LogInfo()`    | Normal business milestones, confirmations                            |
+| `Warning` | `LogWarning()` | Degraded state, approaching limits, recoverable issues               |
+| `Error`   | `LogError()`   | Failures requiring attention                                         |
+| `Fatal`   | `LogFatal()`   | Critical failures, system unavailable                                |
+
+### Attaching Custom Attributes
+
+Use the lambda overload to attach typed key-value attributes to a log entry:
+
+```csharp
+SentrySdk.Logger.LogWarning(static log =>
+{
+    log.SetAttribute("request.id", 12345);
+    log.SetAttribute("user.tier", "premium");
+    log.SetAttribute("is.retried", true);
+}, "Payment declined for order {0}", orderId);
+```
+
+### Supported Attribute Value Types
+
+| Category       | Types                                                             |
+| -------------- | ----------------------------------------------------------------- |
+| Textual        | `string`, `char`                                                  |
+| Logical        | `bool`                                                            |
+| Integral       | `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, `nint` |
+| Floating-point | `float`, `double`                                                 |
+| Other          | Any type via `ToString()` fallback                                |
+
+---
+
+## Log Filtering — `SetBeforeSendLog`
+
+Use `SetBeforeSendLog` to modify or drop logs before transmission.
+Return `null` to discard:
+
+```csharp
+SentrySdk.Init(options =>
+{
+    options.Dsn = "https://...@sentry.io/...";
+    options.EnableLogs = true;
+
+    options.SetBeforeSendLog(static log =>
+    {
+        // Drop all Info and Trace logs in production
+        if (log.Level is SentryLogLevel.Info or SentryLogLevel.Trace)
+            return null;
+
+        // Drop noisy health-check messages
+        if (log.Message?.Contains("/health") == true)
+            return null;
+
+        // Enrich surviving logs
+        log.SetAttribute("app.version", "2.1.0");
+
+        return log;
+    });
+});
+```
+
+### The `SentryLog` Object
+
+| Member              | Type             | Description                               |
+| ------------------- | ---------------- | ----------------------------------------- |
+| `Timestamp`         | `DateTimeOffset` | When the log was created                  |
+| `TraceId`           | `SentryId`       | Active trace ID — links log to a trace    |
+| `SpanId`            | `SpanId?`        | Active span ID — links log to a span      |
+| `Level`             | `SentryLogLevel` | Trace, Debug, Info, Warning, Error, Fatal |
+| `Message`           | `string`         | Formatted log message                     |
+| `Template`          | `string?`        | Original message template (if structured) |
+| `Parameters`        | `ImmutableArray` | Template parameters                       |
+| `TryGetAttribute()` | method           | Read an attribute                         |
+| `SetAttribute()`    | method           | Write/modify an attribute                 |
+
+---
+
+## Automatically Attached Attributes
+
+These are added by the SDK to every log without any configuration:
+
+| Attribute Key                        | Source                                                                   |
+| ------------------------------------ | ------------------------------------------------------------------------ |
+| `environment`                        | SDK config                                                               |
+| `release`                            | SDK config                                                               |
+| `sdk.name`, `sdk.version`            | SDK internals                                                            |
+| `message.template`                   | Message template                                                         |
+| `message.parameter.0`, `.1`, …       | Template parameters                                                      |
+| `server.address`                     | Host info (requires `SendDefaultPii = true` or an explicit `ServerName`) |
+| `user.id`, `user.name`, `user.email` | Active scope user (attached whenever the scope’s `User` has values)      |
+| `origin`                             | Integration that created the log                                         |
+
+---
+
+## Integration: Microsoft.Extensions.Logging (ILogger)
+
+### Install
+
+```shell
+dotnet add package Sentry.Extensions.Logging
+```
+
+### What it does
+
+The MEL integration provides **three capabilities** simultaneously:
+
+1. Stores log messages as **breadcrumbs** (attached to the next error event as context)
+2. Sends logs at or above the event threshold as **Sentry error events**
+3. Forwards logs as **native Sentry structured logs** (SDK ≥ 6.0.0)
+
+### ASP.NET Core / Generic Host Setup (Recommended)
+
+```csharp
+// Program.cs
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Logging.AddSentry(o =>
+{
+    o.Dsn = "https://...@sentry.io/...";
+    o.MinimumBreadcrumbLevel = LogLevel.Debug;   // default: Information
+    o.MinimumEventLevel = LogLevel.Error;         // default: Error
+    o.InitializeSdk = true;                       // set false if using SentrySdk.Init elsewhere
+});
+```
+
+Or configure via `appsettings.json`:
+
+```json
+{
+  "Sentry": {
+    "Dsn": "https://...@sentry.io/...",
+    "MinimumBreadcrumbLevel": "Information",
+    "MinimumEventLevel": "Error",
+    "SendDefaultPii": true,
+    "MaxBreadcrumbs": 100
+  }
+}
+```
+
+```csharp
+builder.Logging.AddSentry(); // reads Sentry section from appsettings.json
+```
+
+### Direct Setup (no DI)
+
+```csharp
+var loggerFactory = LoggerFactory.Create(logging =>
+{
+    logging.AddSentry(o => o.Dsn = "https://...@sentry.io/...");
+});
+ILogger logger = loggerFactory.CreateLogger<MyClass>();
+```
+
+### Usage
+
+Once configured, use standard `ILogger<T>` — no Sentry-specific code required:
+
+```csharp
+public class OrderService
+{
+    private readonly ILogger<OrderService> _logger;
+
+    public OrderService(ILogger<OrderService> logger) => _logger = logger;
+
+    public async Task ProcessOrderAsync(int orderId)
+    {
+        _logger.LogInformation("Processing order {OrderId}", orderId); // → breadcrumb
+
+        try
+        {
+            await _paymentService.ChargeAsync(orderId);
+            _logger.LogInformation("Order {OrderId} paid successfully", orderId);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "Failed to process order {OrderId}", orderId); // → Sentry event
+            throw;
+        }
+    }
+}
+```
+
+### Configuration Options
+
+| Option                   | Type                   | Default       | Description                                                                                         |
+| ------------------------ | ---------------------- | ------------- | --------------------------------------------------------------------------------------------------- |
+| `MinimumBreadcrumbLevel` | `LogLevel`             | `Information` | Threshold for breadcrumb storage                                                                    |
+| `MinimumEventLevel`      | `LogLevel`             | `Error`       | Threshold for sending Sentry error events                                                           |
+| `InitializeSdk`          | `bool`                 | `true`        | Auto-init SDK. Set `false` when using `SentrySdk.Init`                                              |
+| `AddLogEntryFilter(...)` | method                 | —             | Register a custom `ILogEntryFilter` for pre-processing (the underlying `Filters` array is internal) |
+| `TagFilters`             | `IList<StringOrRegex>` | —             | Inherited from core `SentryOptions`; drops tags whose key matches by substring or regex             |
+
+### Important Behavior Notes
+
+- **Breadcrumb cascade**: A `LogError` event includes ALL breadcrumbs accumulated since
+  the last event — so the full Info/Warning/Error history is attached.
+- **Self-filtering**: Log entries whose category name is `"Sentry"` or starts with
+  `"Sentry."` are excluded to prevent infinite loops.
+- **Single init**: Set `InitializeSdk = false` if calling `SentrySdk.Init()` elsewhere
+  in your startup.
+- **Empty DSN** disables the SDK entirely.
+
+---
+
+## Integration: Serilog
+
+### Install
+
+```shell
+dotnet add package Sentry.Serilog
+```
+
+### What it does
+
+Same three capabilities as MEL: breadcrumbs, Sentry error events, and native structured
+logs.
+
+### Basic Setup (Serilog initializes Sentry)
+
+```csharp
+Log.Logger = new LoggerConfiguration()
+    .MinimumLevel.Debug()
+    .WriteTo.Sentry(o =>
+    {
+        o.Dsn = "https://...@sentry.io/...";
+        o.MinimumBreadcrumbLevel = LogEventLevel.Debug;   // default: Information
+        o.MinimumEventLevel = LogEventLevel.Warning;      // default: Error
+    })
+    .WriteTo.Console()
+    .CreateLogger();
+```
+
+### Setup (Sentry initialized separately)
+
+```csharp
+SentrySdk.Init(o => o.Dsn = "...");
+
+Log.Logger = new LoggerConfiguration()
+    .WriteTo.Sentry(o =>
+    {
+        o.InitializeSdk = false; // ← avoid double-init
+        o.MinimumBreadcrumbLevel = LogEventLevel.Information;
+        o.MinimumEventLevel = LogEventLevel.Error;
+    })
+    .CreateLogger();
+```
+
+### ASP.NET Core with Serilog
+
+```csharp
+builder.Host.UseSerilog((ctx, cfg) =>
+{
+    cfg.ReadFrom.Configuration(ctx.Configuration)
+       .WriteTo.Sentry(o =>
+       {
+           o.Dsn = ctx.Configuration["Sentry:Dsn"];
+           o.MinimumBreadcrumbLevel = LogEventLevel.Debug;
+           o.MinimumEventLevel = LogEventLevel.Error;
+       });
+});
+```
+
+### Usage
+
+```csharp
+var log = Log.ForContext<OrderService>();
+
+log.Information("Processing order {OrderId} for {CustomerId}", orderId, customerId); // → breadcrumb
+log.Error(ex, "Payment failed for order {OrderId}", orderId); // → Sentry event
+```
+
+### Configuration Options
+
+| Option                   | Default       | Description                             |
+| ------------------------ | ------------- | --------------------------------------- |
+| `MinimumBreadcrumbLevel` | `Information` | Minimum `LogEventLevel` for breadcrumbs |
+| `MinimumEventLevel`      | `Error`       | Minimum level for Sentry error events   |
+| `InitializeSdk`          | `true`        | Whether this sink initializes the SDK   |
+
+---
+
+## Integration: NLog
+
+### Install
+
+```shell
+dotnet add package Sentry.NLog
+```
+
+### Code-Based Configuration
+
+```csharp
+LogManager.Configuration = new LoggingConfiguration();
+
+LogManager.Configuration.AddSentry(options =>
+{
+    options.Dsn = "https://...@sentry.io/...";
+    options.Layout = "${message}";
+    options.BreadcrumbLayout = "${logger}: ${message}";
+    options.MinimumBreadcrumbLevel = LogLevel.Debug;  // default: Info
+    options.MinimumEventLevel = LogLevel.Error;        // default: Error
+    options.AddTag("logger", "${logger}");
+    options.IgnoreEventsWithNoException = false;
+    options.IncludeEventPropertiesAsTags = true;
+});
+
+LogManager.ReconfigExistingLoggers();
+```
+
+### XML Configuration (nlog.config)
+
+```xml
+<?xml version="1.0" encoding="utf-8" ?>
+<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
+      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <extensions>
+    <add assembly="Sentry.NLog"/>
+  </extensions>
+
+  <targets>
+    <target xsi:type="Sentry"
+            name="sentry"
+            dsn="https://...@sentry.io/..."
+            minimumBreadcrumbLevel="Debug"
+            minimumEventLevel="Error"
+            layout="${message}"
+            breadcrumbLayout="${logger}: ${message}"
+            includeEventPropertiesAsTags="true"
+            ignoreEventsWithNoException="false">
+      <tag name="logger" layout="${logger}"/>
+    </target>
+  </targets>
+
+  <rules>
+    <!-- Set minlevel LOWER than breadcrumbLevel so SentryTarget sees all entries -->
+    <logger name="*" minlevel="Debug" writeTo="sentry"/>
+  </rules>
+</nlog>
+```
+
+### Usage
+
+```csharp
+private static readonly Logger Logger = LogManager.GetCurrentClassLogger();
+
+public void ProcessOrder(int orderId)
+{
+    Logger.Info("Processing order {orderId}", orderId); // → breadcrumb
+
+    try { /* ... */ }
+    catch (Exception ex)
+    {
+        Logger.Error(ex, "Failed to process order {orderId}", orderId); // → Sentry event
+    }
+}
+```
+
+### Configuration Options
+
+| Option                          | Default | Description                                     |
+| ------------------------------- | ------- | ----------------------------------------------- |
+| `MinimumBreadcrumbLevel`        | `Info`  | Threshold for breadcrumb storage                |
+| `MinimumEventLevel`             | `Error` | Threshold for Sentry error events               |
+| `InitializeSdk`                 | `true`  | Auto-init SDK when DSN provided                 |
+| `IgnoreEventsWithNoException`   | `false` | Skip entries with no attached exception         |
+| `IncludeEventPropertiesAsTags`  | `false` | Forward NLog properties as Sentry tags          |
+| `IncludeEventDataOnBreadcrumbs` | `false` | Attach event property data to breadcrumbs       |
+| `BreadcrumbLayout`              | —       | NLog layout string for breadcrumb text          |
+| `Layout`                        | —       | NLog layout string for event message            |
+| `Tags`                          | —       | Additional static tags attached to all messages |
+
+### ⚠️ Critical NLog Detail
+
+The `SentryTarget` must receive **all** log entries to correctly classify them as
+breadcrumbs vs events.
+Configure NLog’s `minlevel` **lower** than `MinimumBreadcrumbLevel`:
+
+```xml
+<!-- If MinimumBreadcrumbLevel = Info, set minlevel = Debug or Trace -->
+<logger name="*" minlevel="Debug" writeTo="sentry"/>
+```
+
+---
+
+## Integration: log4net
+
+### Install
+
+```shell
+dotnet add package Sentry.Log4Net
+```
+
+### XML Configuration (`app.config` / `web.config`)
+
+```xml
+<configuration>
+  <configSections>
+    <section name="log4net"
+             type="log4net.Config.Log4NetConfigurationSectionHandler, log4net"/>
+  </configSections>
+
+  <log4net>
+    <appender name="SentryAppender" type="Sentry.Log4Net.SentryAppender, Sentry.Log4Net">
+      <Dsn value="https://...@sentry.io/..."/>
+      <SendIdentity value="true"/>  <!-- send log4net Identity as Sentry user.id -->
+      <threshold value="INFO"/>     <!-- minimum level for this appender -->
+    </appender>
+
+    <root>
+      <level value="DEBUG"/>
+      <appender-ref ref="SentryAppender"/>
+    </root>
+  </log4net>
+</configuration>
+```
+
+### Programmatic Setup (for full SDK control)
+
+The XML appender supports only a subset of Sentry options.
+For full control, init the SDK separately and omit the `Dsn` element to skip auto-init:
+
+```csharp
+// Startup code
+SentrySdk.Init(options =>
+{
+    options.Dsn = "https://...@sentry.io/...";
+    options.Release = "my-app@1.0.0";
+    options.TracesSampleRate = 0.1;
+});
+```
+
+```xml
+<!-- In app.config — no <Dsn> element means SDK won't be re-initialized -->
+<appender name="SentryAppender" type="Sentry.Log4Net.SentryAppender, Sentry.Log4Net">
+  <SendIdentity value="true"/>
+  <threshold value="INFO"/>
+</appender>
+```
+
+### Usage
+
+```csharp
+private static readonly ILog Logger = LogManager.GetLogger(typeof(MyClass));
+
+Logger.Info("Processing started");       // → breadcrumb
+Logger.Warn("Low disk space warning");   // → breadcrumb
+Logger.Error("DB connection failed");    // → Sentry event
+Logger.Fatal("Application crash", ex);  // → Sentry event
+```
+
+### Key Appender Options
+
+| Option         | Description                             |
+| -------------- | --------------------------------------- |
+| `Dsn`          | Auto-initializes SDK when provided      |
+| `SendIdentity` | Reports log4net `Identity` as `user.id` |
+| `threshold`    | Minimum log4net level for this appender |
+
+---
+
+## Log-to-Trace Correlation
+
+Every log entry from any integration automatically carries the active trace and span
+IDs:
+
+| Field     | Description                                  |
+| --------- | -------------------------------------------- |
+| `TraceId` | Links the log to an active distributed trace |
+| `SpanId`  | Links the log to the currently active span   |
+
+In the Sentry UI you can navigate from an error or trace directly to the logs that
+occurred during that trace, and vice versa.
+No extra configuration required — correlation is automatic when `TracesSampleRate > 0`.
+
+---
+
+## Log Level Mapping
+
+| Sentry Level | MEL (`ILogger`) | Serilog       | NLog    | log4net |
+| ------------ | --------------- | ------------- | ------- | ------- |
+| `Trace`      | `Trace`         | `Verbose`     | `Trace` | `Trace` |
+| `Debug`      | `Debug`         | `Debug`       | `Debug` | `Debug` |
+| `Info`       | `Information`   | `Information` | `Info`  | `Info`  |
+| `Warning`    | `Warning`       | `Warning`     | `Warn`  | `Warn`  |
+| `Error`      | `Error`         | `Error`       | `Error` | `Error` |
+| `Fatal`      | `Critical`      | `Fatal`       | `Fatal` | `Fatal` |
+
+---
+
+## SDK Version Matrix
+
+| Feature                                                                                        | Min SDK Version |
+| ---------------------------------------------------------------------------------------------- | --------------- |
+| Native `SentrySdk.Logger` + `EnableLogs` (stable)                                              | **6.0.0**       |
+| Native structured logging (experimental, via `options.Experimental`)                           | **5.14.0**      |
+| Native logs forwarded via supported integrations (MEL, AspNetCore, Maui, GoogleCloud, Serilog) | **6.0.0**       |
+
+---
+
+## Troubleshooting
+
+| Issue                                              | Solution                                                                                                              |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Native logs not appearing in Sentry                | Verify `EnableLogs = true` in `SentrySdk.Init()` — without it, all `SentrySdk.Logger.*` calls are silently discarded  |
+| MEL/Serilog/NLog logs not triggering Sentry events | Check `MinimumEventLevel` — only logs at or above this threshold are sent as events; lower it if needed               |
+| NLog: only Error/Fatal seen, no breadcrumbs        | NLog `<logger minlevel>` must be set **lower** than `MinimumBreadcrumbLevel` so the SentryTarget receives all entries |
+| SDK initialized twice (double events)              | Set `InitializeSdk = false` in the logging integration when you also call `SentrySdk.Init()` in startup               |
+| Logs not linked to traces                          | Ensure `TracesSampleRate > 0` and the log is emitted inside an active span                                            |
+| Sensitive data appearing in logs                   | Add filtering in `SetBeforeSendLog`; better yet, avoid logging sensitive values at the call site                      |
+| `SetBeforeSendLog` not firing                      | Confirm `EnableLogs = true` — without it, no logs are processed and the hook never runs                               |
+| log4net: SDK not receiving Identity as user.id     | Set `<SendIdentity value="true"/>` in the appender config                                                             |
+| High log volume / rate limits                      | Use `SetBeforeSendLog` to drop `Trace` and `Debug` levels in production                                               |