diff --git a/docs/platforms/dotnet/common/logs/index.mdx b/docs/platforms/dotnet/common/logs/index.mdx new file mode 100644 index 0000000000000..80ab9959c050b --- /dev/null +++ b/docs/platforms/dotnet/common/logs/index.mdx @@ -0,0 +1,39 @@ +--- +title: Set Up Logs +sidebar_title: Logs +description: "Structured logs allow you to send, view and query logs sent from your applications within Sentry." +sidebar_order: 5600 +notSupported: + - dotnet.google-cloud-functions + - dotnet.log4net + - dotnet.nlog + - dotnet.serilog + - dotnet.xamarin +--- + + + +With Sentry Structured Logs, you can send text based log information from your applications to Sentry. Once in Sentry, these logs can be viewed alongside relevant errors, searched by text-string, or searched using their individual attributes. + +## Requirements + + + +## Setup + + + +## Usage + + + +## Integrations + + + +## Options + + + + + diff --git a/docs/product/explore/logs/getting-started/index.mdx b/docs/product/explore/logs/getting-started/index.mdx index 90689a5d05716..71e39b43bf7bd 100644 --- a/docs/product/explore/logs/getting-started/index.mdx +++ b/docs/product/explore/logs/getting-started/index.mdx @@ -246,6 +246,14 @@ To set up Sentry Logs, use the links below for supported SDKs. After it's been s - +### .NET + +- + ## Upcoming SDKs We're actively working on adding Log functionality to additional SDKs. Check out these GitHub issues for the latest updates: @@ -260,11 +268,6 @@ We're actively working on adding Log functionality to additional SDKs. Check out label="Elixir" url="https://github.com/getsentry/sentry-elixir/issues/886" /> -- - ](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger-1) API. + +#### Experimental.SetBeforeSendLog(Func) + +To filter logs, or update them before they are sent to Sentry, you can use the `Experimental.SetBeforeSendLog()` option. + +```csharp +options => +{ + options.Dsn = "___PUBLIC_DSN___"; + options.Experimental.EnableLogs = true; + // a callback that is invoked before sending a log to Sentry + options.Experimental.SetBeforeSendLog(static log => + { + // filter out all info logs + if (log.Level is SentryLogLevel.Info) + { + return null; + } + + // filter out logs based on some attribute they have + if (log.TryGetAttribute("suppress", out var attribute) && attribute is true) + { + return null; + } + + // set a custom attribute for all other logs sent to Sentry + log.SetAttribute("my.attribute", "value"); + + return log; + }); +}); +``` + +The callback function set via `Experimental.SetBeforeSendLog()` receives a log object, and should return the log object if you want it to be sent to Sentry, or `null` if you want to discard it. + +The log object of type `SentryLog` has the following members: +- `Timestamp` Property: (`DateTimeOffset`) The timestamp of the log. +- `TraceId` Property: (`SentryId`) The trace id of the log. +- `Level` Property: (`SentryLogLevel`) The severity level of the log. Either `Trace`, `Debug`, `Info`, `Warning`, `Error`, or `Fatal`. +- `Message` Property: (`string`) The formatted log message. +- `Template` Property: (`string?`) The parameterized template string. +- `Parameters` Property: (`ImmutableArray>`) The parameters to the template string. +- `ParentSpanId` Property: (`SpanId?`) The span id of the span that was active when the log was collected. +- `TryGetAttribute(string key, out object value)` Method: Gets the attribute value associated with the specified key. Returns `true` if the log contains an attribute with the specified key and it's value is not `null`, otherwise `false`. +- `SetAttribute(string key, object value)` Method: Set a key-value pair of data attached to the log. Supported types are `string`, `bool`, integers up to a size of 64-bit signed, and floating-point numbers up to a size of 64-bit. diff --git a/platform-includes/logs/requirements/dotnet.mdx b/platform-includes/logs/requirements/dotnet.mdx new file mode 100644 index 0000000000000..0df8ad43b5734 --- /dev/null +++ b/platform-includes/logs/requirements/dotnet.mdx @@ -0,0 +1 @@ +Logs for .NET are supported in Sentry .NET SDK version `5.14.0` and above. diff --git a/platform-includes/logs/setup/dotnet.mdx b/platform-includes/logs/setup/dotnet.mdx new file mode 100644 index 0000000000000..f4e152eef9608 --- /dev/null +++ b/platform-includes/logs/setup/dotnet.mdx @@ -0,0 +1,53 @@ +To enable logging, you need to initialize the SDK with the `Experimental.EnableLogs` option set to `true`. + + + +```csharp +SentrySdk.Init(options => +{ + options.Dsn = "___PUBLIC_DSN___"; + // Enable logs to be sent to Sentry + options.Experimental.EnableLogs = true; +}); +``` + + + + + +```csharp {tabTitle:Builder} +.UseSentry(options => +{ + options.Dsn = "___PUBLIC_DSN___"; + // Enable logs to be sent to Sentry + options.Experimental.EnableLogs = true; +}); +``` + + + + + +```csharp {tabTitle:Factory} +.AddSentry(options => +{ + options.Dsn = "___PUBLIC_DSN___"; + // Enable logs to be sent to Sentry + options.Experimental.EnableLogs = true; +}); +``` + + + + + +```json {tabTitle:Configuration} {filename:appsettings.json} + "Sentry": { + "Dsn": "___PUBLIC_DSN___", + "Experimental": { + "EnableLogs": true + } + }, +``` + + diff --git a/platform-includes/logs/usage/dotnet.mdx b/platform-includes/logs/usage/dotnet.mdx new file mode 100644 index 0000000000000..a766e3acabdb6 --- /dev/null +++ b/platform-includes/logs/usage/dotnet.mdx @@ -0,0 +1,63 @@ +Once the feature is enabled on the SDK and the SDK is initialized, you can send logs using the `SentrySdk.Experimental.Logger` APIs. + +The `SentrySdk.Experimental.Logger` instance exposes six methods that you can use to log messages at different log levels: `Trace`, `Debug`, `Info`, `Warning`, `Error`, and `Fatal`. + +These properties will be sent to Sentry, and can be searched from within the Logs UI, and even added to the Logs views as a dedicated column. + +```csharp +SentrySdk.Experimental.Logger.LogInfo("A simple log message"); +SentrySdk.Experimental.Logger.LogError("A {0} log message", ["formatted"]); +``` + + +During the experimental phase of the feature, we will provide more method overloads for convenient invocation in common scenarios. +Additionally, we may provide method overloads that are not based on _composite format strings_, but on _interpolated strings_. + + + + +Additionally, when enabled and initialized, the SDK registers a [ILoggerProvider](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.iloggerprovider) +that allows sending logs to Sentry via [ILogger](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger-1) instances resolved through _.NET dependency injection_. + +```csharp +public sealed class MyService(ILogger logger) +{ + public async Task InvokeAsync(HttpContext context) + { + logger.LogInformation("A simple log message"); + await Task.Yield(); + logger.LogError("A {Parameter} log message", "formatted"); + await Task.Delay(TimeSpan.FromSeconds(1)); + logger.LogWarning(new EventId(1, nameof(InvokeAsync)), "Message with EventId"); + } +} +``` + +The `ILogger`'s _CategoryName_, as well as the `EventId` (if provided), are attached as attributes to the logs. + +For more information, see article on [Logging in C# and .NET](https://learn.microsoft.com//dotnet/core/extensions/logging). +Sentry Structured Logs also work with [High-performance logging in .NET](https://learn.microsoft.com/dotnet/core/extensions/high-performance-logging) and [Compile-time logging source generation](https://learn.microsoft.com/dotnet/core/extensions/logger-message-generator) alike. + + + +The SDK automatically provides a set of default attributes attached to your logs. +Additionally, you can attach custom attributes via a delegate. + +```csharp +SentrySdk.Experimental.Logger.LogWarning("A log message with additional attributes.", [], static log => +{ + log.SetAttribute("my.attribute", "value"); +}); +``` + + +Please note that we will revise the API shape to set custom attributes during the experimental phase of the feature. + + +Supported attribute types are: +- Textual: `string` and `char` +- Logical: `bool` +- Integral: `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long` and `nint` +- Floating-point: `float` and `double` + +Unsupported numeric types such as `ulong`, `nuint`, `decimal`, as well as all other types including `object`, are treated as `string` via `ToString`.