1. Home
  2. Product Guides
  3. APM
  4. Profiler Setup
  5. .NET on Linux

.NET on Linux

Install the Raygun APM Agent for Linux before configuring an application.

The Linux installer does not change applications or store API keys. Configure each .NET application with its own Raygun application API key before the CLR starts.

The application must receive the following values before .NET starts. Replace the API-key placeholder with the key shown on the APM setup page for the Raygun application that will receive these traces.

All Linux architectures use:

PROTON_API_KEY=YOUR_RAYGUN_APPLICATION_API_KEY
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER='{e2338988-38cc-48cd-a6b6-b441c31f34f1}'
CORECLR_PROFILER_PATH=/opt/raygun/agent/current/Profiler/RaygunProfiler.so
DOTNET_STARTUP_HOOKS=/opt/raygun/agent/current/StartupHook/Raygun.Apm.StartupHook.dll
PROTON_NETWORK_MODE=Udp

The managed startup hook supplies automatic ASP.NET Core request identity across async execution. It does not require Raygun middleware, an application package, or source-code changes. If the application already uses startup hooks, append the Raygun path with the Linux path-list separator (:) instead of replacing the existing entries.

On AMD64, also set:

CORECLR_PROFILER_PATH_64=/opt/raygun/agent/current/Profiler/RaygunProfiler.so

On ARM64, set this value instead:

CORECLR_PROFILER_PATH_ARM64=/opt/raygun/agent/current/Profiler/RaygunProfiler.so

Do not use a version-specific profiler path. The current selector is changed atomically during an Agent upgrade.

Use a root-owned environment file so the API key is not placed in a world-readable service unit.

  1. Create the environment file:
sudo install -d -o root -g root -m 0755 /etc/raygun
sudoedit /etc/raygun/my-api.env
  1. For an AMD64 application, add:
PROTON_API_KEY=YOUR_RAYGUN_APPLICATION_API_KEY
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={e2338988-38cc-48cd-a6b6-b441c31f34f1}
CORECLR_PROFILER_PATH=/opt/raygun/agent/current/Profiler/RaygunProfiler.so
CORECLR_PROFILER_PATH_64=/opt/raygun/agent/current/Profiler/RaygunProfiler.so
DOTNET_STARTUP_HOOKS=/opt/raygun/agent/current/StartupHook/Raygun.Apm.StartupHook.dll
PROTON_NETWORK_MODE=Udp

For ARM64, replace CORECLR_PROFILER_PATH_64 with:

CORECLR_PROFILER_PATH_ARM64=/opt/raygun/agent/current/Profiler/RaygunProfiler.so
  1. Restrict the file to root:
sudo chown root:root /etc/raygun/my-api.env
sudo chmod 600 /etc/raygun/my-api.env
  1. Create a drop-in for the existing application service. Replace my-api.service with its real unit name:
sudo systemctl edit my-api.service

Add:

[Unit]
After=raygunagent.service

[Service]
EnvironmentFile=/etc/raygun/my-api.env
  1. Reload systemd and restart only the application:
sudo systemctl daemon-reload
sudo systemctl restart my-api.service

Restarting the application is required. CoreCLR discovers the native profiler and managed startup hook only while the process starts.

The Agent installer does not edit the application unit because one host can run applications with different Raygun API keys. Keep PROTON_API_KEY out of /etc/raygun/agent.env; that file configures the Agent service, not profiled applications.

For Docker, Kubernetes, a shell script, or another process manager, add the same variables to the application process environment. Do not give the profiler variables to the RaygunAgent process. Start the Agent with profiling disabled if it is launched manually:

sudo env CORECLR_ENABLE_PROFILING=0 COR_ENABLE_PROFILING=0 \
  /opt/raygun/agent/current/RaygunAgent agent --console false

Confirm the stable selector contains both components:

test -f /opt/raygun/agent/current/Profiler/RaygunProfiler.so
test -f /opt/raygun/agent/current/StartupHook/Raygun.Apm.StartupHook.dll

Confirm the service received the non-secret profiler settings:

sudo systemctl show my-api.service \
  --property=EnvironmentFiles --property=MainPID

For ASP.NET Core, confirm the application environment includes DOTNET_STARTUP_HOOKS, then generate traffic through real application endpoints and confirm traces appear in Raygun. Do not rely only on a load-balancer health check.

If traces do not appear, follow Linux troubleshooting.

On this page: