Azure App Service

App Service Plan Requirements

  • Minimum 200 total ACU App Service plan such as the S2 or P1V2 pricing tiers
  • Support for an AlwaysOn App Service and Continuous running WebJob is needed to run the Raygun Agent successfully
  • A minimum of 2GB of free storage is needed so the F1 and D1 App Service plans cannot be used.

Read the general .NET setup instructions for more information on supported frameworks.

note: For the Raygun Agent to profile successfully you must ensure:

  • The Application Insights extension is disabled
  • Your App Service plan supports the Always on option
  • The MySQL In App feature is off
  • The API CORS feature is not configured (please enabled CORS through your web.config or another means)
  • There is a minimum of 2GB of free storage


Installing the Raygun Agent

The Raygun Agent is installed into an Azure App Service using the extensions functionality. Extensions can be managed in two places, either in the Azure Portal or the Kudu site for your App Service.


STEP 1 - Prerequisites

Please read the full Azure App Service prerequisites above and ensure you have these requirements in place before installing the Raygun APM agent.

The Raygun Agent is installed into an Azure App Service using the extensions functionality. Extensions can be managed in two places, either in the Azure Portal or the Kudu site for your App Service.


STEP 2 - Initial set up and API key

Navigate to https://portal.azure.com.

Within the portal, locate your App Service and find the Application Settings menu option (found under the Settings sub heading).

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.

Add a new application setting with the name Raygun_ApiKey and value set to your API key.

Make sure you save the changes to the application settings.


STEP 3 - Ensure Always On is set

Modify the Always On option to On.


STEP 4 - Install the agent

Navigate to the Extensions menu option (found under the Development tools sub heading) and click the Add button.

Select the .NET Raygun APM option from the list of extensions. Then click OK to accept the legal terms and OK again to start installing the extension.


STEP 5 - Restart

The Raygun Agent is now installed, but you will need to restart your Azure App Service to start the profiling of your application.


Integrating with Raygun4Net

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

If your application has been developed with .NET Core then please refer to integrating with Raygun4Net for .NET Core. Otherwise refer to integrating with Raygun4Net for ASP.NET and ASP.NET MVC.


Updating the Raygun Agent

The Raygun Agent for Azure App Services will automatically check for updates each time the RaygunAPM WebJob is started. If an updated version is found it will download the update packages first then start.

To force it to check for updates, stop and start the RaygunAPM WebJob. If an update was found, then it is recommended that the App Service should also be restarted.


Uninstalling the Raygun Agent

To uninstall the Raygun Agent, simple remove the Azure App Service extension and restart your App Service.

1. Navigate to the Extensions menu option (found under the Development tools sub heading) and select the .NET Raygun APM extension from the list.

2. Click the Delete button and confirm that you want to delete the extension.

3. Confirm that the WebJob has been removed and restart your App Service.

4. Optionally if you don’t plan on installing the extension again you can remove all files stored in the D:\home\Raygun location. If you plan to install the extension again at a later date then we recommend leaving these files in place.


Troubleshooting

Experiencing high CPU

When restarting the App Service 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.


Disable MySQL in app feature

Ensure the Azure App service feature “MySQL In App” is disabled. This App Service feature is incompatible and will prevent the Raygun APM profiler from being able to profile your App Service.


Disable the API “CORS” feature

Ensure the Azure App service API “CORS” feature is not configured. This App Service feature is incompatible and will prevent the Raygun APM profiler from being able to profile your App Service.


Disable “Application Insights” site extension

Ensure the “Application Insights” site extension is disabled. If Application Insights is enabled then it installs a profiler that overrides the configuration of the Raygun APM profiler.


Run status checks

Run some basic status checks by triggering the “RaygunAPM-Diagnostics” WebJob that should exist in your App service. If you could then view the log of the completed job trigger and ensure that all checks pass. The result should look similar to this:

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

Check you have the correct environment variables configured

Check the App service w3wp.exe process has the correct environment variables configured that enable the Raygun profiler. If you can log into your SCM site (Kudu) and navigate to the process explorer. Click the properties button next to the process for your application (not the scm site).

Process Explorer

This will open the properties dialog, click the environment variables tab and check that the following exist:

w3wp-exe


Check that the profiler is successfully attaching

Check that the profiler is successfully attaching to your application by checking the Event log. If you can open the file at D:\home\LogFiles\eventlog.xml (you can use either Debug console in Kudu to navigate to the file and download it or edit in the browser to view it). 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 the App Service and preventing Raygun APM from being able to profile.

Check there are no other profiler extensions installed such as Application Insights.


Restarting the Raygun Agent

The Raygun Agent runs as a continuous WebJob inside the Kudu management site. You can see the process listed in the process list of Kudu by going to https://<your-app-name>.scm.azurewebsites.net/ProcessExplorer/

Raygun Agent shown in the Kudu process list

To restart the Raygun Agent simply stop and start the RaygunAPM continuous WebJob.


Log files

The Raygun Agent logs are located under the home location for your App Service, under LogFiles\Raygun\AgentLogs. You can download the log files through an ftp client to your App Service or by using one of the debug consoles in Kudu.

For example, navigate to https://<your-app-name>.scm.azurewebsites.net/DebugConsole/?shell=powershell and enter cd D:\home\LogFiles\Raygun\AgentLogs to change directory to the logs folder. You can then download the log files through the console or click the edit icon to view the file on-screen.

All other Raygun Agent and Profiler files are installed into D:\home\Raygun. Please do not modify these files without direction from Raygun support.


Enabling detailed logging

To enable detailed logging for the Raygun Agent, simply add a configuration setting to your App Service. Add a new setting with name Raygun_LogLevel and a value of Verbose (other options are Warning, Info, Verbose, Debug).

Save the configuration change to apply which should automatically restart the RaygunAPM WebJob.