Getting Started

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

• Windows Agent Install Overview

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.

• Linux Agent Install Overview

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

• App Services
• Cloud Services

AWS Deployment Scenarios

• Elastic Beanstalk
• ECS
• Fargate

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

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.

1. Open environment from the command-line

   sudo nano /etc/environment
   

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

• log4net
• NLog
• Serilog
• Stackify API

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.