|
| 1 | +To enable logging in your Unity game, you need to configure the Sentry SDK with structured logging enabled. |
| 2 | + |
| 3 | +### Project Settings Configuration |
| 4 | + |
| 5 | +1. Inside the editor open: **Tools > Sentry > Logging** |
| 6 | +2. Check the **Enable Structured Logging** option |
| 7 | + |
| 8 | +### Programmatic Configuration |
| 9 | + |
| 10 | +Alternatively, you can enable logging programmatically through the [configure callback](/platforms/unity/configuration/options/programmatic-configuration): |
| 11 | + |
| 12 | +```csharp |
| 13 | +public override void Configure(SentryUnityOptions options) |
| 14 | +{ |
| 15 | + options.EnableLogs = true; |
| 16 | +} |
| 17 | +``` |
| 18 | + |
| 19 | +or if you're manually initializing the SDK: |
| 20 | + |
| 21 | +```csharp |
| 22 | +SentrySdk.Init(options => |
| 23 | +{ |
| 24 | + options.Dsn = "___PUBLIC_DSN___"; |
| 25 | + |
| 26 | + // Enable logs to be sent to Sentry |
| 27 | + options.EnableLogs = true; |
| 28 | +}); |
| 29 | +``` |
| 30 | + |
| 31 | +### Advanced Configuration Options |
| 32 | + |
| 33 | +In addition to enabling Structured Logging you can control the log capture behaviour through some additional options. |
| 34 | + |
| 35 | +#### Automatic Unity Log Forwarding |
| 36 | + |
| 37 | +You can configure the SDK to automatically forward Unity's Debug Logs to Sentry based on the enabled log level in the configuration window, or programmatically: |
| 38 | + |
| 39 | +```csharp |
| 40 | +// Configure automatic log forwarding programmatically |
| 41 | +options.EnableLogs = true; |
| 42 | + |
| 43 | +options.CaptureStructuredLogsForLogType[LogType.Log] = false; |
| 44 | +options.CaptureStructuredLogsForLogType[LogType.Warning] = true; |
| 45 | +options.CaptureStructuredLogsForLogType[LogType.Assert] = true; |
| 46 | +options.CaptureStructuredLogsForLogType[LogType.Error] = true; |
| 47 | +options.CaptureStructuredLogsForLogType[LogType.Exception] = true; |
| 48 | + |
| 49 | +options.AddBreadcrumbsWithStructuredLogs = false; // Send as structured logs instead of breadcrumbs |
| 50 | +``` |
| 51 | + |
| 52 | +#### Before-Log Handler |
| 53 | + |
| 54 | +To filter logs, or update them before they are sent to Sentry, you can provide a custom `BeforeSendLog` callback: |
| 55 | + |
| 56 | +```csharp |
| 57 | +options.SetBeforeSendLog(log => |
| 58 | +{ |
| 59 | + if (log.Message.StartsWith("Sensitive:")) |
| 60 | + { |
| 61 | + return null; |
| 62 | + } |
| 63 | + |
| 64 | + // Set a custom attribute for all other logs sent to Sentry |
| 65 | + log.SetAttribute("my.attribute", "value"); |
| 66 | + |
| 67 | + return log; |
| 68 | +}); |
| 69 | +``` |
| 70 | + |
| 71 | +The callback function set via `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. |
| 72 | + |
| 73 | +The log object of type `SentryLog` has the following members: |
| 74 | +- `Timestamp` Property: (`DateTimeOffset`) The timestamp of the log. |
| 75 | +- `TraceId` Property: (`SentryId`) The trace id of the log. |
| 76 | +- `Level` Property: (`SentryLogLevel`) The severity level of the log. Either `Trace`, `Debug`, `Info`, `Warning`, `Error`, or `Fatal`. |
| 77 | +- `Message` Property: (`string`) The formatted log message. |
| 78 | +- `Template` Property: (`string?`) The parameterized template string. |
| 79 | +- `Parameters` Property: (`ImmutableArray<KeyValuePair<string, object>>`) The parameters to the template string. |
| 80 | +- `ParentSpanId` Property: (`SpanId?`) The span id of the span that was active when the log was collected. |
| 81 | +- `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`. |
| 82 | +- `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. |
0 commit comments