- 3 Minutes to read
- Print
- DarkLight
- PDF
Getting Started
- 3 Minutes to read
- Print
- DarkLight
- PDF
Retrace offers many basic and advanced features. In this article we will try to outline all of the amazing things that Retrace can do for your .NET applications.
Step 1. Install Retrace Agent
The first thing you need to do is install the Retrace monitoring agent on your server. The installation directions vary depending on if you are using Windows, Linux, Azure App Services, Elastic Beanstalk, and other scenarios.
Basic Installations
By default Retrace will instrument all IIS applications once the agent is installed. Please review our .NET APM on Windows guide to learn more. With a little configuration you can also enable Windows Services and define custom transactions.
To enable the .NET profiler on Linux you must set environment variables and create a Stackify.json
file in the application folder you want to profile. Please see our guide for .NET APM on Linux to learn more.
Container Based Installations
- Docker (Linux)
- Kubernetes
Azure Deployment Scenarios
AWS Deployment Scenarios
Note: Retrace is not designed for Windows 10 desktop usage. We would recommend trying Prefix instead.
Step 2. Configure Your App
To ensure that Retrace will automatically profile your application and to give it a proper application and environment name, you should create a Stackify.json
file in the root of your application deployment folder.
{
"AppName": "MyApp",
"Environment": "Production"
}
Note: For non web applications, you must manually instrument your code to define transactions for Windows Services and other forms of .NET background services.
Linux Environment Variables
Setting the environment variables should only be required on Linux systems. In Windows these values are set by the agent automatically.
The .NET CLR requires environment variables to be set in order to load a profiler into a process. There are several ways to set these environment variables. Here is an example that only needs to be set once and will be available to each new process that loads without any additional steps.
- Open
environment
from the command-linesudo nano /etc/environment
- Add the environment variables
CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-b283c03916da} CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER_PATH=/usr/local/stackify/stackify-dotnet-apm/StackifyProfiler.so
If you are running your .NET Core application within systemd, you will need to modify conf file for your job.
[Service]
Environment=CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-b283c03916da}
Environment=CORECLR_ENABLE_PROFILING=1
Environment=CORECLR_PROFILER_PATH=/usr/local/stackify/stackify-dotnet-apm/StackifyProfiler.so
Step 3. Send Your Logs to Retrace
You can send your applications logs to Retrace with multiple .NET logging frameworks. Be sure to send your logs to take full advantage of Retrace's error tracking and centralized logging features. Errors are also used as part of Retrace's "App Scoring" feature.
Step 4. Deployment Tracking
Notify Retrace when you do a new deployment to get advanced reporting features. This makes it easy to see how performance changes after a new deployment. Popular tools like Team City, Visual Studio Team Services, Octopus Deploy and others are supported. View our docs to learn more.
Sending All Exceptions to Retrace
By default the new .NET profiler only captures "unhandled" exceptions to avoid the overhead of a first-chance exception handler. However, if you want to capture and upload all first-chance exceptions you can enble this on a per application basis. To enable this, add the setting CaptureAllExceptions
to the Stackify.json
file as shown in the following example.
{
"AppName": "MyApp",
"Environment": "Production",
"CaptureAllExceptions": true
}
Disabling Tracing
If you want to temporarily disable collection of APM data, you can add a property to the Stackify.json
file to cause the profiler to be disabled. This does not impact collection of logs that are sent to Retrace.
This is useful to disable profiling of some applications on your server but not all.
{
"AppName": "MyApp",
"Environment": "Production",
"DisableTracing": true
}
Additional Topics
- Custom Metrics - Track custom metrics in your code with the Stackify API.
- Custom Instrumentation - Customize what Retrace profiles and the data it collects.