feat(nlog)!: the Sentry target no longer initializes the SDK

samples/Sentry.Samples.NLog/NLog.config

@@ -10,11 +10,8 @@
   <targets>
     <target name="logconsole" xsi:type="ColoredConsole" />
 
-    <!-- You can also add a `dsn` property to the following target (with the DSN of your Sentry project):
-    See Program.cs for the DSN used in the code-only example-->
-
+    <!-- This only configures the Sentry target. Sentry itself is initialised in Program.cs -->
     <target xsi:type="Sentry" name="sentry"
-            environment="Development"
             includeEventProperties="True"
             layout="${message}"
             breadcrumbLayout="${message}"
@@ -24,13 +21,6 @@
             includeEventPropertiesAsTags="True"
             minimumEventLevel="Error">
 
-      <!-- Advanced options can be configured here-->
-      <options
-          attachStacktrace="true"
-          sendDefaultPii="true"
-          shutdownTimeoutSeconds="5"
-        />
-
       <!--Optionally add any desired additional Tags that will be sent with every message -->
       <tag name="exception" layout="${exception:format=shorttype}" includeEmptyValue="false" />
 

samples/Sentry.Samples.NLog/Program.cs

@@ -12,6 +12,18 @@ public static class Program
 
     private static void Main()
     {
+        // Initialise the Sentry SDK
+        using var _ = SentrySdk.Init(options =>
+        {
+#if !SENTRY_DSN_DEFINED_IN_ENV
+            // A DSN is required. You can set here in code, or you can set it in the SENTRY_DSN environment variable.
+            // See https://docs.sentry.io/product/sentry-basics/dsn-explainer/
+            options.Dsn = SamplesShared.Dsn;
+#endif
+            options.AttachStacktrace = true;
+            options.SendDefaultPii = true; // Send Personal Identifiable information like the username of the user logged in to the device
+        });
+
         try
         {
             // You can configure your logger using a configuration file:
@@ -97,28 +109,18 @@ private static void UsingNLogConfigFile()
 
     private static void UsingCodeConfiguration()
     {
-        // Other overloads exist, for example, configure the SDK with only the DSN or no parameters at all.
+        // Configure NLog to send logs to Sentry
         var config = LogManager.Configuration = new LoggingConfiguration();
         _ = config
             .AddSentry(options =>
             {
-#if !SENTRY_DSN_DEFINED_IN_ENV
-                // A DSN is required. You can set here in code, in the SENTRY_DSN environment variable or in the
-                // NLog.config file.
-                // See https://docs.sentry.io/product/sentry-basics/dsn-explainer/
-                options.Dsn = SamplesShared.Dsn;
-#endif
                 options.Layout = "${message}";
                 options.BreadcrumbLayout = "${logger}: ${message}"; // Optionally specify a separate format for breadcrumbs
 
                 options.MinimumBreadcrumbLevel = LogLevel.Debug; // Debug and higher are stored as breadcrumbs (default is Info)
-                options.MinimumEventLevel = LogLevel.Error; // Error and higher is sent as event (default is Error)
-
-                options.AttachStacktrace = true;
-                options.SendDefaultPii = true; // Send Personal Identifiable information like the username of the user logged in to the device
+                options.MinimumEventLevel = LogLevel.Error; // Error and higher are sent as events (default is Error)
 
                 options.IncludeEventDataOnBreadcrumbs = true; // Optionally include event properties with breadcrumbs
-                options.ShutdownTimeoutSeconds = 5;
 
                 //Optionally specify user properties via NLog (here using MappedDiagnosticsLogicalContext as an example)
                 options.User = new SentryNLogUser
@@ -134,8 +136,6 @@ private static void UsingCodeConfiguration()
                 };
 
                 options.AddTag("logger", "${logger}");  // Send the logger name as a tag
-
-                // Other configuration
             });
 
         config.AddTarget(new DebuggerTarget("debugger"));

samples/Sentry.Samples.NLog/README.md

@@ -2,20 +2,17 @@
 
 This is a simple console application that demonstrates how you can add Sentry to your application using NLog.
 
-This project attempts to sample the integration by using code only and also via the configuration file.
-In both cases **you need to add your own DSN** so you can see the events sent in your Sentry project.
+This project demonstrates configuring Sentry and NLog via code and configuration.
+The Sentry target configures NLog to send logs to Sentry. The Sentry SDK itself is initialised via the call to `SentrySdk.Init`
+in `Program.cs`, so **you need to add your own DSN** there to see the events sent in your Sentry project.
 
 You can get your [Sentry DSN at sentry.io](https://sentry.io).
-Make sure to add it to both `NLog.config` and `Program.cs` in this directory.
 
 ## Configuration of NLog.config
 The following options are available for the NLog Sentry Target:
 
 ```xml
 <target xsi:type="Sentry" name="sentry"
-    dsn="https://123@sentry.io/456"
-    environment="${environment:cached=true:ASPNETCORE_ENVIRONMENT}"
-    release="${assembly-version:cached=true:type=File}"
     layout="${message}"
     includeEventProperties="True"
     includeMdlc="False"
@@ -25,17 +22,9 @@ The following options are available for the NLog Sentry Target:
     ignoreEventsWithNoException="False"
     includeEventDataOnBreadcrumbs="False"
     includeEventPropertiesAsTags="True"
-    initializeSdk="True"
-    flushTimeoutSeconds="15"
     >
         <tag name="exception" layout="${exception:format=shorttype}" includeEmptyValue="false" /><!-- Repeatable SentryEvent Tags -->
         <contextproperty name="threadid" layout="${threadid}" includeEmptyValue="true" />        <!-- Repeatable SentryEvent Data -->
-        <!-- Advanced options can be configured here-->
-        <options
-            sendDefaultPii="False"
-            isEnvironmentUser="True"
-            attachStacktrace="False"
-        />
         <!-- Optionally specify user properties via NLog (here using MappedDiagnosticsLogicalContext as an example) -->
         <user
             id="${mdlc:item=id}" 
@@ -48,10 +37,6 @@ The following options are available for the NLog Sentry Target:
 </target>
 ```
 
-* **dsn** - Sentry Data Source Name Address. See also https://sentry.io
-* **initializeSdk** -  Whether the NLog target should initialize the Sentry SDK (Using Dsn). Default: _True_
-* **environment** - Application Environment sent to Sentry
-* **release** - Application Release Version sent to Sentry
 * **layout** - NLog Layout for rendering SentryEvent message. Default: _${message}_
 * **includeEventProperties** - Include LogEvent properties as Data on SentryEvent. Default: _True_
 * **includeEventPropertiesAsTags** - Include LogEvent properties as extra Tags on SentryEvent. Default: _False_
@@ -61,17 +46,12 @@ The following options are available for the NLog Sentry Target:
 * **minimumEventLevel** - Send NLog LogEvents as SentryEvent when matching severity (or worse). Default: _Error_
 * **minimumBreadcrumbLevel** - Send NLog LogEvents as Breadcrumbs when matching severity (or worse). Default: _Info_
 * **ignoreEventsWithNoException** - Ignore NLog LogEvents without an exception. Default: _False_
-* **flushTimeoutSeconds** - Flush timeout in seconds before aborting flush to Sentry. Default: _15_
 * **user**
    * **id**
    * **username**
    * **email**
    * **ipAddress**
    * **other** - Any arbitrary key-value pairs to be included as properties for a user on every event.
-* **options**
-   * **sendDefaultPii** - Whether to include default Personal Identifiable information (UserName / IP-Address). Default: _False_
-   * **isEnvironmentUser** - Lookup Environment.User if having enabled **sendDefaultPii**. Default: _True_
-   * **attachStacktrace** - Whether to send the stack trace of a event captured without an exception. Default: _False_
 
 There is filtering logic in the Sentry Target that is usually handled by NLog Logging Rules and Filters.
 Mostly because the same Sentry Target is writing both breadcrumbs and actual SentryEvents.

src/Sentry.NLog/ConfigurationExtensions.cs

@@ -12,66 +12,58 @@ public static class ConfigurationExtensions
     // Internal for testability
     internal const string DefaultTargetName = "sentry";
 
+    internal const string ObsoleteDsnOverload =
+        "The Sentry target no longer initializes the SDK, so a DSN can no longer be supplied to it. " +
+        "Initialize Sentry with SentrySdk.Init (or UseSentry via one of the integrations), and remove 'dsn', " +
+        "'initializeSdk' and any other core SDK settings from the target configuration.";
+
     /// <summary>
-    /// Adds a target for Sentry to the NLog configuration.
+    /// Not supported. The Sentry target no longer initializes the SDK.
     /// </summary>
-    /// <remarks>
-    /// If DSN is not set, the SDK will look for an environment variable called SENTRY_DSN. If nothing is
-    /// found, SDK is disabled.
-    /// </remarks>
     /// <param name="configuration">The NLog configuration.</param>
+    /// <param name="dsn">No longer supported.</param>
     /// <param name="optionsConfig">An optional action for configuring the Sentry target options.</param>
-    /// <returns>The configuration.</returns>
+    /// <returns>Never returns.</returns>
+    /// <exception cref="NotSupportedException">Always.</exception>
+    [Obsolete(ObsoleteDsnOverload, error: true)]
     public static LoggingConfiguration AddSentry(
         this LoggingConfiguration configuration,
+        string? dsn,
         Action<SentryNLogOptions>? optionsConfig = null)
-    {
-        // Not to throw on code that ignores nullability warnings.
-        if (configuration.IsNull())
-        {
-            return configuration!;
-        }
-
-        return configuration.AddSentry(null, DefaultTargetName, optionsConfig);
-    }
+        => throw new NotSupportedException(ObsoleteDsnOverload);
 
     /// <summary>
-    /// Adds a target for Sentry to the NLog configuration.
+    /// Not supported. The Sentry target no longer initializes the SDK.
     /// </summary>
     /// <param name="configuration">The NLog configuration.</param>
-    /// <param name="dsn">
-    /// The sentry DSN. If DSN is not set, the SDK will look for an environment variable called SENTRY_DSN.
-    /// If nothing is found, SDK is disabled.
-    /// </param>
+    /// <param name="dsn">No longer supported.</param>
+    /// <param name="targetName">The name to give the new target.</param>
     /// <param name="optionsConfig">An optional action for configuring the Sentry target options.</param>
-    /// <returns>The configuration.</returns>
+    /// <returns>Never returns.</returns>
+    /// <exception cref="NotSupportedException">Always.</exception>
+    [Obsolete(ObsoleteDsnOverload, error: true)]
     public static LoggingConfiguration AddSentry(
         this LoggingConfiguration configuration,
         string? dsn,
+        string targetName,
         Action<SentryNLogOptions>? optionsConfig = null)
-    {
-        // Not to throw on code that ignores nullability warnings.
-        if (configuration.IsNull())
-        {
-            return configuration!;
-        }
-
-        return configuration.AddSentry(dsn, DefaultTargetName, optionsConfig);
-    }
+        => throw new NotSupportedException(ObsoleteDsnOverload);
 
     /// <summary>
     /// Adds a target for Sentry to the NLog configuration.
     /// </summary>
+    /// <remarks>
+    /// This doesn't initialise Sentry. Initialise Sentry separately, using <c>SentrySdk.Init</c> or another Sentry
+    /// integration (such as ASP.NET Core or MAUI).
+    /// </remarks>
     /// <param name="configuration">The NLog configuration.</param>
-    /// <param name="dsn">The sentry DSN.</param>
-    /// <param name="targetName">The name to give the new target.</param>
     /// <param name="optionsConfig">An optional action for configuring the Sentry target options.</param>
+    /// <param name="targetName">The name to give the new target.</param>
     /// <returns>The configuration.</returns>
     public static LoggingConfiguration AddSentry(
         this LoggingConfiguration configuration,
-        string? dsn,
-        string targetName,
-        Action<SentryNLogOptions>? optionsConfig = null)
+        Action<SentryNLogOptions>? optionsConfig = null,
+        string targetName = DefaultTargetName)
     {
         // Not to throw on code that ignores nullability warnings.
         if (configuration.IsNull())
@@ -95,11 +87,6 @@ public static LoggingConfiguration AddSentry(
             Layout = "${message}",
         };
 
-        if (dsn != null && string.IsNullOrWhiteSpace(options.Dsn))
-        {
-            options.Dsn = dsn;
-        }
-
         configuration.AddTarget(targetName, target);
 
         configuration.AddRuleForAllLevels(targetName);

src/Sentry.NLog/Sentry.NLog.csproj

@@ -28,6 +28,7 @@
     <Using Include="Sentry.NLog" />
     <Using Include="Sentry.Extensibility" />
     <Using Include="Sentry.Infrastructure" />
+    <Using Include="Sentry.Internal" />
     <Using Include="Sentry.Reflection" />
   </ItemGroup>