Skip to main content

DotNet Instrumentation

This guide explains how to instrument a .NET application by selecting the appropriate deployment type in Motadata APM for trace ingestion.

Prerequisites​

  • The Motadata Agent must be installed and running on the server where the .NET application is deployed. Also, the otelcol should be running as part of the Motadata Agent.
    To check the agent status, open a Linux terminal and run:
service motadata status

  • The Motadata Agent version must be:

    • 8.1.0 or higher for Host/VM.
    • 8.1.2 or higher for Docker.

  • The application must use:

    • .NET Core 8 or 9 on Linux.

  • .NET Core 8 self-contained deployments are not supported.

  • For Docker deployment:

    • Docker version must be 20.1 or higher.
    • The Motadata Agent must be installed on the host machine, but not inside the container.

  • The application must already be working and able to start without errors.

  • You may need root/sudo access if you encounter permission issues.

Configuration Steps​

Step1: Register the Application Service in Motadata APM

Go to Menu > Settings > APM > Application Registration. Clicking the Application Registration button, you can register a new application.

From the application registration screen, select the instrumentation type Host/VM or Docker.

.NET Trace Configuration​

FieldDescription
Select AgentSelect the Host/VM where this application is running.
LanguageSelect .NET from the language icons.
Service NameProvide a unique and meaningful name (for example, orderservice). Service names can contain letters, numbers, dots (.), and underscores (_). Do not use spaces or hyphens.
Service Attributes (Tags)Add key–value tags to your application for better filtering and organizing data in Explorer. Attribute key names must be lowercase (for example, apm.env = prod). To add multiple Key-Value pairs, click the add icon.
Add Custom ParametersAllows you to define custom sampling or tagging parameters for advanced use cases. These optional parameters are passed to the agent (for example, version=4).

Clicking the Apply Configuration button, the ingestion gets started.

Providing these details displays the Setup Command to instrument your .NET application. Run the generated command on the application host and restart the service to start collecting Traces.

Supported Frameworks​

The following frameworks are supported for instrumentation and monitoring. Ensure your application version aligns with the supported versions listed below.

FRAMEWORKVERSION(S)
ASP.NET (.NET Framework) MVC / WebApiAll versions (Not supported on .NET; Not supported on .NET ARM64; Only integrated pipeline mode is supported)
ASP.NET CoreAll versions (Not supported on .NET Framework)
GraphQL≥7.5.0 (Not supported on .NET Framework)
Quartz≥3.4.0 (Not supported on .NET Framework 4.7.1 and older)
WCF (Client)All versions
WCF (Service)All versions (Not supported on .NET)

Supported Database​

DatabaseVersion(s)
Elastic.Clients.Elasticsearch≥8.0.0 and <8.10.0 (Version ≥8.10.0 is supported by Elastic.Transport instrumentation)
Elastic.Transport≥0.4.16
Microsoft.EntityFrameworkCore≥6.0.12 (Not supported on .NET Framework)
MongoDB.Driver.Core / MongoDB.Driver≥2.7.0 < 4.0.0
MySqlConnector≥2.0.0
MySql.Data≥8.1.0 (Not supported on .NET Framework)
Npgsql≥6.0.0
Oracle.ManagedDataAccess.Core / Oracle.ManagedDataAccess≥23.4.0 (Not supported on ARM64)
Microsoft.Data.SqlClient / System.Data.SqlClient / System.DataAll versions (Microsoft.Data.SqlClient v3.* is not supported on .NET Framework; System.Data.SqlClient ≥4.8.5)
StackExchange.Redis≥2.6.122 & < 3.0.0 (Not supported on .NET Framework)

Supported Queue​

QueueVersion(s)
Confluent.Kafka≥1.4.0 & < 3.0.0 (Supported from version ≥1.8.2 on ARM64)
MassTransit≥8.0.0 (Not supported on .NET Framework)
NServiceBus≥8.0.0 & < 10.0.0
RabbitMQ.Client≥6.0.0 (Needs bytecode instrumentation only for 6. versions; 7.0.0+ uses only source instrumentation)

Supported Others​

LibraryVersion(s)
Azure SDKReleased after October 1, 2021 (Azure.* prefixed packages)
Grpc.Net.Client≥2.52.0 & < 3.0.0
System.Net.Http.HttpClient / System.Net.HttpWebRequestAll versions

Step2: Configure .NET Instrumentation

Choose the appropriate method based on where your .NET application is running.

Instrument .NET on Linux Host/VM​

The setup command generated in the UI is similar to the following:

SERVICE_NAME={{YourServiceName}} source /motadata/motadata/instrumentation/agents/dotnet/motadata-dotnet-auto-install.sh

Replace {{YourServiceName}} with the exact service name registered in Motadata APM.

Run the Setup Command​

Open a terminal on the same Linux machine where your application runs, navigate to the application directory, and run:

cd /path/to/your/dotnet/application
SERVICE_NAME={{YourServiceName}} source /motadata/motadata/instrumentation/agents/dotnet/motadata-dotnet-auto-install.sh

Start the Application​

Start the application in the same terminal session where you executed the setup command.

For example:

dotnet run

Or:

dotnet run --project YourProject.csproj

Or:

dotnet YourApplication.dll

Step3: Verify Trace Collection

Once the application is running, verify the below points:

  • Confirm that the service has been registered successfully.
  • On the service registration screen, the Service Trace Collection Status should display "Running."
  • The traces will start appearing in the APM Explorer screen.

Troubleshooting​

Problem 1: Permission denied while running the instrumentation command​

Cause
The current user does not have sufficient permission to execute the instrumentation script or access the required files.

Remedy
Run the instrumentation command with elevated privileges.

sudo SERVICE_NAME=orderservice source /motadata/motadata/instrumentation/agents/dotnet/motadata-dotnet-auto-install.sh

After the command completes, start the application normally if your application does not require sudo.

Problem 2: Environment variables are not set after running the setup command​

Cause The instrumentation command did not execute correctly, or the application was started from a different terminal session. For Linux Host/VM, the exported environment variables are session-specific.

Remedy Run the following commands in the same terminal where you executed the instrumentation command:

echo $CORECLR_ENABLE_PROFILING
echo $CORECLR_PROFILER
echo $OTEL_DOTNET_AUTO_HOME
echo $OTEL_EXPORTER_OTLP_ENDPOINT

If the values are empty, rerun the instrumentation command:

SERVICE_NAME=orderservice source /motadata/motadata/instrumentation/agents/dotnet/motadata-dotnet-auto-install.sh

Then start the application in the same terminal:

dotnet run

Problem 3: Traces are not visible even though the application starts successfully​

Cause The Motadata Agent may not be running correctly, the service configuration file may be missing, or trace files may not be getting generated.

Remedy

  1. Restart the Motadata Agent:
sudo service motadata restart
  1. Verify that the configuration file exists:
ls -la /motadata/motadata/config/orderservice.properties
  1. Check trace logs for recent errors:
ls /motadata/motadata/logs/trace/
  1. Rerun the instrumentation command and restart the application:
SERVICE_NAME=orderservice source /motadata/motadata/instrumentation/agents/dotnet/motadata-dotnet-auto-install.sh
dotnet run

Problem 4: Configuration file is missing​

Cause The service may not have been created successfully from the UI, or the properties file was not generated.

Remedy Check whether the configuration file exists:

ls -la /motadata/motadata/config/orderservice.properties

If the file is missing:

  • Go back to the Motadata APM UI
  • Verify that the service was created successfully
  • Delete and recreate the service if required
  • Confirm that the .properties file is generated after saving the service

Problem 5: Motadata Agent is not running​

Cause The Motadata Agent service or the otelcol process is not active on the host.

Remedy Check the agent status:

service motadata status

If needed, use sudo:

sudo service motadata status

If the agent is inactive or failed, start it:

sudo service motadata start

Then verify the status again:

sudo service motadata status

Confirm that the following processes are active:

  • motadata-agent
  • otelcol

Problem 6: Unsupported .NET version​

Cause The application is running on an unsupported runtime version.

Remedy Check the installed .NET version:

dotnet --version

Supported versions for Linux Host/VM are:

  • .NET Core 8
  • .NET Core 9

Also note that .NET Core 8 self-contained deployments are not supported.

Problem 7: Traces take too long to appear​

Cause By default, only 10% of traces are sampled. This can delay visibility during testing.

Remedy Temporarily increase the sampling rate to 100% for testing.

Edit the properties file:

sudo nano /motadata/motadata/config/yourservice.properties

Change:

otel.traces.sampler.arg=0.1

to:

otel.traces.sampler.arg=1

Save the file, then rerun the instrumentation command and restart the application:

SERVICE_NAME=yourservice source /motadata/motadata/instrumentation/agents/dotnet/motadata-dotnet-auto-install.sh
dotnet run

After testing, revert the value back to 0.1 and restart the application again.

Problem 8: Traces are generated but not exported to APM​

Cause The exporter configuration may not be working as expected.

Remedy Temporarily switch the exporter to console output for debugging.

Edit the properties file:

sudo nano /motadata/motadata/config/yourservice.properties

Change:

otel.traces.exporter=otlp

to:

otel.traces.exporter=console

Then rerun the instrumentation command and restart the application:

SERVICE_NAME=yourservice source /motadata/motadata/instrumentation/agents/dotnet/motadata-dotnet-auto-install.sh
dotnet run

Trace output will appear in the same terminal where the application is running.

After debugging, change the exporter back to otlp and restart the application again.

Problem 9: Traces stopped appearing after system reboot​

Cause The Motadata Agent may not have restarted properly, and Linux Host/VM instrumentation environment variables do not persist across reboots.

Remedy

  1. Check the agent status:
sudo service motadata status
  1. Start the agent if required:
sudo service motadata start
  1. Rerun the instrumentation command:
SERVICE_NAME=orderservice source /motadata/motadata/instrumentation/agents/dotnet/motadata-dotnet-auto-install.sh
  1. Start the application again:
dotnet run

Extra debugging: Enable detailed .NET auto-instrumentation logs​

Cause More detailed logs may be needed for advanced troubleshooting.

Remedy

Set debug logging using environment variables:

export OTEL_LOG_LEVEL=debug
export OTEL_DOTNET_AUTO_LOG_DIRECTORY=/var/log/otel-logs

Or use the properties file:

otel.dotnet.auto.debug=true
otel.dotnet.auto.log.level=debug
otel.dotnet.auto.log.directory=/var/log/otel-logs
otel.dotnet.auto.logger=file

Default internal log location:

/var/log/opentelemetry/dotnet

After troubleshooting, revert the debug configuration and rerun the instrumentation command before starting the application again.