Setting up .NET tracing on Linux or Alpine Linux

Edit online

You can set up .NET tracing on Linux by using Instana AutoTrace or by manually configuring the environment variables. On .NET Core sensor 1.0.56 and later, .NET Tracer supports host auto tracing on Linux systems except containers.

For details about the working of .NET monitoring, see How .NET monitoring works.

Running .NET applications on Linux

Edit online

If you are not familiar with deploying .NET applications on Linux, follow these steps to set up and run your application.

Step 1: Install .NET SDK

Edit online

Depending on your requirements, you can install the .NET SDK in one of the following environments:

  • WSL (Windows Subsystem for Linux): For development and debugging
  • Linux machine: For production environments

To install .NET SDK 8.0 on Ubuntu 22.04, run the following command:

wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install -y dotnet-sdk-8.0

Step 2: Run the .NET application

Edit online

You can run your .NET application by using one of the following methods:

  • Direct run:

    dotnet run --project /home/username/Applications/WebAPI.Linux/WebAPI.Linux.csproj

  • Run with Kestrel: Go to the Publish folder and run the DLL:

    cd /home/username/Publish/WebAPI.Linux
dotnet WebAPI.Linux.dll

Enabling .NET tracing

Edit online

Enable .NET tracing on Linux by using one of the following methods:

Method 1: Enabling auto-tracing

Edit online

With Instana AutoTrace, Instana automatically detects and instruments your .NET application. You don't need to change any code.

To enable Instana AutoTrace, complete the following steps:

  1. After you install the host agent, start the agent.
  2. Start your .NET application.

During the discovery startup, the sensor automatically enables the tracing. You don't need to manually inject the NuGet package and compile the application.

During the discovery process, the instana_dotnet_global_env.sh file is created. This file contains the environment variables that are required for .NET Core tracing.

To verify whether tracing is working, log in to your Instana dashboard. You can see traces appearing.

Method 2: Enabling tracing manually

Edit online

Use this method if you don't want to use auto-tracing or if you need more control over the setup. This approach involves adding NuGet packages to your application.

Tracing applications running on Linux (except Alpine Linux)

Edit online

To enable tracing manually in a .NET Core application running on Linux, complete the following steps:

  1. After you install the host agent, install the following packages in your application:

    When the packages are distributed through NuGet.org, you can install them without recompiling the application. Use one of the following methods:

    • nuget.exe available: Restore the packages by using nuget.exe without compiling the project that is to be instrumented.
    • nuget.exe unavailable: Download the packages directly, extract them, and then set the environment variables to point to the extracted files as described in the following step.
    Note: Select the appropriate rewriter package based on your system architecture. You can add the Instana.Tracing.Core.Rewriter.Linux package to your project or add it before publishing.

  2. Set the following environment variables in the Web.config file of your application before you start your process:

    DOTNET_STARTUP_HOOKS=[path-to-your-app]/Instana.Tracing.Core.dll
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-b283c03916dd}
CORECLR_PROFILER_PATH=[Path_to_your_app]/instana_tracing/CoreProfiler.so

    Replace [path-to-your-app] with the actual path to your application directory.

  3. If your application is running inside a container, define the agent environment variables so that the .NET Tracer knows where to look for the agent and send spans at runtime:

    INSTANA_AGENT_HOST=[address_where_the_agents_listens_and_is_reachable_from_inside_the_container]
INSTANA_AGENT_PORT=42699

    Use a different port if configured differently.

Tracing applications running on Alpine Linux

Edit online

To enable tracing for applications running on Alpine Linux, complete the following steps:

  1. After you install the host agent, install the following packages in your application:

    Note:
    • If the packages are available on NuGet.org, you can download them by using the nuget.exe file, if available, without compiling the project. Alternatively, you can manually download these packages, extract them, and then set the environment variables to point to the extracted files as described in the following step.
    • Select the appropriate rewriter package based on your system architecture. You can add the Instana.Tracing.Core.Rewriter.Windows package to your project or add it before publishing.

  2. Set the following environment variables before you start your process:

    DOTNET_STARTUP_HOOKS=[path-to-your-app]/Instana.Tracing.Core.dll
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-b283c03916dd}
CORECLR_PROFILER_PATH=[Path_to_your_app]/instana_tracing/CoreProfiler.so

  3. If your application is running inside a container, define the agent environment variables:

    INSTANA_AGENT_HOST=[address_where_the_agents_listens_and_is_reachable_from_inside_the_container]
INSTANA_AGENT_PORT=42699