Monitoring .NET and .NET Core based applications

Enabling tracing for applications running on Kubernetes

The Instana AutoTrace webhook is an implementation of a Kubernetes Mutating Webhook Admission Controller that automatically sets up everything that is required to monitor .NET applications with Instana, across an entire Kubernetes cluster.

If Instana AutoTrace webhook is installed on the Kubernetes clusters, tracing is automatically enabled for the .NET applications that run in those clusters.

If the .NET application and the Instana Agent are managed by Kubernetes, refer to Kubernetes network access for information about the required configuration.

Enabling tracing for applications running on Linux

When the packages are distributed through NuGet.org, you don't need to compile the project that is to be instrumented. You can restore the project by using the nuget.exe file, if available. Alternatively, you can download the necessary NuGet packages from Instana.Tracing.Core and Instana.Tracing.Core.Rewriter.Linux, and then extract them. After extraction, point the environment variables to the extracted files as shown in the following steps.

For applications that run on Linux except on Alpine Linux, install the Instana.Tracing.Core.Rewriter.Linux package. You can add the package to your project or add it before publishing. Provide the environment variables to your process before starting the process as shown in the following example:

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

If your application is running inside a container, define the environment for the process to contact the Instana agent at runtime:

INSTANA_AGENT_HOST=[address_where_the_agents_listens_and_is_reachable_from_inside_the_container]
INSTANA_AGENT_PORT=42699 (or any other port of configured differently)

Enabling tracing for applications running on Alpine Linux

When the packages are distributed through NuGet.org, you don't need to compile the project that is to be instrumented. You can restore the project by using the nuget.exe file, if available. Alternatively, you can download the necessary NuGet packages from Instana.Tracing.Core or Instana.Tracing.Core.Rewriter.Alpine, and then extract them. After extraction, point the environment variables to the extracted files as shown in the following steps.

Install the Instana.Tracing.Core.Rewriter.Alpine package. You can add the package to your project or add it before publishing. Then provide the environment variables to your process before starting the process as shown in the following example:

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

If your application is running in a container, define the environment for the process to contact the Instana agent at runtime:

INSTANA_AGENT_HOST=[address_where_the_agents_listens_and_is_reachable_from_inside_the_container]
INSTANA_AGENT_PORT=42699 (or any other port of configured differently)

Enabling tracing for applications running on Windows

When the packages are distributed through NuGet.org, you don't need to compile the project that is to be instrumented. The project can be restored using nuget.exe, if available. Alternatively, you can download the necessary NuGet packages from Instana.Tracing.Core and Instana.Tracing.Core.Rewriter.Windows, and then extract them. After extraction, point the environment variables to the extracted files as shown in the following steps.

Install the Instana.Tracing.Core.Rewriter.Windows package. You can add the package to your project or add it before publishing.

Enabling tracing for Windows processes

After you install the package, provide the environment variables to your process before starting the process as shown in the following example:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3}
CORECLR_PROFILER_PATH_64=[Path_to_your_app]/instana_tracing/CoreRewriter_x64.dll
CORECLR_PROFILER_PATH_32=[Path_to_your_app]/instana_tracing/CoreRewriter_x86.dll
DOTNET_STARTUP_HOOKS=[Path_to_your_app]/Instana.Tracing.Core.dll

Enabling tracing for Windows services

If you are running Windows services, you can also put these settings into the registry, on a per-service basis, which gives you better control to choose the services to trace.

Go to the Registry Editor in the HKLM\System\CurrentControlSet\Services\<ServiceName> directory, and add a MULTI_SZ as the value for Environment. If Environment does not exist, then copy the variables CORECLR_ENABLE_PROFILING=1 and CORECLR_PROFILER={FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3} into the file.

To set the contents of a MULTI_SZ value, enter one key-value-pair per line as shown in the following example:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3}
CORECLR_PROFILER_PATH_64=[Path_to_your_app]/instana_tracing/CoreRewriter_x64.dll
CORECLR_PROFILER_PATH_32=[Path_to_your_app]/instana_tracing/CoreRewriter_x86.dll
DOTNET_STARTUP_HOOKS=[Path_to_your_app]/Instana.Tracing.Core.dll

Press Enter after you enter the last line.

Enabling tracing for IIS hosted applications

You need the following components to set up tracing:

• .NET Framework

  InstanaPCP automatically sets the environment variables and installs the necessary files to work with your .NET Framework applications. After the Instana agent and InstanaPCP application start running, run the iisreset command. To check whether InstanaPCP is running, use Task Manager on Windows.

• .NET Core

  To set up tracing in .NET core, complete the following steps:

  1. You must make sure that both the Instana agent and InstanaPCP are running.

  2. You need to install both the Instana.Tracing.Core.Rewriter.Windows and Instana.Tracing.Core packages in the application. Alternatively, you can download these packages, extract them, and point the following described environment variables to the files.

  3. Then, add the environment variables in the web.config file of the application that you want to trace in the following format:

     <aspNetCore ...>
     <environmentVariables>
     <environmentVariable name="CORECLR_ENABLE_PROFILING" value="1" />
     <environmentVariable name="CORECLR_PROFILER" value="{FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3}" />
     <environmentVariable name="CORECLR_PROFILER_PATH_64" value="[Path_to_your_app]/instana_tracing/CoreRewriter_x64.dll" />
     <environmentVariable name="CORECLR_PROFILER_PATH_32" value="[Path_to_your_app]/instana_tracing/CoreRewriter_x32.dll" />
     <environmentVariable name="DOTNET_STARTUP_HOOKS" value="[Path_to_your_app]/Instana.Tracing.Core.dll" />
     </environmentVariables>
     </aspNetCore>
     

  After the variables are added, run the iisreset command to reload the process.

If IIS is not reset, the IIS workers aren't instrumented, and you cannot trace IIS-hosted applications. After you restart your system, you must reset IIS to ensure that IIS hosted applications are instrumented. You must reset IIS even if the application was previously instrumented.

Enabling tracing for applications on Cloud Foundry

This section is applicable only if the Instana agent is running on the Diego cells of the Cloud Foundry foundation. For information on setting up Instana agents and the related Cloud Foundry or Pivotal Platform functionality, see Cloud Foundry and Pivotal Platform documentation.

On Cloud Foundry, to monitor non self-contained .NET applications follow these steps:

• To add the Instana NuGet package to the Cloud Foundry application, run this command:

  dotnet add myproject.csproj package Instana.Tracing.Core.Rewriter.Linux
  

• To prepare the .NET application for publication, run this command:

  dotnet publish -c Release
  

• To use a configuration other than Release, add the following environment variables to the application manifest:

  ---
  applications:
  - name: <application_name>
    path: bin/Release/netcoreapp2.1/publish/
    env:
      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: "/home/vcap/app/instana_tracing/CoreProfiler.so"
      LD_LIBRARY_PATH: "/home/vcap/app/instana_tracing"
  

  Depending on the .NET SDK that is used and the configuration name that is passed to the dotnet publish -c Release command through the -c flag (Release in the example), the value for the path variable might change.

• To push the Cloud Foundry application, run this command:

  cf push
  

  The command above assumes that the application's manifest.mf file is located in the same folder from which you run the cf push command.

For more information on how to use the cf push command together with a manifest file, see Deploying with App Manifests.

IL-rewriter and Instrumentation libraries for Linux containers

Add the nuget-package, and ensure that the environment variables are added for connection to the agent.

Setting up your container for automatic tracing

The following example shows a Docker file:

### your docker-image and application-build/-publish here

# set CoreCLR tracing environment variables
ENV DOTNET_STARTUP_HOOKS=/app/Instana.Tracing.Core.dll
ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-b283c03916dd}
ENV CORECLR_PROFILER_PATH=/app/instana_tracing/CoreProfiler.so

# provide agent-endpoint
ENV INSTANA_AGENT_HOST=host_or_other_container_name_or_ip
ENV INSTANA_AGENT_PORT=42699
ENTRYPOINT ["dotnet", "YourApp.dll","some","parameters"]

Verify the tracer is installed

Check your application logs for the following entry:

Error getting agent-info, make sure the agent is running and reachable:One or more errors occurred. (Connection refused)

This line indicates that the tracer is installed and running. You can see several entries with the following text:

Process Announcement:One or more errors occurred. (Connection refused)

If you do not see entries with the text in the example, ensure that the following prerequisites are met:

• .NET tracing is enabled in the configuration.yaml file of the host agent.
• All the required steps in the Tracing documentation are followed.

If your .NET application is running on Kubernetes, try Instana AutoTrace webhook, which automatically and transparently adds .NET instrumentation to your pods.

If you are unable to fix the issue with other troubleshooting steps listed, try the following tips to resolve networking issues:

Verify the tracer can connect to the host agent

If .NET tracer is installed, verify that .NET process can connect to the host agent on the same host on port 42699. For more information on network visibility, see Network requirements for the Instana host agent.

In containerized platforms, network visibility issues between the containers of the application and Instana host agent might occur. Due to some overlay network setup, the container of the application might not connect to the Instana agent container on the same host.

.NET tracer might be using the wrong IP address or DNS name to communicate with the Instana agent. You can set .NET tracer to use a specific network address by using the INSTANA_AGENT_HOST environment variable.

In some instances, if you have set up your networking, the issue might not be with the network address, but the issue might be related to the port that is used by the tracer.

If the host agent listen on a different port other than 42699, remap the port for the tracer by using the INSTANA_AGENT_PORT environment variable.

If you are unable to troubleshoot the issues, open a support case.