Skip to content

Commit 44aa38e

Browse files
Flash0verFlash0ver
authored
docs(dotnet/logs): add Serilog integration and update Logger APIs (#14693)
1 parent d33a360 commit 44aa38e

8 files changed

Lines changed: 86 additions & 23 deletions

File tree

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ notSupported:
77
- dotnet.google-cloud-functions
88
- dotnet.log4net
99
- dotnet.nlog
10-
- dotnet.serilog
1110
- dotnet.xamarin
1211
---
1312

‎docs/platforms/dotnet/guides/serilog/index.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ Sentry provides an integration with `Serilog` through the [Sentry.Serilog NuGet
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: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -281,6 +281,11 @@ To set up Sentry Logs, use the links below for supported SDKs. After it's been s
281281
label="Microsoft.Extensions.Logging"
282282
url="/platforms/dotnet/guides/extensions-logging/logs/"
283283
/>
284+
- <LinkWithPlatformIcon
285+
platform="dotnet.serilog"
286+
label="Serilog"
287+
url="/platforms/dotnet/guides/serilog/logs/"
288+
/>
284289

285290
### Native
286291

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,6 @@ Available integrations:
22
- [ASP.NET Core](/platforms/dotnet/guides/aspnetcore/logs/)
33
- [.NET Multi-platform App UI (.NET MAUI)](/platforms/dotnet/guides/maui/logs/)
44
- [Microsoft.Extensions.Logging](/platforms/dotnet/guides/extensions-logging/logs/)
5+
- [Serilog](/platforms/dotnet/guides/serilog/logs/)
56

67
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: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
11
#### Experimental.EnableLogs
22

3-
Set to `true` in order to enable the `SentrySdk.Experimental.Logger` APIs, as well as logging integrations via the `ILogger<TCategoryName>` API.
3+
<PlatformSection notSupported={["dotnet.aspnetcore", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.extensions-logging", "dotnet.maui", "dotnet.serilog"]}>
4+
Set to `true` in order to enable the `SentrySdk.Logger` APIs.
5+
</PlatformSection>
6+
7+
<PlatformSection supported={["dotnet.aspnetcore", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.extensions-logging", "dotnet.maui"]}>
8+
Set to `true` in order to enable the logging integration via the `ILogger<TCategoryName>` API.
9+
</PlatformSection>
10+
11+
<PlatformSection supported={["dotnet.serilog"]}>
12+
Set to `true` in order to enable the logging integration via the `Log`/`Logger` APIs.
13+
</PlatformSection>
414

515
#### Experimental.SetBeforeSendLog
616

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

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,7 @@
1-
Logs for .NET are supported in Sentry .NET SDK version `5.14.0` and above.
1+
<PlatformSection notSupported={["dotnet.serilog"]}>
2+
Logs for <PlatformOrGuideName/> are supported in Sentry <PlatformOrGuideName/> SDK version `5.14.0` and above.
3+
</PlatformSection>
4+
5+
<PlatformSection supported={["dotnet.serilog"]}>
6+
Logs for <PlatformOrGuideName/> are supported in Sentry <PlatformOrGuideName/> SDK version `5.16.0` and above.
7+
</PlatformSection>

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

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
To enable logging, you need to initialize the SDK with the `Experimental.EnableLogs` option set to `true`.
22

3-
<PlatformSection notSupported={["dotnet.aspnetcore", "dotnet.aws-lambda", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.extensions-logging", "dotnet.maui"]}>
3+
<PlatformSection notSupported={["dotnet.aspnetcore", "dotnet.aws-lambda", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.extensions-logging", "dotnet.maui", "dotnet.serilog"]}>
44

55
```csharp
66
SentrySdk.Init(options =>
@@ -53,3 +53,16 @@ SentrySdk.Init(options =>
5353
```
5454

5555
</PlatformSection>
56+
57+
<PlatformSection supported={["dotnet.serilog"]}>
58+
59+
```csharp
60+
.WriteTo.Sentry(options =>
61+
{
62+
options.Dsn = "___PUBLIC_DSN___";
63+
// Enable logs to be sent to Sentry
64+
options.Experimental.EnableLogs = true;
65+
});
66+
```
67+
68+
</PlatformSection>

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

Lines changed: 44 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
<PlatformSection notSupported={["dotnet.aspnetcore", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.extensions-logging", "dotnet.maui"]}>
1+
<PlatformSection notSupported={["dotnet.aspnetcore", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.extensions-logging", "dotnet.maui", "dotnet.serilog"]}>
22

3-
Once the feature is enabled on the SDK and the SDK is initialized, you can send logs using the `SentrySdk.Experimental.Logger` APIs.
3+
Once the feature is enabled on the SDK and the SDK is initialized, you can send logs using the `SentrySdk.Logger` APIs.
44

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`.
5+
The `SentrySdk.Logger` instance exposes six methods that you can use to log messages at different log levels: `Trace`, `Debug`, `Info`, `Warning`, `Error`, and `Fatal`.
66

77
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.
88

99
```csharp
10-
SentrySdk.Experimental.Logger.LogInfo("A simple log message");
11-
SentrySdk.Experimental.Logger.LogError("A {0} log message", ["formatted"]);
10+
SentrySdk.Logger.LogInfo("A simple log message");
11+
SentrySdk.Logger.LogError("A {0} log message", "formatted");
1212
```
1313

1414
<Alert title="Note">
@@ -27,12 +27,12 @@ The `LoggerExtensions` extension methods expose various overloads that you can u
2727

2828
| Microsoft.Extensions.Logging.LogLevel | Sentry.SentryLogLevel | Sentry Logs UI Severity |
2929
| --- | --- | --- |
30-
| Trace | Trace | TRACE |
31-
| Debug | Debug | DEBUG |
32-
| Information | Info | INFO |
33-
| Warning | Warning | WARN |
34-
| Error | Error | ERROR |
35-
| Critical | Fatal | FATAL |
30+
| Trace | Trace | trace |
31+
| Debug | Debug | debug |
32+
| Information | Info | info |
33+
| Warning | Warning | warn |
34+
| Error | Error | error |
35+
| Critical | Fatal | fatal |
3636

3737
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.
3838

@@ -55,22 +55,48 @@ Sentry Structured Logs also work with [High-performance logging in .NET](https:/
5555

5656
</PlatformSection>
5757

58-
<PlatformSection notSupported={["dotnet.aspnetcore", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.extensions-logging", "dotnet.maui"]}>
58+
<PlatformSection supported={["dotnet.serilog"]}>
59+
60+
Once the feature is enabled on the SDK and the SDK is initialized, you can send logs using the _Serilog_ APIs.
61+
62+
The static `Log` and instance `Logger` types expose various methods that you can use to log messages at six different log levels automatically mapped to Sentry's severity:
63+
64+
| Serilog.Events.LogEventLevel | Sentry.SentryLogLevel | Sentry Logs UI Severity |
65+
| --- | --- | --- |
66+
| Verbose | Trace | trace |
67+
| Debug | Debug | debug |
68+
| Information | Info | info |
69+
| Warning | Warning | warn |
70+
| Error | Error | error |
71+
| Fatal | Fatal | fatal |
72+
73+
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.
74+
75+
```csharp
76+
using (LogContext.PushProperty("Version", 5150))
77+
{
78+
Log.Information("A simple log message");
79+
Log.Error("A {Parameter} log message", "formatted");
80+
Log.ForContext("Property", "Value").Warning("Message with Property");
81+
}
82+
```
83+
84+
The _Enrichments_ of _log events_ are attached as attributes to the logs, alongside a set of default attributes automatically provided by the SDK.
85+
86+
</PlatformSection>
87+
88+
<PlatformSection notSupported={["dotnet.aspnetcore", "dotnet.azure-functions-worker", "dotnet.blazor-webassembly", "dotnet.extensions-logging", "dotnet.maui", "dotnet.serilog"]}>
5989

6090
The SDK automatically provides a set of default attributes attached to your logs.
6191
Additionally, you can attach custom attributes via a delegate.
6292

6393
```csharp
64-
SentrySdk.Experimental.Logger.LogWarning("A log message with additional attributes.", [], static log =>
94+
SentrySdk.Logger.LogWarning(static log =>
6595
{
6696
log.SetAttribute("my.attribute", "value");
67-
});
97+
}, "A log message with additional attributes.");
6898
```
6999

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-
74100
Supported attribute types are:
75101
- Textual: `string` and `char`
76102
- Logical: `bool`

0 commit comments

Comments
 (0)