Backtrace 2.1.10-alpha1
See the version list below for details.
dotnet add package Backtrace --version 2.1.10-alpha1
NuGet\Install-Package Backtrace -Version 2.1.10-alpha1
<PackageReference Include="Backtrace" Version="2.1.10-alpha1" />
paket add Backtrace --version 2.1.10-alpha1
#r "nuget: Backtrace, 2.1.10-alpha1"
// Install Backtrace as a Cake Addin #addin nuget:?package=Backtrace&version=2.1.10-alpha1&prerelease // Install Backtrace as a Cake Tool #tool nuget:?package=Backtrace&version=2.1.10-alpha1&prerelease
Backtrace
Backtrace's integration with C# applications allows customers to capture and report handled and unhandled C# exceptions to their Backtrace instance, instantly offering the ability to prioritize and debug software errors.
Usage
// replace with your endpoint url and token
var backtraceCredentials =
new BacktraceCredentials(@"https://myserver.sp.backtrace.io:6097", "4dca18e8769d0f5d10db0d1b665e64b3d716f76bf182fbcdad5d1d8070c12db0");
var backtraceClient = new BacktraceClient(backtraceCredentials);
try{
//throw exception here
}
catch(Exception exception){
await backtraceClient.SendAsync(new BacktraceReport(exception));
}
Table of contents
- Features Summary
- Supported .NET Frameworks
- Installation
- Running sample application
- Documentation
- Architecture
- Good to know
- Release Notes
Features Summary <a name="features-summary"></a>
- Light-weight C# client library that quickly submits C#/.NET exceptions and crashes to your Backtrace dashboard
- Can include callstack, system metadata, custom metadata, and file attachments (e.g. minidump) if needed.
- Supports a wide range of .NET versions such as .NET Framework, .NET Core, Mono, Xamarin and Unity. Read more here
- Supports both CLI and IDE work environments
- Supports asynchronous Tasks in .NET 4.5+
- Supports offline database for error report storage and re-submission in case of network outage
- Fully customizable and extendable event handlers and base classes for custom implementations
- Available as a NuGet Package as well as a fully open-sourced Github Release.
Supported .NET Frameworks <a name="supported-frameworks"></a>
- .NET Framework 3.5 +
- .NET Framework 4.5 +
- getting information about application thread
- handling unhandled application exceptions
- .NET Standard:
- .NET Core 2.0 application
- Xamarin
- Universal Windows Platform
- Unity
Installation <a name="installation"></a>
Prerequisites <a name="installation-before-start"></a>
Development Environment
- On Windows, we recommend Visual Studio 2017 or above for IDE. You can download and install Visual Studio here. As an alternative to
Visual Studio
you can use .NET Core command line interface, see installation guide here - On Mac OS X, you can download and install Visual Studio here if you prefer using an IDE. For command line, you should to download and install .NET Core 2.0 or above.
- On Linux, Visual Studio Code is available as a light-weight IDE. Similarly, you can use .NET Core command line interface, see instruction for Linux here
NuGet
The Backtrace library is available on NuGet. You can read more about NuGet and how to download the packages here
Installing Backtrace via NuGet <a name="installation-nuget"></a>
You can install Backtrace via NuGet using the following commands:
Windows NuGet CLI:
Install-Package Backtrace
Linux/Mac OS X .NET Core CLI:
dotnet add package Backtrace
Running sample application <a name="sample-app"></a>
Visual Studio <a name="sample-app-vs"></a>
Visual Studio allows you to build a project and run all available samples (includes support for .NET Core, .NET Framework 4.5, .NET Framework 3.5).
- Double click
.sln
file or open project directory in Visual Studio. - In Solution Explorer navigate to directory
Sample
and set preferred project (.NET Core/Framework) as startup project.
- Open
Program.cs
class in any Backtrace Sample project and replaceBacktraceCredential
constructor patemeters with with yourBacktrace endpoint URL
(e.g. https://xxx.sp.backtrace.io:6098) andsubmission token
:
var backtraceCredentials = new BacktraceCredentials(@"https://myserver.sp.backtrace.io:6097", "4dca18e8769d0f5d10db0d1b665e64b3d716f76bf182fbcdad5d1d8070c12db0");
- Press
Ctrl+Shift+B
tobuild
solution - Press
F5
to run the project - You should see new errors in your Backtrace instance. Refresh the Project page or Query Builder to see new details in real-time.
.NET Core command line <a name="sample-app-cli"></a>
You can use .NET Core's CLI to run sample project on Windows, Mac OS and Linux. To run a sample project using .NET Core CLI:
- While in solution directory, navigate to Backtrace.Core sample application:
cd Backtrace.Core
- Open
Program.cs
in project Backtrace.Core and replaceBacktraceCredential
constructor parameters with with yourBacktrace endpoint URL
(e.g. https://xxx.sp.backtrace.io:6098) andsubmission token
:
var backtraceCredentials = new BacktraceCredentials(@"https://myserver.sp.backtrace.io:6097", "4dca18e8769d0f5d10db0d1b665e64b3d716f76bf182fbcdad5d1d8070c12db0");
- Build the project:
dotnet build
- When the build completes, run the project:
dotnet run
- You should see new errors in your Backtrace instance. Refresh the Project page or Query Builder to see new details in real-time.
Visual Studio for MacOS <a name="sample-app-vs-mac"></a>
- Open the Backtrace solution in Visual Studio, unload all projects except Backtrace, Backtrace.Tests and Backtrace.Core, and set Backtrace.Core as your startup project:
- Open
Program.cs
class in project Backtrace.Core and replaceBacktraceCredential
constructor parameters with with yourBacktrace endpoint URL
(e.g. https://xxx.sp.backtrace.io:6098) andsubmission token
:
var backtraceCredentials = new BacktraceCredentials(@"https://myserver.sp.backtrace.io:6097", "4dca18e8769d0f5d10db0d1b665e64b3d716f76bf182fbcdad5d1d8070c12db0");
- Build the project.
- Upon successful build, run the project.
- You should see new errors in your Backtrace instance. Refresh the Project page or Query Builder to see new details in real-time.
Documentation <a name="documentation"></a>
Initialize a new BacktraceClient <a name="documentation-initialization"></a>
First create a BacktraceCredential
instance with your Backtrace endpoint URL
(e.g. https://xxx.sp.backtrace.io:6098) and submission token
, and supply it as a parameter in the BacktraceClient
constructor:
var credentials = new BacktraceCredentials("backtrace_endpoint_url", "token");
var backtraceClient = new BacktraceClient(credentials);
For more advanced usage of BacktraceClient
, you can supply BacktraceClientConfiguration
as a parameter. See the following example:
var credentials = new BacktraceCredentials("backtrace_endpoint_url", "token");
var configuration = new BacktraceClientConfiguration(credentials){
ClientAttributes = new Dictionary<string, object>() {
{ "attribute_name", "attribute_value" } },
ReportPerMin = 3,
}
var backtraceClient = new BacktraceClient(configuration);
For more information on BacktraceClientConfiguration
parameters please see <a href="#architecture-BacktraceClient">Architecture</a> section.
Notes:
- If parameter
reportPerMin
is equal to 0, there is no limit on the number of error reports per minute. When thereportPerMin
cap is reached,BacktraceClient.Send/BacktraceClient.SendAsync
method will return false, - If you develop application behind the proxy you can pass
WebProxy
object toBacktraceCredentials
object. We will try to useWebProxy
object when user pass it toBacktrace
. To setup proxy use propertyProxy
, BacktraceClient
allows you to unpackAggregateExceptions
and send only exceptions that are available inInnerException
property ofAggregateException
. By defaultBacktraceClient
will sendAggregateException
information to Backtrace server. To avoid sending these reports, please overrideUnpackAggregateException
and set value totrue
.
Database initialization <a name="documentation-database-initialization"></a>
BacktraceClient
allows you to customize the initialization of BacktraceDatabase
for local storage of error reports by supplying a BacktraceDatabaseSettings
parameter, as follows:
var dbSettings = new BacktraceDatabaseSettings("databaseDirectory"){
MaxRecordCount = 100,
MaxDatabaseSize = 1000,
AutoSendMode = true,
RetryBehavior = Backtrace.Types.RetryBehavior.ByInterval
};
var database = new BacktraceDatabase(dbSettings);
var credentials = new BacktraceCredentials("backtrace_endpoint_url", "token");
var configuration = new BacktraceClientConfiguration(credentials);
var backtraceClient = new BacktraceClient(configuration, database);
Notes:
- If a valid
databaseDirectory
directory is supplied, the Backtrace library will generate and attach a minidump to each error report automatically. Otherwise,BacktraceDatabase
will be disabled, - You can set
backtraceClient.MiniDumpType
toMiniDumpType.None
if you don't want to generate minidump files.
Deduplication
Backtrace C# library allows you to aggregate the same reports. By using Backtrace deduplication mechanism you can aggregate the same reports and send only one message to Backtrace Api. As a developer you can choose deduplication options. Please use DeduplicationStrategy
enum to setup possible deduplication rules or copy example below to setup deduplication strategy:
var dbSettings = new BacktraceDatabaseSettings(path)
{
DeduplicationStrategy = DeduplicationStrategy.LibraryName | DeduplicationStrategy.Classifier | DeduplicationStrategy.Message,
}
Deduplication strategy enum types:
- Ignore - ignore deduplication strategy,
- Default - deduplication strategy will only use current strack trace to find duplicated reports,
- Classifier - deduplication strategy will use stack trace and exception type to find duplicated reports,
- Message - deduplication strategy will use stack trace and exception message to find duplicated reports,
- LibraryName - deduplication strategy will use stack trace and faulting library name to find duplicated reports.
To combine all possible deduplication strategies please use code below:
DeduplicationStrategy = DeduplicationStrategy.LibraryName | DeduplicationStrategy.Classifier | DeduplicationStrategy.Message
Notes:
- When you aggregate reports via Backtrace C# library,
BacktraceDatabase
will store number of the same reports incounter
file. - Deduplication algorithm will include
BacktraceReport
Fingerprint
andFactor
properties.Fingerprint
property will overwrite deduplication algorithm result.Factor
property will change hash generated by deduplication algorithm. - By storing data in additional counter file we can read number of the same offline reports on application starts and send them to Backtrace when your internet connection back.
- When C# library aggregate multiple reports into one diagnostic data, application will send only one request, not multiple,
BacktraceDatabase
methods allows you to use aggregated diagnostic data together. You can checkHash
property ofBacktraceDatabaseRecord
to check generated hash for diagnostic data andCounter
to check how much the same records we detect.BacktraceDatabase
Count
method will return number of all records stored in database (included deduplicated records),BacktarceDatabase
Delete
method will remove record (with multiple deduplicated records) at the same time.- You can override default hash method by using
GenerateHash
delegate available inBacktraceDatabase
object. When you add your own method implementation,BacktraceDatabase
won't use default deduplication mechanism.
Sending an error report <a name="documentation-sending-report"></a>
BacktraceClient.Send/BacktraceClient.SendAsync
method will send an error report to the Backtrace endpoint specified. There Send
method is overloaded, see examples below:
Using BacktraceReport
The BacktraceReport
class represents a single error report. (Optional) You can also submit custom attributes using the attributes
parameter, or attach files by supplying an array of file paths in the attachmentPaths
parameter.
try
{
//throw exception here
}
catch (Exception exception)
{
var report = new BacktraceReport(
exception: exception,
attributes: new Dictionary<string, object>() { { "key", "value" } },
attachmentPaths: new List<string>() { @"file_path_1", @"file_path_2" }
);
var result = backtraceClient.Send(backtraceReport);
}
Notes:
- if you initialize
BacktraceClient
withBacktraceDatabase
and your application is offline or you pass invalid credentials toBacktraceClient
, reports will be stored in database directory path, - for .NET 4.5+, we recommend to use
SendAsync
method, - if you don't want to use reflection to determine valid stack frame method name, you can pass
false
toreflectionMethodName
. By default this value is equal totrue
, BacktraceReport
allows you to change default fingerprint generation algorithm. You can useFingerprint
property if you want to change fingerprint value. Keep in mind - fingerprint should be valid sha256 string,BacktraceReport
allows you to change grouping strategy in Backtrace server. If you want to change how algorithm group your reports in Backtrace server please overrideFactor
property,Fingerprint
will overwriteBacktraceReport
deduplication strategy! In this case two different reports will use the same hash in deduplication algorithm, that could cause data lost,Factor
can change a result from deduplication algorithm. Hash generated by deduplication model properties will includeFactor
value.
If you want to use Fingerprint
and Factor
property you have to override default property values. See example below to check how to use these properties:
try
{
//throw exception here
}
catch (Exception exception)
{
var report = new BacktraceReport(...){
FingerPrint = "sha256 string",
Factor = exception.GetType().Name
};
....
}
Asynchronous Send Support
For developers that use .NET 4.5+ and .NET Standard we recommend using SendAsync
method, which uses asynchronous Tasks. Both Send
and SendAsync
method returns BacktraceResult
. See example below:
try
{
//throw exception here
}
catch (Exception exception)
{
var report = new BacktraceReport(
exception: exception,
attributes: new Dictionary<string, object>() { { "key", "value" } },
attachmentPaths: new List<string>() { @"file_path_1", @"file_path_2" }
);
var result = await backtraceClient.SendAsync(backtraceReport);
}
Other BacktraceReport Overloads
BacktraceClient
can also automatically create BacktraceReport
given an exception or a custom message using the following overloads of the BacktraceClient.Send
method:
try
{
//throw exception here
}
catch (Exception exception)
{
//use extension method
var report = exception.ToBacktraceReport();
backtraceClient.Send(report);
//pass exception to Send method
backtraceClient.Send(exception);
//pass your custom message to Send method
await backtraceClient.SendAsync("Message");
}
Attaching custom event handlers <a name="documentation-events"></a>
BacktraceClient
allows you to attach your custom event handlers. For example, you can trigger actions before the Send
method:
//Add your own handler to client API
backtraceClient.BeforeSend =
(Model.BacktraceData model) =>
{
var data = model;
//do something with data for example:
data.Attributes.Add("eventAtrtibute", "EventAttributeValue");
if(data.Classifier == null || !data.Classifier.Any())
{
data.Attachments.Add("path to attachment");
}
return data;
};
BacktraceClient
currently supports the following events:
BeforeSend
AfterSend
RequestHandler
OnReportStart
OnClientReportLimitReached
OnUnhandledApplicationException
OnServerResponse
OnServerError
Reporting unhandled application exceptions
BacktraceClient
also supports reporting of unhandled application exceptions not captured by your try-catch blocks. To enable reporting of unhandled exceptions:
backtraceClient.HandleApplicationException();
Unhandled application exception handler will store your report in database. In case if you won't see your report in Backtrace, you will have to relaunch your application.
Custom client and report classes <a name="documentation-customization"></a>
You can extend BacktraceBase
to create your own Backtrace client and error report implementation. You can refer to BacktraceClient
for implementation inspirations.
Architecture <a name="architecture"></a>
BacktraceReport <a name="architecture-BacktraceReport"></a>
BacktraceReport
is a class that describe a single error report. Keep in mind that BacktraceClient
uses CallingAssembly
method to retrieve information about your application.
BacktraceClient <a name="architecture-BacktraceClient"></a>
BacktraceClient
is a class that allows you to instantiate a client instance that interacts with BacktraceApi
. This class sets up connection to the Backtrace endpoint and manages error reporting behavior (for example, saving minidump files on your local hard drive and limiting the number of error reports per minute). BacktraceClient
extends BacktraceBase
class.
BacktraceClient
takes a BacktraceClientConfiguration
parameter, which has the following properties:
Credentials
- theBacktraceCredentials
object to use for connection to the Backtrace server.ClientAttributes
- custom attributes to be submitted to Backtrace alongside the error report.ReportPerMin
- A cap on the number of reports that can be sent per minute. IfReportPerMin
is equal to zero then there is no cap.
BacktraceData <a name="architecture-BacktraceData"></a>
BacktraceData
is a serializable class that holds the data to create a diagnostic JSON to be sent to the Backtrace endpoint via BacktraceApi
. You can add additional pre-processors for BacktraceData
by attaching an event handler to the BacktraceClient.BeforeSend
event. BacktraceData
require BacktraceReport
and BacktraceClient
client attributes.
BacktraceApi <a name="architecture-BacktraceApi"></a>
BacktraceApi
is a class that sends diagnostic JSON to the Backtrace endpoint. BacktraceApi
is instantiated when the BacktraceClient
constructor is called. You use the following event handlers in BacktraceApi
to customize how you want to handle JSON data:
RequestHandler
- attach an event handler to this event to override the defaultBacktraceApi.Send
method. ARequestHandler
handler requires 3 parameters -uri
,header
andformdata
bytes. DefaultSend
method won't execute when aRequestHandler
handler is attached.OnServerError
- attach an event handler to be invoked when the server returns with a400 bad request
,401 unauthorized
or other HTTP error codes.OnServerResponse
- attach an event handler to be invoked when the server returns with a valid response.
BacktraceApi
can send synchronous and asynchronous reports to the Backtrace endpoint. To enable asynchronous report (default is synchronous) you have to set AsynchronousRequest
property to true
.
BacktraceResult <a name="architecture-BacktraceResult"></a>
BacktraceResult
is a class that holds response and result from a Send
or SendAsync
call. The class contains a Status
property that indicates whether the call was completed (OK
), the call returned with an error (ServerError
), the call was aborted because client reporting limit was reached (LimitReached
), or the call wasn't needed because developer use UnpackAggregateException
property with empty AggregateException
object (Empty
). Additionally, the class has a Message
property that contains details about the status. Note that the Send
call may produce an error report on an inner exception, in this case you can find an additional BacktraceResult
object in the InnerExceptionResult
property.
BacktraceDatabase <a name="architecture-BacktraceDatabase"></a>
BacktraceDatabase
is a class that stores error report data in your local hard drive. If DatabaseSettings
dones't contain a valid DatabasePath
then BacktraceDatabase
won't generate minidump files and store error report data.
BacktraceDatabase
stores error reports that were not sent successfully due to network outage or server unavailability. BacktraceDatabase
periodically tries to resend reports
cached in the database. In BacktraceDatabaseSettings
you can set the maximum number of entries (MaxRecordCount
) to be stored in the database. The database will retry sending
stored reports every RetryInterval
seconds up to RetryLimit
times, both customizable in the BacktraceDatabaseSettings
.
BacktraceDatabaseSettings
has the following properties:
DatabasePath
- the local directory path whereBacktraceDatabase
stores error report data when reports fail to sendMaxRecordCount
- Maximum number of stored reports in Database. If value is equal to0
, then there is no limit.MaxDatabaseSize
- Maximum database size in MB. If value is equal to0
, there is no limit.AutoSendMode
- if the value istrue
,BacktraceDatabase
will automatically try to resend stored reports. Default isfalse
.RetryBehavior
- -RetryBehavior.ByInterval
- Default.BacktraceDatabase
will try to resend the reports every time interval specified byRetryInterval
. -RetryBehavior.NoRetry
- Will not attempt to resend reportsRetryInterval
- the time interval between retries, in seconds.RetryLimit
- the maximum number of timesBacktraceDatabase
will attempt to resend error report before removing it from the database.
If you want to clear your database or remove all reports after send method you can use Clear
, Flush
and FlushAsync
methods.
ReportWatcher <a name="architecture-ReportWatcher"></a>
ReportWatcher
is a class that validate send requests to the Backtrace endpoint. If reportPerMin
is set in the BacktraceClient
constructor call, ReportWatcher
will drop error reports that go over the limit. BacktraceClient
check rate limit before BacktraceApi
generate diagnostic json.
Good to know <a name="good-to-know"></a>
Xamarin
You can use this Backtrace library with Xamarin if you change your HttpClient
Implementation to Android
. To change HttpClient
settings, navigate to Android Options
under Project Settings
and click on Advanced
button.
Release Notes <a name="changelog"></a>
See release notes here.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net35 is compatible. net40 was computed. net403 was computed. net45 is compatible. net451 was computed. net452 was computed. net46 was computed. net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETFramework 3.5
- Newtonsoft.Json (>= 13.0.3)
-
.NETFramework 4.5
- Microsoft.Diagnostics.Runtime (>= 0.9.170809.3)
- Newtonsoft.Json (>= 13.0.3)
-
.NETStandard 2.0
- Newtonsoft.Json (>= 13.0.3)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
2.1.10 | 3,221 | 7/3/2024 |
2.1.10-alpha1 | 77 | 7/3/2024 |
2.1.10-alpha | 79 | 7/3/2024 |
2.1.9 | 72,427 | 6/8/2020 |
2.1.8 | 995 | 3/26/2020 |
2.1.7 | 20,014 | 3/2/2020 |
2.1.6 | 751 | 10/11/2019 |
2.1.5 | 551 | 10/4/2019 |
2.1.4 | 832 | 8/2/2019 |
2.1.3 | 872 | 6/13/2019 |
2.1.2 | 872 | 6/7/2019 |
2.1.1 | 1,253 | 3/18/2019 |
2.1.0 | 860 | 3/12/2019 |
2.0.7 | 1,039 | 2/14/2019 |
2.0.6 | 1,300 | 12/19/2018 |
2.0.5 | 1,007 | 12/14/2018 |
2.0.4 | 1,233 | 9/24/2018 |
2.0.3 | 1,191 | 9/4/2018 |
2.0.2 | 1,043 | 8/28/2018 |
2.0.1 | 1,330 | 7/17/2018 |
2.0.0 | 1,214 | 7/10/2018 |
1.3.2 | 1,309 | 7/3/2018 |
1.3.1 | 1,320 | 6/28/2018 |
1.3.0 | 1,324 | 6/26/2018 |
1.2.3 | 1,373 | 6/21/2018 |
1.2.2 | 1,442 | 6/19/2018 |
1.2.1 | 1,310 | 6/14/2018 |
1.2.0 | 1,452 | 5/5/2018 |
1.1.4 | 1,231 | 4/27/2018 |
1.1.2 | 1,228 | 4/9/2018 |
1.1.1 | 1,279 | 4/9/2018 |
1.1.0 | 1,349 | 4/2/2018 |
1.0.3 | 1,327 | 3/20/2018 |