getsentry / getsentry/sentry-dotnet

Exceptions for Structured Logs

Open
#4,440 11 comments 3 reactions 0 assignees View on GitHub
.NET 2. High Feature Logs Microsoft.Extensions.Logging public API
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.