Skip to content

Commit 482fa37

Browse files
Flash0verFlash0ver
authored
docs(dotnet/logs): add Logs for the .NET SDK (#14583)
1 parent 6134a2c commit 482fa37

File tree

8 files changed

+255
-6
lines changed

8 files changed

+255
-6
lines changed

‎docs/platforms/dotnet/common/logs/index.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Set Up Logs
3+
sidebar_title: Logs
4+
description: "Structured logs allow you to send, view and query logs sent from your applications within Sentry."
5+
sidebar_order: 5600
6+
notSupported:
7+
- dotnet.google-cloud-functions
8+
- dotnet.log4net
9+
- dotnet.nlog
10+
- dotnet.serilog
11+
- dotnet.xamarin
12+
---
13+
14+
<Include name="feature-stage-beta-logs.mdx" />
15+
16+
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.
17+
18+
## Requirements
19+
20+
<PlatformContent includePath="logs/requirements" />
21+
22+
## Setup
23+
24+
<PlatformContent includePath="logs/setup" />
25+
26+
## Usage
27+
28+
<PlatformContent includePath="logs/usage" />
29+
30+
## Integrations
31+
32+
<PlatformContent includePath="logs/integrations" />
33+
34+
## Options
35+
36+
<PlatformContent includePath="logs/options" />

‎docs/platforms/dotnet/guides/extensions-logging/index.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ Sentry has an integration with `Microsoft.Extensions.Logging` through the [Sentr
99
## Overview of the features
1010

1111
- Store log messages as breadcrumbs
12-
- Send events to sentry
12+
- Send events to Sentry
13+
- Send structured logs to Sentry
1314

1415
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](enriching-events/scopes/).
1516

@@ -19,6 +20,8 @@ The default value to report a log entry as an event to Sentry is `Error`.
1920

2021
This means that out of the box, any `LogError` call will create an `Event` which will include all log messages of level `Information`, `Warning` and also `Error` and `Critical`.
2122

23+
Additionally, when enabled, log messages are sent to Sentry as [Structured Logs](logs/).
24+
2225
## Install
2326

2427
Add the Sentry dependency:

‎docs/product/explore/logs/getting-started/index.mdx‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,29 @@ To set up Sentry Logs, use the links below for supported SDKs. After it's been s
246246

247247
- <LinkWithPlatformIcon platform="rust" label="Rust" url="/platforms/rust/logs/" />
248248

249+
### .NET
250+
251+
- <LinkWithPlatformIcon
252+
platform="dotnet"
253+
label=".NET"
254+
url="/platforms/dotnet/logs/"
255+
/>
256+
- <LinkWithPlatformIcon
257+
platform="dotnet.aspnetcore"
258+
label="ASP.NET Core"
259+
url="/platforms/dotnet/guides/aspnetcore/logs/"
260+
/>
261+
- <LinkWithPlatformIcon
262+
platform="dotnet.maui"
263+
label="MAUI"
264+
url="/platforms/dotnet/guides/maui/logs/"
265+
/>
266+
- <LinkWithPlatformIcon
267+
platform="dotnet.extensions-logging"
268+
label="Microsoft.Extensions.Logging"
269+
url="/platforms/dotnet/guides/extensions-logging/logs/"
270+
/>
271+
249272
## Upcoming SDKs
250273

251274
We're actively working on adding Log functionality to additional SDKs. Check out these GitHub issues for the latest updates:
@@ -260,11 +283,6 @@ We're actively working on adding Log functionality to additional SDKs. Check out
260283
label="Elixir"
261284
url="https://github.com/getsentry/sentry-elixir/issues/886"
262285
/>
263-
- <LinkWithPlatformIcon
264-
platform="dotnet"
265-
label=".NET"
266-
url="https://github.com/getsentry/sentry-dotnet/issues/4132"
267-
/>
268286
- <LinkWithPlatformIcon
269287
platform="php.symfony"
270288
label="Symfony"

‎platform-includes/logs/integrations/dotnet.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Available integrations:
2+
- [ASP.NET Core](/platforms/dotnet/guides/aspnetcore/logs/)
3+
- [.NET Multi-platform App UI (.NET MAUI)](/platforms/dotnet/guides/maui/logs/)
4+
- [Microsoft.Extensions.Logging](/platforms/dotnet/guides/extensions-logging/logs/)
5+
6+
If there's an integration you would like to see, open a [new issue on GitHub](https://github.com/getsentry/sentry-dotnet/issues/new/choose).

‎platform-includes/logs/options/dotnet.mdx‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
#### Experimental.EnableLogs
2+
3+
Set to `true` in order to enable the `SentrySdk.Experimental.Logger` APIs, as well as logging integrations via the `ILogger<TCategoryName>` API.
4+
5+
#### Experimental.SetBeforeSendLog
6+
7+
To filter logs, or update them before they are sent to Sentry, you can use the `Experimental.SetBeforeSendLog(Func<SentryLog, SentryLog?>)` option.
8+
9+
```csharp
10+
options =>
11+
{
12+
options.Dsn = "___PUBLIC_DSN___";
13+
options.Experimental.EnableLogs = true;
14+
// a callback that is invoked before sending a log to Sentry
15+
options.Experimental.SetBeforeSendLog(static log =>
16+
{
17+
// filter out all info logs
18+
if (log.Level is SentryLogLevel.Info)
19+
{
20+
return null;
21+
}
22+
23+
// filter out logs based on some attribute they have
24+
if (log.TryGetAttribute("suppress", out var attribute) && attribute is true)
25+
{
26+
return null;
27+
}
28+
29+
// set a custom attribute for all other logs sent to Sentry
30+
log.SetAttribute("my.attribute", "value");
31+
32+
return log;
33+
});
34+
});
35+
```
36+
37+
The callback function set via `Experimental.SetBeforeSendLog(Func<SentryLog, SentryLog?>)` 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.
38+
39+
The log object of type `SentryLog` has the following members:
40+
- `Timestamp` Property: (`DateTimeOffset`) The timestamp of the log.
41+
- `TraceId` Property: (`SentryId`) The trace id of the log.
42+
- `Level` Property: (`SentryLogLevel`) The severity level of the log. Either `Trace`, `Debug`, `Info`, `Warning`, `Error`, or `Fatal`.
43+
- `Message` Property: (`string`) The formatted log message.
44+
- `Template` Property: (`string?`) The parameterized template string.
45+
- `Parameters` Property: (`ImmutableArray<KeyValuePair<string, object>>`) The parameters to the template string.
46+
- `ParentSpanId` Property: (`SpanId?`) The span id of the span that was active when the log was collected.
47+
- `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`.
48+
- `SetAttribute(string key, object value)` Method: Sets 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.

‎platform-includes/logs/requirements/dotnet.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Logs for .NET are supported in Sentry .NET SDK version `5.14.0` and above.

‎platform-includes/logs/setup/dotnet.mdx‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
To enable logging, you need to initialize the SDK with the `Experimental.EnableLogs` option set to `true`.
2+
3+
<PlatformSection notSupported={["dotnet.aspnetcore", "dotnet.aws-lambda", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.extensions-logging", "dotnet.maui"]}>
4+
5+
```csharp
6+
SentrySdk.Init(options =>
7+
{
8+
options.Dsn = "___PUBLIC_DSN___";
9+
// Enable logs to be sent to Sentry
10+
options.Experimental.EnableLogs = true;
11+
});
12+
```
13+
14+
</PlatformSection>
15+
16+
<PlatformSection supported={["dotnet.aspnetcore", "dotnet.aws-lambda", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.maui"]}>
17+
18+
```csharp {tabTitle:Builder}
19+
.UseSentry(options =>
20+
{
21+
options.Dsn = "___PUBLIC_DSN___";
22+
// Enable logs to be sent to Sentry
23+
options.Experimental.EnableLogs = true;
24+
});
25+
```
26+
27+
</PlatformSection>
28+
29+
<PlatformSection supported={["dotnet.extensions-logging"]}>
30+
31+
```csharp {tabTitle:Factory}
32+
.AddSentry(options =>
33+
{
34+
options.Dsn = "___PUBLIC_DSN___";
35+
// Enable logs to be sent to Sentry
36+
options.Experimental.EnableLogs = true;
37+
});
38+
```
39+
40+
</PlatformSection>
41+
42+
<PlatformSection supported={["dotnet.aspnetcore", "dotnet.extensions-logging"]}>
43+
44+
```json {tabTitle:Configuration} {filename:appsettings.json}
45+
{
46+
"Sentry": {
47+
"Dsn": "___PUBLIC_DSN___",
48+
"Experimental": {
49+
"EnableLogs": true
50+
}
51+
}
52+
}
53+
```
54+
55+
</PlatformSection>

‎platform-includes/logs/usage/dotnet.mdx‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
<PlatformSection notSupported={["dotnet.aspnetcore", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.extensions-logging", "dotnet.maui"]}>
2+
3+
Once the feature is enabled on the SDK and the SDK is initialized, you can send logs using the `SentrySdk.Experimental.Logger` APIs.
4+
5+
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`.
6+
7+
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.
8+
9+
```csharp
10+
SentrySdk.Experimental.Logger.LogInfo("A simple log message");
11+
SentrySdk.Experimental.Logger.LogError("A {0} log message", ["formatted"]);
12+
```
13+
14+
<Alert title="Note">
15+
During the experimental phase of the feature, we will provide more method overloads for convenient invocation in common scenarios.
16+
Additionally, we may provide method overloads that are not based on _composite format strings_, but on _interpolated strings_.
17+
</Alert>
18+
19+
</PlatformSection>
20+
21+
<PlatformSection supported={["dotnet.aspnetcore", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.extensions-logging", "dotnet.maui"]}>
22+
23+
Once the feature is enabled on the SDK and the SDK is initialized, you can send logs using instances of the [ILogger](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger-1) interface,
24+
resolved through _.NET dependency injection_.
25+
26+
The `LoggerExtensions` extension methods expose various overloads that you can use to log messages at six different log levels automatically mapped to Sentry's severity:
27+
28+
| Microsoft.Extensions.Logging.LogLevel | Sentry.SentryLogLevel | Sentry Logs UI Severity |
29+
| --- | --- | --- |
30+
| Trace | Trace | TRACE |
31+
| Debug | Debug | DEBUG |
32+
| Information | Info | INFO |
33+
| Warning | Warning | WARN |
34+
| Error | Error | ERROR |
35+
| Critical | Fatal | FATAL |
36+
37+
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.
38+
39+
```csharp
40+
public sealed class MyService(ILogger<MyService> logger)
41+
{
42+
public void Invoke()
43+
{
44+
logger.LogInformation("A simple log message");
45+
logger.LogError("A {Parameter} log message", "formatted");
46+
logger.LogWarning(new EventId(1, nameof(Invoke)), "Message with EventId");
47+
}
48+
}
49+
```
50+
51+
The `ILogger`'s _CategoryName_, as well as the `EventId` (if provided), are attached as attributes to the logs.
52+
53+
For more information, see the article on [Logging in C# and .NET](https://learn.microsoft.com//dotnet/core/extensions/logging).
54+
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.
55+
56+
</PlatformSection>
57+
58+
<PlatformSection notSupported={["dotnet.aspnetcore", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.extensions-logging", "dotnet.maui"]}>
59+
60+
The SDK automatically provides a set of default attributes attached to your logs.
61+
Additionally, you can attach custom attributes via a delegate.
62+
63+
```csharp
64+
SentrySdk.Experimental.Logger.LogWarning("A log message with additional attributes.", [], static log =>
65+
{
66+
log.SetAttribute("my.attribute", "value");
67+
});
68+
```
69+
70+
<Alert title="Note">
71+
Please note that we will revise the API shape to set custom attributes during the experimental phase of the feature.
72+
</Alert>
73+
74+
Supported attribute types are:
75+
- Textual: `string` and `char`
76+
- Logical: `bool`
77+
- Integral: `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long` and `nint`
78+
- Floating-point: `float` and `double`
79+
80+
Unsupported numeric types such as `ulong`, `nuint`, `decimal`, as well as all other types including `object`, are treated as `string` via `ToString()`.
81+
82+
</PlatformSection>

0 commit comments

Comments
 (0)