Linux
Docker
The Raygun Agent can be run as a Docker container see Docker instructions for more information.
Installing using systemd
Follow these steps to install the Raygun Agent on a Linux x64 machine running under systemd. The Raygun Agent is built as a self-contained .NET Core application but the .NET Core runtime doesn't need to be installed on the target machine.
1. Install dependencies
Ensure you have the dependencies needed to run the commands below.
sudo apt-get -y install unzip wget
Depending on your Linux distribution, please also install the .NET Core 3.0 dependencies.
2. Download and extract the agent
Create a directory to install the Raygun Agent to. If you install the Raygun Agent to a different directory then also update the raygunagent.service
file with the same directory.
Then download the Raygun Agent zip file to that directory and give execute permission to the Agent and CLI executables.
sudo mkdir /opt/raygun
sudo wget https://downloads.raygun.com/APM/latest/RaygunAgent-netcore-linux.zip
sudo unzip -d /opt/raygun/agent -o RaygunAgent-netcore-linux.zip
sudo rm RaygunAgent-netcore-linux.zip
sudo chmod +x /opt/raygun/agent/RaygunAgent
sudo chmod +x /opt/raygun/agent/rgc
3. Install the systemd service
Copy the raygunagent.service configuration file to the systemd directory and reload the daemon to pick up the new service.
sudo mv /opt/raygun/agent/raygunagent.service /etc/systemd/system/
sudo systemctl daemon-reload
4. Start the service and register your agent
The final step is to start the new service and issue the command to register the agent with your API key.
sudo systemctl start raygunagent
sudo /opt/raygun/agent/rgc -register [YOUR-API-KEY]
Profiling .NET applications
note: This is currently offered via a beta build of Raygun APM - you can download this build from the downloads page
To profile .NET applications you must set the following environment variables prior to execution
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER='{e2338988-38cc-48cd-a6b6-b441c31f34f1}'
CORECLR_PROFILER_PATH=/opt/raygun/agent/RaygunProfiler.so
Note: The profiler path assumes the agent has been installed to /opt/raygun/agent, change this as required if you install to a different location.
Troubleshooting
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 code filtering 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.
No traces in the Raygun UI
What if everything is set up, but there are no traces in the Raygun UI? Try following the steps below to resolve common issues with receiving traces.
Run status checks
Run some basic status checks by using the CLI tool.
Running ./rgc -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 ...
Profiler x64 test: 64-bit Profiler found at ...
Troubleshooting failed status checks
If any checks fail you will receive a message describing the problem. Here are some things you can try in order to resolve these problems:
- Depending on your installation, list the running services or processes to check that the agent is running.
- 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 installed the agent.
If you are still not receiving traces, you will need to send us diagnostic session as described below:
Enabling detailed logging
-
The log files for the Raygun Agent are located under
/usr/share/Raygun/AgentLogs/
. -
To enable detailed logging for the Raygun Agent, add a configuration setting to the
appsettings.json
file in the directory where you installed the agent. -
It should look like the following: (other loglevel options are Warning, Info, Verbose, Debug).
{
"Logging": {
"LogLevel": {
"Default": "Debug",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"Agent": {
"LogLevel": "Debug"
}
}
Run a diagnostic session
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
- 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
Start a diagnostics session that is uploaded to Raygun when complete
rgc -auto-diagnostic 300
For more information on diagnostic command options, see the CLI documentation.
Information about your environment
To be able to help you faster, we will need to know:
- The diagnostic session identifier
- Hosting type - cloud, on premise, Azure App Service etc
- OS Version, 32 or 64 bit
- Web Server (i.e. IIS or Node) version
- Framework type (i.e. .NET Core or Rails)
- Framework version
Split traces
Under high load, partially formed traces may appear in the UI. They are named after a method and have no HTTP information associated with them. An example is shown below:
This happens because of UDP packet drop between the application being profiled and the Raygun Agent. If you see the split traces there are a couple of options to try to prevent them from appearing:
Solution 1: use memory mapped file transmission mode
In this mode the application and Raygun Agent use files to communicate to each other. It is less CPU intensive than UDP and has better delivery guarantees. For it to work, the Agent and the profiled application need to share a drive where files will be placed.
Before you start, choose a path where the files will be stored, for example /usr/share/raygun/commandstream
.
Configuring your application
For your application, set the following environment variables
PROTON_NETWORK_MODE=File
PROTON_FILE_IPC_FOLDER=<path_to_communication_folder>
Configuring Raygun Agent
When running the Agent, ensure it has the following environment variable set:
Raygun_NetworkTransmissionMode=File
Solution 2: increase UDP buffers
If your application is hosted on Linux and you have full control over the environment, tuning system UDP buffer sizes can help to resolve the problem. We recommend setting the receive buffer to 5MB:
sudo sysctl -w net.core.rmem_max=5242880
sudo sysctl -w net.core.rmem_default=5242880
Solution 3: use Sampling to filter out those traces
If you see that split traces mostly have the same names, it is possible to use Sampling to remove them by setting big sampling interval for those traces to be 1 trace per 300 hours or similar.