1. Home
  2. Product Guides
  3. APM
  4. Agent installation
  5. Linux

Linux

The prefered method to install and configure the agent is using our one touch script.

The Raygun Agent can be run as a Docker container see Docker instructions for more information.

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.

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.

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

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

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]

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.

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

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:

  • 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 (/var/raygun/agent if installed using the one-touch script)

  • 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"
  }
}

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.

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
  • For .NET Core under IIS - in process or out of process hosting type

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:

Split traces

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:

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

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

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.

On this page: