.NET agent

The Traceable .NET agent is an in-app tracing agent that collects telemetry data from your .NET application and forwards it to the Traceable Platform Agent (TPA). The TPA then processes and sends this data to the Traceable platform for security analysis, observability, and runtime protection.

This topic walks you through the support matrix, prerequisites, installation steps, configuration options, upgrade and uninstallation procedures, and troubleshooting guidelines.

Before You Begin

Ensure the following requirements are met before installing the .NET agent:

• You are using .NET Core 6, 7, 8, and 9.

• Your application is not built on .NET Framework. .NET Framework-based applications are not supported.

• You have access to modify environment variables or update the application startup files.

• You have access to the deployed Traceable Platform Agent (TPA) endpoint (for example, http://agent.traceableai:5442). For a TLS connection, the port would be 5443.

• You have permission to install NuGet packages (for manual instrumentation).

• The underlying OS is supported if you plan to use blocking or sampling features.

Support Matrix

Support for request blocking

Traceable provides request-blocking support on the following operating system versions. You can install the Traceable .NET agent on other operating systems and continue to collect telemetry data. However, request blocking is not supported on any other operating system.

• Debian 10+

• Ubuntu 18.04+

• Amazon Linux 2+

• CentOS 7+

Note

.NET Framework is not supported.

Installation Options and Steps

Traceable provides two options for instrumenting your .NET application. Choose the method that best suits your deployment setup and control preferences.

Option A – Auto Instrumentation

Auto-instrumentation allows you to trace your application without modifying the code. This method works by setting environment variables that hook into the application startup.

Steps

1. Download the agent binaries for your runtime

   curl -L https://downloads.traceable.ai/agent/dotnet/latest/<rid>/<framework>/dotnetagent-<rid>-<framework>.zip -o dotnet-traceable.zip
   

   Replace <rid> with your Runtime Identifier (for example, win-x64, linux-x64) and <framework> with your .NET version (for example, net8.0).

   This command fetches the pre-compiled Traceable .NET agent specific to your environment.
   

2. Extract the contents of the downloaded ZIP file

   unzip dotnet-traceable.zip && cd traceable
   

   This unzips the agent package into a folder named traceable, which contains binaries and setup scripts.
   

3. Run the installation script to set the required environment variables

   • On Windows:

     .\install.ps1
     

   • On Linux:

     ./install.sh
     

     These scripts configure three essential environment variables that enable the agent to hook into .NET runtime:

   • DOTNET_STARTUP_HOOKS: Specifies the startup hook assembly.

   • DOTNET_SHARED_STORE: Points to shared dependencies for auto instrumentation.

   • DOTNET_ADDITIONAL_DEPS: Includes additional dependency declarations.

     Example values:

     DOTNET_STARTUP_HOOKS=<path>/traceable/net/Traceable.StartupHook.dll
     DOTNET_SHARED_STORE=<path>/traceable/store/
     DOTNET_ADDITIONAL_DEPS=<path>/traceable/additionalDeps/

4. Restart your application

   The .NET runtime reads the environment variables during application startup. A restart is required for instrumentation to begin.

Important:
The install script modifies environment variables only in the current terminal session. To persist these changes across reboots or systemd services, add them to your system profile, .bashrc, .systemd unit file, or equivalent.

Option B – Manual Instrumentation (SDK-based)

Manual instrumentation provides more control and requires a minor code change. This method is preferred if you are already managing dependencies via csproj.

Steps

1. Add the Traceable .NET SDK package

   dotnet add package Traceable.Agent
   

   This command pulls the Traceable SDK from NuGet and adds it to your project file (.csproj).
   

2. Register the Traceable agent in your Startup.cs or Program.cs

   For example in Startup.cs,

   using System.Text;
   public class Startup
   {
       // ... Rest of the code
       public void ConfigureServices(IServiceCollection services)
       {
           services.AddControllers();
           services.AddTraceableAgent(); // only change for Traceable Agent
       }
       // ... Rest of the code
       
   }

   This enables Traceable to start capturing telemetry and context-aware request data.
   

3. (Optional) If you want to control the position of Traceable’s Middleware, then Startup.cs or Program.cs file can be updated like

   Do either Step 2 or Step 3, not both.

   using System.Text;
   using Traceable.Instrumentation.AspNetCore.Implementation;
   public class Startup
   {
       // ... Rest of the code
       public void ConfigureServices(IServiceCollection services)
       {
           services.AddControllers();
           services.InitTraceableAgent(); //1st change for Traceable Agent
       }
       // ... Rest of the code
       
       <configure all the middlewares required before>    
       app.UseMiddleware<TraceableMiddleware>(); //2nd change for Traceable Agent
       <configure all the middlewares required after>    
   }

   You can choose whether Traceable runs before or after specific middleware (for example, CORS, Authentication), depending on what you want to capture.

Configuration Variables

You can configure the .NET agent using either a config.yaml file or environment variables. Environment variables always take precedence over values set in the YAML file.

Note:
The .NET agent supports configuration through either a YAML file (config.yaml) or environment variables. This applies to both Auto and Manual instrumentation methods.

• To use a YAML file, set the environment variable TA_CONFIG_FILE to point to the config file path.

• Any environment variable will override the corresponding value in the YAML file.

Following is a sample config.yaml file:

export TA_ENVIRONMENT="production"
export TA_SERVICE_NAME="example-service-name"
export TA_REPORTING_ENDPOINT="<http://agent.traceableai:5442>"
export TA_REPORTING_TRACE_REPORTER_TYPE="Otlp"
export TA_BLOCKING_CONFIG_ENABLED=true
export TA_REMOTE_CONFIG_ENDPOINT=agent.traceableai:5442

Info: If you want to use TLS communication between the Traceable Platform Agent (TPA) and the .NET agent, you must use the OTLP_HTTP reporting type. This is because OpenTelemetry for .NET does not support TLS over OTLP/gRPC.

• For config.yaml:

  reporting:
    trace_reporter_type: OTLP_HTTP

• For environment variable:

  TA_REPORTING_TRACE_REPORTER_TYPE=OtlpHttp

The TPA endpoint will also need to change to a secure URL, for example: https://agent.traceableai:5443/v1/traces

Upgrade

To upgrade to the latest version of the .NET agent:

• Auto instrumentation: Download the latest binary package and re-run the install.ps1 or install.sh script.

• Manual instrumentation: Update the version in your .csproj file or run:

  dotnet add package Traceable.Agent -v <DESIRED_VERSION>

  Then execute:

  dotnet restore

Uninstall

• Manual instrumentation:

  dotnet remove package Traceable.Agent
  

  Remove any related code (such as AddTraceableAgent) from Startup.cs or Program.cs.

• Auto instrumentation:
  Delete the installed binaries and remove related environment variables from your shell or system configuration.

Troubleshoot

If no data appears in the Traceable platform after setup:

• Check if logs are being generated. Traceable logs are written to the application logger or the stdout.

• Verify the platform agent endpoint is reachable.

• Look for startup logs confirming agent initialization.

Common Issues