.NET

System Requirements

Raygun APM offers support for ASP.NET, ASP.NET Web Forms, ASP.NET WebAPI, ASP.NET Core

  • .NET 4.5 installed (Windows Server 2008 or above)
  • 2 GHz or faster multi-core processor
  • 1 GB of RAM
  • 2 GB available hard disk space
  • 64-Bit Windows


Installing the Agent

STEP 1 - Read APM Deploy Best Practices

If you haven’t already, read about APM Deploy Best Practices


STEP 2 - Download the installer

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


STEP 3 - Install the agent

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


STEP 4 - Input your API key

Launch the Raygun Profiler Configuration. 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 set the Default API key and then Register the Agent.


STEP 5 - Attach to an IIS application pool

Select the application pool using the dropdown and Register.

Change the API key if you would like the data to be associated with a different application, then recycle the application pool to start profiling.


STEP 6 - Update to the latest version of Raygun4Net

In your server side Visual Studio project(s) for this application, we recommended you update the Raygun4Net NuGet package to the latest release in order to correlate data between Crash Reporting and APM.

You can do this by right clicking on the project, or by using the NuGet package manager console. Update the Raygun4Net package you have installed to the latest version.


Integrating with Raygun4Net

By adding Raygun4Net to your ASP.NET application or Raygun4Net.Mvc to your ASP.NET MVC application Raygun APM unlocks advanced features and intelligence that helps to reduce the CPU overhead of the profiler.

If you’re already using one of these packages in your web application and have the Raygun HTTP module registered in your web.config file then there may be nothing more you need to do other than make sure you’re using version 5.10.0 or above.

To ensure everything connects correctly you’ll need to make sure that your IIS application pool name matches your IIS website name. If they match then Raygun APM and Raygun4Net will be able to connect automatically and there is nothing else you need to do. If they don’t match then you’ll need to let Raygun4Net know what the application pool name is like this:

<RaygunSettings apikey="YOUR_APP_API_KEY" applicationIdentifier="IIS_APP_POOL_NAME" />

If you’re not using the Raygun HTTP module then you can initialize the integration manually by adding a single line of code to your HttpApplication implementation in the Global.asax.cs file.

using Mindscape.Raygun4Net;

public class MvcApplication : System.Web.HttpApplication
{
    public override void Init()
    {
        base.Init();
        
        // You only need to set the applicationIdentifier parameter if your 
        // IIS application pool name does not match your IIS website name.
        APM.Initialize(this, "IIS_APP_POOL_NAME");
    }
}

Deregistering an application pool

If an application is no longer being served from a particular application pool or you no longer want a particular application to be monitored, you can deregister that application’s application pool in the configuration utility.

1. Go to the IIS tab of the Raygun Configuration Utility.

2. Select the registered application pool which you would like to de-register

3. Click the Deregister button

4. Click Yes on the dialog to recycle the application pool


Deregistering the agent

If you want to disable monitoring of all the applications on a server, you can deregister the agent using the configuration utility.

1. Go to the Agent tab in the Raygun Configuration Utility

2. Click the Deregister button

3. Once the agent has successfully deregistered, the status in the bottom left will have updated:

For more information on how to get the most out of Raygun APM, check out our [getting started guide][19] or view our docs on the [APM overview page][20].


Troubleshooting

Experiencing high CPU

When restarting the app pool 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” application and switch 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.

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.


Check that the profiler is successfully attaching

Check that the profiler is successfully attaching to your application by checking the Event log. Look for an entry that mentions CLSID e2338988-38cc-48cd-a6b6-b441c31f34f1. If it is attaching correctly there will be a log entry saying:

.NET Runtime version 4.0.30319.0 - The profiler was loaded successfully.  Profiler CLSID: '{e2338988-38cc-48cd-a6b6-b441c31f34f1}'.  Process ID (decimal): xxxx.  Message ID: [0x2507].
If this message is in the event log but with a different CLSID then this indicates another profiler is currently profiling your application and preventing Raygun APM from being able to profile. Check there are no other profilers installed and still configured.


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 “Raygun Profiler Configuration” tool or 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  -type IIS -apikey  -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