Skip to content

Commit

Permalink
Merge pull request #55 from MindscapeHQ/dev
Browse files Browse the repository at this point in the history 
Version 5.3.0 - Update README docs
  • Loading branch information
@sumitramanga
sumitramanga authored Apr 27, 2023
2 parents 8b738f7 + 6dffe0c commit e9056bb
Showing 1 changed file with 102 additions and 51 deletions.
153 changes: 102 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,32 @@
# serilog-sinks-raygun

A Serilog sink that writes events to Raygun
Serilog Sinks error and performance monitoring with Raygun is available using the serilog-sinks-raygun provider.

## Usage
serilog-sinks-raygun is a library that you can easily add to your website or web application, which will then monitor your application and display all Serilog errors and issues affecting your users within your Raygun account. Installation is painless.

Add the [Serilog](https://www.nuget.org/packages/serilog/) and [Serilog.Sinks.Raygun](https://www.nuget.org/packages/Serilog.Sinks.Raygun) nuget packages.
Via the package manager, or via the command line:
The provider is a single package (Serilog.Sinks.Raygun) which includes the sole dependency (Serilog), allowing you to drop it straight in.

```powershell
## Getting started

## Step 1 - Add packages

Install the Serilog (if not included already) and Serilog.Sinks.Raygun package into your project. You can either use the below dotnet CLI command, or the NuGet management GUI in the IDE you use.

```bash
dotnet add package Serilog
dotnet add package Serilog.Sinks.Raygun
```

Then setup the logger configuration; inside the `Program.Main()`, `Global.asax.Application_Start`, etc.
------

```csharp
## Step 2 - Add logger configuration

Setup the logger configuration by passing in your API key. You can do this inside of Program.Main(), Global.asax, Application_Start, or how ever your application is set up with the main, start up running method of your application.

```cs
Log.Logger = new LoggerConfiguration()
.MinimumLevel.Verbose()
.WriteTo.Raygun("RaygunAPIKey",
.WriteTo.Raygun("paste_your_api_key_here",
ListOfWrapperExceptions,
"CustomUserNameProperty",
"CustomAppVersionProperty",
Expand All @@ -32,7 +41,11 @@ Log.Logger = new LoggerConfiguration()
.CreateLogger();
```

When configuring using a JSON configuration file use the following example.
------

## Step 3 - Configure the JSON configuration file

When configuring using a JSON configuration file use the following example -

```json
{
Expand All @@ -44,7 +57,7 @@ When configuring using a JSON configuration file use the following example.
{
"Name": "Raygun",
"Args": {
"applicationKey": "RaygunAPIKey",
"applicationKey": "paste_your_api_key_here",
"userNameProperty": "CustomUserNameProperty",
"applicationVersionProperty": "CustomAppVersionProperty",
"restrictedToMinimumLevel": "Error",
Expand All @@ -60,14 +73,18 @@ When configuring using a JSON configuration file use the following example.
}
```

### applicationKey
### Properties

**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.
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**

### wrapperExceptions
`type: IEnumerable<Type>`

`default: null`
Expand All @@ -76,46 +93,61 @@ This is a list of wrapper exception types that you're not interested in logging

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

**userNameProperty**

`type: string`

`default: UserName`

```csharp
This is so you can specify the username to log the information as a part of the crash report. By default it is UserName. You can set this to be to `null` if you do not want to use this feature.

```cs
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.
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
```cs
Log.ForContext("CustomAppVersionProperty", "1.2.11").Error(new Exception("random error"), "other information");
```

### restrictedToMinimumLevel
**restrictedToMinimumLevel**

`type: LogEventLevel`

`default: LogEventLevel.Error`

### formatProvider
You can set the minimum log event level required in order to write an event to the sink. By default, this is set to Error as Raygun is mostly used for error reporting.

**formatProvider**

`type: IFormatProvider`

`default: null`

### tags
This property supplies culture-specific formatting information. By default, it is null.

**tags**

`type: IEnumerable<string>`

`default: null`

This is a list of global tags that will be included on every crash report sent with this Serilog sink.

### ignoredFormFieldNames

**ignoredFormFieldNames**

`type: IEnumerable<string>`

`default: null`
Expand All @@ -128,39 +160,44 @@ Note that HTTP headers, query parameters, cookies, server variables and raw requ

The `ignoreFormFieldNames` entries will also strip out specified values from the raw request payload if it is multipart/form-data.

### groupKeyProperty

**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
```cs
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
```cs
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
**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.
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
```cs
var userInfo = new RaygunIdentifierMessage("12345")
{
FirstName = "John",
Expand All @@ -171,15 +208,16 @@ var userInfo = new RaygunIdentifierMessage("12345")
Log.ForContext("CustomUserInfoProperty", userInfo, true).Error(new Exception("random error"), "other information");
```

### onBeforeSend

**onBeforeSend**

`type: Action<OnBeforeSendParameters>`

`default: null`

This action allows you to manipulate the crash report payloads that get sent to Raygun.
By default it is `null`, so you don't need to set it in the constructor. If the action is `null`, nothing happens; if an `Action<OnBeforeSendParameters>` is passed, it gets called just before the crash report payload gets serialized and sent to Raygun.
The arguments to the action are of type `Struct OnBeforeSendArguments`; they are passed to the action when it is called and contain references to the following objects passed by the Raygun client object:
```csharp
This action allows you to manipulate the crash report payloads that get sent to Raygun. By default it is `null`, so you don't need to set it in the constructor. If the action is `null`, nothing happens; if an `Action<OnBeforeSendParameters>` is passed, it gets called just before the crash report payload gets serialized and sent to Raygun. The arguments to the action are of type `Struct OnBeforeSendArguments`; they are passed to the action when it is called and contain references to the following objects passed by the Raygun client object:

```cs
// Abstracted away version of the struct to just show the properties
struct OnBeforeSendArguments
{
Expand All @@ -188,34 +226,37 @@ struct OnBeforeSendArguments
}
```

The provided action can read and/or modify their properties accordingly to produce the desired effect.
For example, one can change the `MachineName` property in the `Details` of the `RaygunMessage` as follows:
The provided action can read and/or modify their properties accordingly to produce the desired effect. For example, one can change the `MachineName` property in the `Details` of the `RaygunMessage` as follows:

```csharp
```cs
Log.Logger = new LoggerConfiguration()
.MinimumLevel.Verbose()
.WriteTo.Raygun(
applicationKey: "",
applicationKey: "paste_your_api_key_here",
onBeforeSend: arguments => {
arguments.RaygunMessage.Details.MachineName = "MyMachine";
})
.CreateLogger();
);
```

------

## Enrich with HTTP request and response data

_Note: This is only valid for .NET Standard 2.0 and above projects. In full framework ASP.NET applications the HTTP request and response are available to Raygun4Net through the `HttpContext.Current` accessor.
In .NET Core this is not available so you'll need to add the Serilog enricher using the `WithHttpDataForRaygun` method to capture the HTTP request and response data._
This is only valid for .NET Standard 2.0 and above projects.

In full framework, ASP.NET applications, the HTTP request and response are available to Raygun4Net through the `HttpContext.Current` accessor.

For .NET Core, this won't be avaliable. Therefore, you'll need to add the Serilog enricher using the `WithHttpDataForRaygun` method to capture the HTTP request and response data.


### Configuration

All parameters to `WithHttpDataForRaygun` are optional.
All parameters to WithHttpDataForRaygun are optional.

```csharp
```cs
Log.Logger = new LoggerConfiguration()
.WriteTo.Raygun("RaygunAPIKey")
.WriteTo.Raygun("paste_your_api_key_here")
.Enrich.WithHttpDataForRaygun(
new HttpContextAccessor(),
LogEventLevel.Error,
Expand Down Expand Up @@ -254,10 +295,13 @@ When configuring using a JSON configuration file use the following example.
}
```

------

## 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 Framework**

Add the following section within the configSections element of your app.config or web.config file.
Expand All @@ -272,27 +316,32 @@ Then add a RaygunSettings element containing the desired settings somewhere with
<RaygunSettings setting="value"/>
```

### ThrowOnError
**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.
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**

### 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.
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`.
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

**IsRawDataIgnored**

`type: bool`

`default: false`
Expand All @@ -303,7 +352,9 @@ If you do want to include the raw request payload, but want to filter out sensit

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

**CrashReportingOfflineStorageEnabled**

`type: bool`

`default: true`
Expand Down

0 comments on commit e9056bb

Please sign in to comment.