getsentry / getsentry/sentry-dotnet
Exceptions for Structured Logs
- Dominant language
- C#
- Stars
- 770
- Forks
- 248
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 49
Description
### Description
Through both internal and external feedback, as the next addition to Structured Logs, we should support Exceptions.
Especially considering the APIs of ` Microsoft.Extensions.Logging` through the [ILogger.Log]() method, and the [LoggerExtensions]() extension methods.
### `Sentry.SentryStructuredLogger`
We could add overloads that take an `Exception`, either with or without the *template*-String, or both:
```CSharp
public void Log/*Level*/(Exception? exception);
public void Log/*Level*/(string template, object[]? parameters = null, Exception? exception);
public void Log/*Level*/(Exception? exception, string template, object[]? parameters = null);
```
For comparison the `LoggerExtensions` methods, which optionally places the `exception` before the `message`:
```CSharp
public static void Log/*Level*/(this ILogger logger, EventId eventId, Exception? exception, string? message, params object?[] args)
public static void Log/*Level*/(this ILogger logger, EventId eventId, string? message, params object?[] args)
public static void Log/*Level*/(this ILogger logger, Exception? exception, string? message, params object?[] args)
public static void Log/*Level*/(this ILogger logger, string? message, params object?[] args)
```
### `Microsoft.Extensions.Logging.ILogger`
Due to the prevalence of this de-facto Logging-Abstraction for all modern application models,
we should not just discard the `Exception` already available and used by existing applications.
### `log` Envelope and Payload
Structured Logs is not a replacement for Events, but an enhancement.
Also, the average byte size of a log should be kept as small as possible, see [Logs Dev Docs]().
So we should not log entire Stack Traces.
However, we could add some limited information about the `Exception` instance, such as *Message* and *Type*, attached as attributes.
E.g.
```JSON
{
"body": "..",
..,
"attributes": {
"exception.message": {
"value": "An item with the same key has already been added. Key: my-key",
"type": "string"
}
"exception.type": {
"value": "System.ArgumentException",
"type": "string"
}
}
}
```
See also OTEL's Exception: [https://getsentry.github.io/sentry-conventions/generated/attributes/exception.html]()
What should be the behavior, if no message is provided, but only an `Exception`?
* `Exception`-Message as `"body"`, `Exception`-Type as attribute.
* `Exception`-Message as `"body"`, both `Exception`-Message and `Exception`-Type as attribute.
### Sentry
Supporting a clickable link from Logs to Issues/Errors is currently not considered (see [https://github.com/getsentry/sentry-dotnet/issues/4132#issuecomment-3179177147]()).
However, from Issues/Errors, you can view Logs with the same Trace-ID,
as well has navigate from Logs via the Trace to the Error.
Contributor guide
Assessment
This issue has not been assessed yet.