From 8ad4f890a50fd7c4045a108186a723c034eb1c7a Mon Sep 17 00:00:00 2001 From: Bruno Garcia Date: Mon, 20 May 2019 13:41:30 +0200 Subject: [PATCH 1/5] feat: NLog support --- __tests__/__snapshots__/documentation.js.snap | 1 + .../_documentation/platforms/dotnet/nlog.md | 169 ++++++++++++++++++ 2 files changed, 170 insertions(+) create mode 100644 src/collections/_documentation/platforms/dotnet/nlog.md diff --git a/__tests__/__snapshots__/documentation.js.snap b/__tests__/__snapshots__/documentation.js.snap index 711a27a7b9224..05b204a66b870 100644 --- a/__tests__/__snapshots__/documentation.js.snap +++ b/__tests__/__snapshots__/documentation.js.snap @@ -270,6 +270,7 @@ Array [ "platforms/dotnet/index.html", "platforms/dotnet/log4net/index.html", "platforms/dotnet/microsoft-extensions-logging/index.html", + "platforms/dotnet/nlog/index.html", "platforms/dotnet/serilog/index.html", "platforms/index.html", "platforms/javascript/advance-settings/index.html", diff --git a/src/collections/_documentation/platforms/dotnet/nlog.md b/src/collections/_documentation/platforms/dotnet/nlog.md new file mode 100644 index 0000000000000..fe2b9677e2181 --- /dev/null +++ b/src/collections/_documentation/platforms/dotnet/nlog.md @@ -0,0 +1,169 @@ +--- +title: NLog +sidebar_order: 13 +--- + +Sentry has an integration with `NLog` through the [Sentry.NLog NuGet package](https://www.nuget.org/packages/Sentry.NLog). + +## Installation + +Using package manager: + +```powershell +Install-Package Sentry.NLog -Version {% sdk_version sentry.dotnet.nlog %} +``` + +Or using the .NET Core CLI: + +```sh +dotnet add package Sentry.NLog -v {% sdk_version sentry.dotnet.nlog %} +``` + +This package extends `Sentry` main SDK. That means that besides the logging related features, through this package you'll also get access to all API and features available in the main `Sentry` SDK. + +> NOTE: Messages logged from assemblies with the name starting with `Sentry` will not generate events. + +## Features + +* Store log messages as breadcrumbs +* Send events to sentry + +Two separate settings define the minimum log level to keep the log entry as a `Breadcrumb` and to send an `Event` to Sentry. The events include any stored breadcrumb on that [scope]({% link _documentation/enriching-error-data/scopes.md %}). + +By default, any message with log level `Info` or higher will be kept as a `Breadcrumb`. + +The default value to report a log entry as an event to Sentry is `Error`. + +This means that out of the box, any `Error` call will create an `Event` which will include all log messages of level `Info`, `Warn` and also `Error` and `Critical`. + + +## Configuration + +You can configure the Sentry NLog target via code as follows: + +```csharp +LogManager.Configuration = new LoggingConfiguration(); +LogManager.Configuration + .AddSentry(o => + { + // Optionally specify a separate format for message + o.Layout = "${message}"; + // Optionally specify a separate format for breadcrumbs + o.BreadcrumbLayout = "${logger}: ${message}"; + + // Debug and higher are stored as breadcrumbs (default is Info) + o.MinimumBreadcrumbLevel = LogLevel.Debug; + // Error and higher is sent as event (default is Error) + o.MinimumEventLevel = LogLevel.Error; + + // Send the logger name as a tag + o.AddTag("logger", "${logger}"); + + // All Sentry Options are accessible here. + }); +``` + +It's also possible to initialize the SDK through the NLog integration (as opposed to using `SentrySdk.Init`). +This is useful when the NLog is the only integration being used in your application. To initialize the Sentry SDK through the NLog integration, provide it with the DSN: + +```csharp +LogManager.Configuration = new LoggingConfiguration(); +LogManager.Configuration + .AddSentry(o => + { + // The NLog integration will initialize the SDK if DSN is set: + o.Dsn = new Dsn("___PUBLIC_DSN___")); + }); +``` + +> NOTE: +The SDK only needs to be initialized once. If a `DSN` is made available to this integration, by default it **will** initialize the SDK. If you do not wish to initialize the SDK via this integration, set the `InitializeSdk` flag to **false**. Not providing a DSN or leaving it as `null` instructs the integration not to initialize the SDK and unless another integration initializes it or you call `SentrySdk.Init`, the SDK will stay disabled. + +The SDK can also be configured via `NLog.config` XML file: + +```xml + + + + + + + + + + + + + true + + + + + + + + + + + + +``` + +### Options + +#### MinimumBreadcrumbLevel + +A `LogLevel` which indicates the minimum level a log message has to be included as a breadcrumb. By default this value is `Info`. + +#### MinimumEventLevel + +A `LogLevel` which indicates the minimum level a log message has to be sent to Sentry as an event. By default this value is `Error`. + +#### InitializeSdk + +Whether or not this integration should initialize the SDK. If you intend to call `SentrySdk.Init` yourself you should set this flag to `false`. + +#### IgnoreEventsWithNoException + +To ignore log messages that don't contain an exception. + +#### SendEventPropertiesAsData + +Determines whether event-level properties will be sent to sentry as additional data. Defaults to true. + +#### SendEventPropertiesAsTags + +Determines whether event properties will be sent to sentry as Tags or not. Defaults to false. + +#### IncludeEventDataOnBreadcrumbs + +Determines whether or not to include event-level data as data in breadcrumbs for future errors. Defaults to false. + +#### BreadcrumbLayout + +Custom layout for breadcrumbs. + +#### layout + +Configured layout for the NLog logger. + +#### Tags + +Any additional tags to apply to each logged message. + +### Samples + +* A [simple example](https://github.com/getsentry/sentry-dotnet/tree/master/samples/Sentry.Samples.NLog). From 1166d9bdaae67740c298118c614c17863aa295fd Mon Sep 17 00:00:00 2001 From: Bruno Garcia Date: Mon, 20 May 2019 14:28:23 +0200 Subject: [PATCH 2/5] fix: Casing for option name --- src/collections/_documentation/platforms/dotnet/nlog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/collections/_documentation/platforms/dotnet/nlog.md b/src/collections/_documentation/platforms/dotnet/nlog.md index fe2b9677e2181..56aed2b6d9bc9 100644 --- a/src/collections/_documentation/platforms/dotnet/nlog.md +++ b/src/collections/_documentation/platforms/dotnet/nlog.md @@ -156,7 +156,7 @@ Determines whether or not to include event-level data as data in breadcrumbs for Custom layout for breadcrumbs. -#### layout +#### Layout Configured layout for the NLog logger. From d54995b310b513cd872f2d2a9e61de719facacda Mon Sep 17 00:00:00 2001 From: Bruno Garcia Date: Thu, 23 May 2019 16:20:00 +0200 Subject: [PATCH 3/5] Update src/collections/_documentation/platforms/dotnet/nlog.md Co-Authored-By: Tien "Mimi" Nguyen --- src/collections/_documentation/platforms/dotnet/nlog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/collections/_documentation/platforms/dotnet/nlog.md b/src/collections/_documentation/platforms/dotnet/nlog.md index 56aed2b6d9bc9..f7e09b06661b6 100644 --- a/src/collections/_documentation/platforms/dotnet/nlog.md +++ b/src/collections/_documentation/platforms/dotnet/nlog.md @@ -30,7 +30,7 @@ This package extends `Sentry` main SDK. That means that besides the logging rela Two separate settings define the minimum log level to keep the log entry as a `Breadcrumb` and to send an `Event` to Sentry. The events include any stored breadcrumb on that [scope]({% link _documentation/enriching-error-data/scopes.md %}). -By default, any message with log level `Info` or higher will be kept as a `Breadcrumb`. +By default, Sentry will keep any message with log level `Info` or higher as a `Breadcrumb`. The default value to report a log entry as an event to Sentry is `Error`. From 54710708df5d098476db55449f7e0c782ce19f74 Mon Sep 17 00:00:00 2001 From: Bruno Garcia Date: Thu, 23 May 2019 16:20:11 +0200 Subject: [PATCH 4/5] Update src/collections/_documentation/platforms/dotnet/nlog.md Co-Authored-By: Tien "Mimi" Nguyen --- src/collections/_documentation/platforms/dotnet/nlog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/collections/_documentation/platforms/dotnet/nlog.md b/src/collections/_documentation/platforms/dotnet/nlog.md index f7e09b06661b6..bf94583cb5809 100644 --- a/src/collections/_documentation/platforms/dotnet/nlog.md +++ b/src/collections/_documentation/platforms/dotnet/nlog.md @@ -126,7 +126,7 @@ The SDK can also be configured via `NLog.config` XML file: #### MinimumBreadcrumbLevel -A `LogLevel` which indicates the minimum level a log message has to be included as a breadcrumb. By default this value is `Info`. +A `LogLevel` which indicates the minimum level a log message needs to be, for Sentry to receive it as an event. By default, this value is `Info`. #### MinimumEventLevel From 0447959bc1851fc0f69501a15116ced82ea929b3 Mon Sep 17 00:00:00 2001 From: Bruno Garcia Date: Thu, 23 May 2019 16:38:04 +0200 Subject: [PATCH 5/5] ref: clarify log levels --- .../_documentation/platforms/dotnet/nlog.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/collections/_documentation/platforms/dotnet/nlog.md b/src/collections/_documentation/platforms/dotnet/nlog.md index bf94583cb5809..47bd4d652e0c5 100644 --- a/src/collections/_documentation/platforms/dotnet/nlog.md +++ b/src/collections/_documentation/platforms/dotnet/nlog.md @@ -64,7 +64,7 @@ LogManager.Configuration ``` It's also possible to initialize the SDK through the NLog integration (as opposed to using `SentrySdk.Init`). -This is useful when the NLog is the only integration being used in your application. To initialize the Sentry SDK through the NLog integration, provide it with the DSN: +This is useful when NLog is the only integration being used in your application. To initialize the Sentry SDK through the NLog integration, provide it with the DSN: ```csharp LogManager.Configuration = new LoggingConfiguration(); @@ -79,6 +79,10 @@ LogManager.Configuration > NOTE: The SDK only needs to be initialized once. If a `DSN` is made available to this integration, by default it **will** initialize the SDK. If you do not wish to initialize the SDK via this integration, set the `InitializeSdk` flag to **false**. Not providing a DSN or leaving it as `null` instructs the integration not to initialize the SDK and unless another integration initializes it or you call `SentrySdk.Init`, the SDK will stay disabled. +> Minimum log level +Two log levels are used to configure this integration (see options below). One will configure the lowest level required for a log message to become an event (`MinimumEventLevel`) sent to Sentry. The other options (`MinimumBreadcrumbLevel`) configures the lowest level a message has to be to become a breadcrumb. Breadcrumbs are kept in memory (by default the last 100 records) and are sent with events. For example, by default, if you log 100 entries with `logger.Info` or `logger.Warn`, no event is sent to Sentry. If you then log with `logger.Error`, an event is sent to Sentry which includes those 100 `Info` or `Warn` messages. For this to work the `SentryTarget` needs to receive all log entries in order to decide what to keep as breadcrumb or sent as event. Make sure to set the `NLog` `LogLevel` configuration to a value lower than what you set for the `MinimumBreadcrumbLevel` and `MinimumEventLevel` to make sure `SentryTarget` receives these log messages. + + The SDK can also be configured via `NLog.config` XML file: ```xml @@ -126,7 +130,7 @@ The SDK can also be configured via `NLog.config` XML file: #### MinimumBreadcrumbLevel -A `LogLevel` which indicates the minimum level a log message needs to be, for Sentry to receive it as an event. By default, this value is `Info`. +A `LogLevel` that indicates the minimum level a log message needs to be in order to become a breadcrumb. By default, this value is `Info`. #### MinimumEventLevel @@ -154,7 +158,7 @@ Determines whether or not to include event-level data as data in breadcrumbs for #### BreadcrumbLayout -Custom layout for breadcrumbs. +Custom layout for breadcrumbs. See [NLog layout renderers](https://nlog-project.org/config/?tab=layout-renderers) for more. #### Layout