.NET Application monitoring using OCI APM

You can monitor your .NET application using Oracle Cloud Infrastructure APM service.

The supported version is .NET framework 4.6.2 or higher, or .NET 6 or higher.

The supported operating system are Windows Server 2012r2, 2016, 2019 ,2022. It also supports Linux operating system from 1.7 APM .NET agent version.

Installation:

1. Create a APM Domain if not available already.

Application Performance Monitoring → Administration → Create APM Domain . You can create free domain for testing purpose.

It will take some time for the domain to be created. Once its created please note down the data keys and data upload endpoint .

2. Download the .NET agent and upload to the host where the .NET application is running .

Unzip the file in a specific directory and that directory will be used as Install directory later while setting the environment variable.

NOTE : The below steps were written for .NET agent version before 1.7 . From 1.7 version powershell automation has been provided. Please follow the oracle documentation to deploy.

If you application is based on .NET framework you have to run a powershell script to register dll’s present under the directory net in Global Assembly Cache (GAC). Please refer the APM provisioning doc for the script under Optional — Register .NET Framework DLLs in GAC

[System.Reflection.Assembly]::Load("System.EnterpriseServices, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a") | Out-Null
$publish = New-Object System.EnterpriseServices.Internal.Publish
$dlls = Get-ChildItem -Path .\netfx\ -Filter *.dll -File
for($i = 0; $i -lt $dlls.Count; $i++) {
    $percentageComplete = $i / $dlls.Count * 100
    Write-Progress -Activity "Registering .NET Framweworks dlls in GAC"`
        -Status "Module $($i+1) out of $($dlls.Count). Installing $($dlls[$i].Name):"`
        -PercentComplete $percentageComplete
     $publish.GacInstall($dlls[$i].FullName)
}
Write-Progress -Activity "Registering .NET Framweworks dlls in GAC"-Status "Ready" -Completed

3. Next we need to register OTEL environment variables for the windows service.

If the .NET application is running on IIS set the environment variable for WAS and W3SVC service.

If the .NET application is running as a separate windows service set the environment for that specific service.

For console application you have to set the environment variables in the console using set command.

Setting manually the environment variables in regedit will be cumbersome for many services.

Opentelemetry .NET project has provided some scripts for automation. I have modified the function and added extra environment variables needed for OCI APM. You can find the powershell script in GitHub here .

NOTE: Please validate the script before using it in production environment and its advised to backup the registry before editing .

You can run the script in powershell like below to add environment variables to the service(WAS for example) specified. If you want to specify OTEL_SERVICE_NAME then the third argument has to be passed as well.

If you don’t specify OTEL_SERVICE_NAME it will automatically pick the website name in IIS .Refer this opentelemetry Github page for more info.

4. Restart IIS for the changes to take effect for application deployed in IIS

Restart the windows service if application is running as a windows service.

5. Hit the application URL and you should see the traces in APM Trace Explorer. I have used the sample rolldice application for demonstration.

6 . To enable browser agent follow the steps as per this doc since its disabled by default . The browser agent will inject java script into html pages.

Set the below environment variables to enable browser injection
OTEL_BA_ENABLED=true
OTEL_BA_PUBLIC_KEY=<public data key>

APM HttpModule has to be added as well for .NET framework in applicationHost.config by adding location tag. please To learn more about applicationHostConfig refer this Microsoft page and search for location tag.

For other additional settings for the browser agent please refer this doc.

If your application code has content security policy which restricts downloading java script from other endpoints or URL the application might fail to load. Either you have to change the CSP settings or do manual instrumentation of the javascript .

Advantage of OCI APM over OTEL:

Using OCI APM .NET agent over Opentelemetry .NET agent you will be able to do the browser monitoring .OCI APM has other features like abridge tracing which can help to eliminate cases of excessive span count per trace.

You will get out of the box dashboards for APM and if needed you can create your own custom dashboard as well.

You can monitor your URL availability using synthetic monitoring and using the OCI notification service you can alert when certain metrics are breached.

Troubleshooting:

In case if you don’t see any traces in Trace Explorer please check the metrics explorer for oci_apm namespace and metricname PayloadRejections for the reason . If its showing INVALID_DATA_KEY as a reason please check whether you have given the correct private key .

You can also enable APM service logs for troubleshooting. Please disable the logs if no longer needed .

Navigate to https://cloud.oracle.com/logging/logs to enable APM service logs.