-
Notifications
You must be signed in to change notification settings - Fork 20
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #34 from serilog/dev
5.0.1 Release
- Loading branch information
Showing
5 changed files
with
359 additions
and
94 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -18,20 +18,28 @@ Log.Logger = new LoggerConfiguration() | |
| new[] { "globalTag1", "globalTag2" }, | ||
| new[] { "ignoreField1", "ignoreField2" }, | ||
| "CustomGroupKeyProperty", | ||
| "CustomTagsProperty") | ||
| "CustomTagsProperty", | ||
| "CustomUserInfoProperty") | ||
| .CreateLogger(); | ||
| ``` | ||
| ### Required | ||
| #### applicationKey | ||
| `string` | ||
|
|
||
| ### Optional | ||
| #### wrapperExceptions | ||
| `type: IEnumerable<Exception>` | ||
| ### applicationKey | ||
| `type: string` | ||
|
|
||
| `required` | ||
|
|
||
| Each application you create in Raygun will have an API Key which you can pass in here to specify where the crash reports will be sent to. Although this is required, you can set this to null or empty string which would result in crash reports not being sent. This can be useful if you want to configure your local environment to not send crash reports to Raygun and then use config transforms or the like to provide an API key for other environments. | ||
|
|
||
| ### wrapperExceptions | ||
| `type: IEnumerable<Type>` | ||
|
|
||
| `default: null` | ||
|
|
||
| #### userNameProperty | ||
| This is a list of wrapper exception types that you're not interested in logging to Raygun. Whenever an undesired wrapper exception is logged, it will be discarded and only the inner exception(s) will be logged. | ||
|
|
||
| For example, you may not be interested in the details of an AggregateException, so you could include `typeof(AggregateException)` in this list of wrapperExceptions. All inner exceptions of any logged AggregateException would then be sent to Raygun as separate crash reports. | ||
|
|
||
| ### userNameProperty | ||
| `type: string` | ||
|
|
||
| `default: UserName` | ||
|
|
@@ -40,50 +48,154 @@ Log.Logger = new LoggerConfiguration() | |
| Log.ForContext("CustomUserNameProperty", "John Doe").Error(new Exception("random error"), "other information"); | ||
| ``` | ||
|
|
||
| #### applicationVersionProperty | ||
| ### applicationVersionProperty | ||
| `type: string` | ||
|
|
||
| `default: ApplicationVersion` | ||
|
|
||
| By default, crash reports sent to Raygun will have an ApplicationVersion field based on the version of the entry assembly for your application. If this is not being picked up correctly, or if you want to provide a different version, then you can do so by including the desired value in the logging properties collection. | ||
|
|
||
| You can specify the property key that you place the version in by using this applicationVersionProperty setting. Otherwise the version will be read from the "ApplicationVersion" key. | ||
|
|
||
| ```csharp | ||
| Log.ForContext("CustomAppVersionProperty", "1.2.11").Error(new Exception("random error"), "other information"); | ||
| ``` | ||
|
|
||
| #### restrictedToMinimumLevel | ||
| ### restrictedToMinimumLevel | ||
| `type: LogEventLevel` | ||
|
|
||
| `default: LogEventLevel.Error` | ||
|
|
||
| #### formatProvider | ||
| ### formatProvider | ||
| `type: IFormatProvider` | ||
|
|
||
| `default: null` | ||
|
|
||
| #### tags | ||
| ### tags | ||
| `type: IEnumerable<string>` | ||
|
|
||
| `default: null` | ||
|
|
||
| #### ignoredFormFieldNames | ||
| This is a list of global tags that will be included on every crash report sent with this Serilog sink. | ||
|
|
||
| ### ignoredFormFieldNames | ||
| `type: IEnumerable<string>` | ||
|
|
||
| `default: null` | ||
|
|
||
| #### groupKeyProperty | ||
| Crash reports sent to Raygun from this Serilog sink will include HTTP context details if present. (Currently only supported in .NET Framework applications). This option lets you specify a list of form fields that you do not want to be sent to Raygun. | ||
|
|
||
| Setting `ignoredFormFieldNames` to a list that only contains "*" will cause no form fields to be sent to Raygun. Placing * before, after or at both ends of an entry will perform an ends-with, starts-with or contains operation respectively. | ||
|
|
||
| Note that HTTP headers, query parameters, cookies, server variables and raw request data can also be filtered out. Configuration to do so is described in the [RaygunSettings](#raygun4net-features-configured-via-raygunsettings) section further below. | ||
|
|
||
| The `ignoreFormFieldNames` entries will also strip out specified values from the raw request payload if it is multipart/form-data. | ||
|
|
||
| ### groupKeyProperty | ||
| `type: string` | ||
|
|
||
| `default: GroupKey` | ||
|
|
||
| Crash reports sent to Raygun will be automatically grouped together based on stack trace and exception type information. The `groupKeyProperty` setting specifies a key in the logging properties collection where you can provide a grouping key. Crash reports containing a grouping key will not be grouped automatically by Raygun. Instead, crash reports with matching custom grouping keys will be grouped together. | ||
|
|
||
| ```csharp | ||
| Log.ForContext("CustomGroupKeyProperty", "TransactionId-12345").Error(new Exception("random error"), "other information"); | ||
| ``` | ||
|
|
||
| #### tagsProperty | ||
| ### tagsProperty | ||
| `type: string` | ||
|
|
||
| `default: Tags` | ||
|
|
||
| This allows you to specify a key in the properties collection that contains a list of tags to include on crash reports. Note that these will be included in addition to any global tags [described above](#tags). If you set a list of tags in the properties collection multiple times (e.g. at different logging scopes) then only the latest list of tags will be used. | ||
|
|
||
| ```csharp | ||
| Log.ForContext("CustomTagsProperty", new[] {"tag1", "tag2"}).Error(new Exception("random error"), "other information"); | ||
| Log.Error(new Exception("random error"), "other information {@CustomTagsProperty}", new[] {"tag3", "tag4"}); | ||
| ``` | ||
| ``` | ||
|
|
||
| ### userInfoProperty | ||
| `type: string` | ||
|
|
||
| `default: null` | ||
|
|
||
| This is null by default, so you need to configure the userInfoProperty name if you want to log more user information in this way. This will cause the provided RaygunIdentifierMessage to be included in the "User" section of the Raygun payload, allowing the information to be picked up by the "Users" section of the Raygun service. It's recommended to destructure the RaygunIdentifierMessage, but this feature will still work if you don't. Sending user information in this way will overwrite the use of the userNameProperty. | ||
|
|
||
| The user identifier passed into the RaygunIdentifierMessage constructor could be the users name, email address, database id or whatever works best for you to identify unique users. | ||
|
|
||
| ```csharp | ||
| var userInfo = new RaygunIdentifierMessage("12345") | ||
| { | ||
| FirstName = "John", | ||
| FullName = "John Doe", | ||
| Email = "[email protected]" | ||
| }; | ||
|
|
||
| Log.ForContext("CustomUserInfoProperty", userInfo, true).Error(new Exception("random error"), "other information"); | ||
| ``` | ||
|
|
||
| ## Raygun4Net features configured via RaygunSettings | ||
|
|
||
| This sink wraps the [Raygun4Net](https://github.com/MindscapeHQ/raygun4net) provider to build a crash report from an Exception and send it to Raygun. This makes the following Raygun4Net features available to you. To use these features, you need to add RaygunSettings to your configuration as explained below which is separate to the Serilog configuration. | ||
|
|
||
| **.NET Core** | ||
|
|
||
| Add a RaygunSettings block to your appsettings.config file where you can populate the settings that you want to use. | ||
|
|
||
| ``` | ||
| "RaygunSettings": { | ||
| "Setting": "Value" | ||
| } | ||
| ``` | ||
|
|
||
| **.NET Framework** | ||
|
|
||
| Add the following section within the configSections element of your app.config or web.config file. | ||
|
|
||
| ```xml | ||
| <section name="RaygunSettings" type="Mindscape.Raygun4Net.RaygunSettings, Mindscape.Raygun4Net"/> | ||
| ``` | ||
|
|
||
| Then add a RaygunSettings element containing the desired settings somewhere within the configuration element of the app.config or web.config file. | ||
|
|
||
| ```xml | ||
| <RaygunSettings setting="value"/> | ||
| ``` | ||
|
|
||
| ### ThrowOnError | ||
| `type: bool` | ||
|
|
||
| `default: false` | ||
|
|
||
| This is false by default, which means that any exception that occur within Raygun4Net itself will be silently caught. Setting this to true will allow any exceptions occurring in Raygun4Net to be thrown, which can help debug issues with Raygun4Net if crash reports aren't showing up in Raygun. | ||
|
|
||
| ### IgnoreSensitiveFieldNames | ||
| `type: string[]` | ||
|
|
||
| `default: null` | ||
|
|
||
| Crash reports sent to Raygun from this Serilog sink will include HTTP context details if present. (Currently only supported in .NET Framework applications). `IgnoreSensitiveFieldNames` lets you specify a list of HTTP query parameters, form fields, headers, cookies and server variables that you do not want to be sent to Raygun. Additionally, entries in this setting will be attempted to be stripped out of the raw request payload (more options for controlling this are explained in the `IsRawDataIgnored` section below). | ||
|
|
||
| Setting `IgnoreSensitiveFieldNames` to a list that only contains "*" will cause none of these things to be sent to Raygun. Placing * before, after or at both ends of an entry will perform an ends-with, starts-with or contains operation respectively. | ||
|
|
||
| Individual options are also available which function in the same way as IgnoreSensitiveFieldNames: `IgnoreQueryParameterNames`, `IgnoreFormFieldNames`, `IgnoreHeaderNames`, `IgnoreCookieNames` and `IgnoreServerVariableNames`. | ||
|
|
||
| The `IgnoreFormFieldNames` entries will also strip out specified values from the raw request payload if it is multipart/form-data. | ||
|
|
||
| ### IsRawDataIgnored | ||
| `type: bool` | ||
|
|
||
| `default: false` | ||
|
|
||
| By default, Raygun crash reports will capture the raw request payload of the current HTTP context if present. (Currently only supported in .NET Framework applications). If you would not like to include raw request payloads on crash reports sent to Raygun, then you can set `IsRawDataIgnored` to true. | ||
|
|
||
| If you do want to include the raw request payload, but want to filter out sensitive fields, then you can use the `IgnoreSensitiveFieldNames` options described above. You'll also need to specify how the fields should be stripped from the raw request payload. Set `UseXmlRawDataFilter` to true for XML payloads or/and set `UseKeyValuePairRawDataFilter` to true for payloads of the format "key1=value1&key2=value2". | ||
|
|
||
| Setting `IsRawDataIgnoredWhenFilteringFailed` to true will cause the entire raw request payload to be ignored in cases where specified sensitive values fail to be stripped out. | ||
|
|
||
| ### CrashReportingOfflineStorageEnabled | ||
| `type: bool` | ||
|
|
||
| `default: true` | ||
|
|
||
| Only available in .NET Framework applications. This is true by default which will cause crash reports to be saved to isolated storage (if possible) in cases where they fail to be sent to Raygun. This option lets you disable this functionality by setting it to false. When enabled, a maximum of 64 crash reports can be saved. This limit can be set lower than 64 via the `MaxCrashReportsStoredOffline` option. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.