.NET Core

System Requirements

  • ASP.NET Core 1.x or 2.x running on Windows
  • Support for ASP.NET Core 3.x and Linux coming soon

Installing the Agent

STEP 1 - Download the installer

Download the Raygun Agent on the server you would like to monitor

STEP 2 - Install the agent

Open the agent installer you downloaded and follow the on-screen prompts to install the agent

STEP 3 - Input your API key

Launch the Raygun Profiler Configuration tool. You’ll need an API key to register the agent. Create a new application in Raygun if you have not already, and navigate to the APM set up screen to find your API key.

Under the Agent tab of the configuration tool, set the Default API key and then Register the Agent.

STEP 4 - Attach to a .NET Core process

Open the .NET Core tab in the Raygun Profiler Configuration tool.

If your .NET Core application is running then you can select it from the process list.

If your process is not listed then find the path to your process dll or exe and enter it into the assembly name field.

With your .NET Core process selected, click the Register button, then enter your Raygun application API Key into the dialog and click Save.

STEP 5 - Register the profiler

There are many ways in which a .NET Core application can be started, so we’ve listed some common methods along with the required environment variables needed to configure the Raygun APM profiler correctly. To view these options, click the Show Config button from the configuration screen:

Select the appropriate option from that list, and set your environment variables. Now everything is configured. Make a few requests to your application and traces should appear within Raygun after a couple of minutes. If they don’t appear, try running status checks and running a profiler test below.

By adding Raygun4Net.AspNetCore to your application Raygun APM unlocks advanced features and intelligence that helps to reduce the CPU overhead of the profiler.

If you’re already using Raygun4Net.AspNetCore in your web application then we recommend you update the Raygun4Net.AspNetCore NuGet package to the latest release in order to correlate data between Crash Reporting and APM.

For the full instructions on installing and configuring Raygun4Net.AspNetCore, please refer to the Installation instructions for Crash Reporting.

Installing using the Raygun CLI tool

Another method for registering and profiling a .NET Core application is to use the Raygun CLI tool

1. Register your .NET Core process with the Raygun application API Key using the following command.

# Configure HelloWorldApp.dll with an API Key
rgc.exe -enable HelloWorldApp.dll -type dotnetcore -apikey xxx -startup 30 -norecycle

2. To start the process and automatically configure the correct environment variables you can bootstrap the execution of your .NET Core process using the following command.

# Start HelloWorldApp.dll process with profiler environment configured
rgc.exe -profile "%ProgramFiles%\dotnet\dotnet.exe" -arguments HelloWorldApp.dll -coreclr -apikey <APP-API-KEY> -startup 60

Deregistering an application

1. To stop profiling a .NET Core application you’ll first need to remove the environment variables that were configured when your application starts. Once these have been removed, restart your application to stop profiling.

2. The final step is to remove the API Key configuration by going to the .NET Core tab in the Raygun Profiler Configuration tool. Select the configured process and click the Deregister button.


Experiencing high CPU

When restarting the application there is an overhead that could cause the CPU to spike, but this high usage shouldn’t persist. APM products will always have an overhead, but our goal is to ensure it’s the lowest overhead possible. The high CPU usage you’re experiencing is likely caused by a high method call count. We recommend setting up a blacklist for a selection of high count method calls and seeing if this improves the CPU usage.

If this issue persists, please reach out to our engineering support team via the contact page, or click contact us in the app.

Run status checks

Run some basic status checks by loading the Raygun Profiler Configuration tool and switching to the “Help” tab. The basic status checks will automatically run and will display a traffic light for each check. Ensure that all status checks are showing green.

Alternatively you can run these same status checks using the CLI tool.

Running rgc.exe -status will produce a result that should look similar to this:

Running Raygun Agent status checks…
Agent status: Registered
Agent test: Connected to the Raygun Agent v1.0.*.0 on port 2790.
API test: Connected to the Raygun API at https://api2.raygun.com.
API key test: API key *** is valid
Profiler x86 test: 32-bit Profiler found at D:\home\Raygun\Profiler\1.0.*\x86\RaygunProfiler.dll.
Profiler x64 test: 64-bit Profiler found at D:\home\Raygun\Profiler\1.0.*\x64\RaygunProfiler.dll.

Troubleshooting failed status checks

If any traffic lights are red, you will receive a message describing the problem. Here are some things you can try in order to resolve these problems:

  • Check that the Raygun Agent is running. It should be running as a service on your machine called “Raygun Agent”. If the application you are profiling is on a separate machine from the agent, check that traffic is allowed on port 2790.
  • Check that the machine running the Raygun Agent can access the Raygun API at https://api2.raygun.com/healthcheck, either using your browser or the cURL command. If you’re using a browser, look for a 200 response in the network tab of the browser’s developer tools.
  • Check that your firewall is not blocking Raygun.
  • Check that the API key is correct. If you have not sent any traces yet, your API key is displayed at the top of the instructions page for your new application. Otherwise, you can find the key under “Application settings” in the menu on the Raygun dashboard. Ensure that this is the same key that you used when you registered your process in the Raygun Profiler Configuration tool. You can verify this by selecting your process and clicking “Edit”:

Run a profiler test

The Raygun Profiler Configuration tool has a function to run a test that will validate that a local test application can be executed and profiled. When this test is run the CLI tool is run in test mode and profiled. If the test is successful then a single trace will be sent to your Raygun application with a name of “Mindscape.Raygun.Agent.Cli.Program.Main”.

To run this test, open the Raygun Profiler Configuration tool, click on the “Help” tab and click on the “Run a profiler test” button.

Enabling detailed logging

The log files for the Raygun Agent are located under %ProgramData%\Raygun\AgentLogs\ on Windows.

To enable detailed logging for the Raygun Agent, simply add a configuration setting to %ProgramFiles(x86)%\Raygun\RaygunAgent\RaygunAgent.exe.config. Add a new element to the <appSettings> section like <add key="LogLevel" value="Verbose"/> (other options are Warning, Info, Verbose, Debug).

Save the configuration file changes and restart the “Raygun Agent” Windows service, e.g. sc stop RaygunAgent followed by sc start RaygunAgent.

Run a diagnostic session

Before running a diagnostic session you should enable debug mode for your application using the CLI. We also recommend that you deregister all applications other than the one you’re wanting to capture the diagnostic information for.

Running a diagnostics session will capture the following information and will help Raygun support to troubleshoot issues you’re having:

  • Snapshot of log files
  • Snapshot of agent settings and blacklist files
  • Agent log files with Log level of Debug automatically set
  • Trace package and source files generated during the session
  • A trace of data being sent from the profiler to the agent
  • Profiler log messages (only captured if debug mode is enabled)

Register an app with debug mode enabled

rgc.exe -enable <raygun.com.apppool> -type IIS -apikey <APP-API-KEY> -startup 0 -debugmode

Start a diagnostics session that is uploaded to Raygun when complete

rgc.exe -auto-diagnostic 300

For more information on diagnostic command options, see the CLI documentation.

After you have run and uploaded a diagnostic session, please add the diagnostic session identifier to your Raygun Support case.

Still need help?

We are always happy to help with any questions you might have. If we can’t answer your technical enquiries through the documentation, please feel free to get in touch through our contact page.

Contact Us