Enabling .NET tracing on different platforms

Depending on the environment in which your .NET applications run, you need to enable tracing as outlined in the following sections:

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 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. 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.

Enabling tracing on containers

For applications and services that run on the containers, apart from environment settings, additional steps are required for tracing to work.

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"]

Enabling tracing for .Net Core applications on Azure Container App Service

To enable tracing in your .NET Core application hosted on Azure, complete the following steps:

  1. Configure your .NET Core application to generate trace data:

    1. Install Instana tracing packages, Instana.Tracing.Core and Instana.Tracing.Core.Rewriter.Linux, on your .NET Core application.

    2. Modify your Dockerfile to include the following environment variables for .NET Core tracing:

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

    3. Create an Azure Container App service and deploy the .NET Core application image.

  2. Connect your .NET Core application to Instana by using the Instana serverless agent to monitor and collect the trace data:

    1. Log in to your Instana account.

    2. Retrieve the Instana endpoint URL and agent key from the Instana UI:

      1. From the navigation menu in the Instana UI, select More > Agents.
      2. Click Install agents, and the select Azure container apps.
      3. Copy the Instana endpoint URL and agent key.

    3. Set environment variables in the Azure portal:

      1. Go to Azure Container Apps in the Azure portal, and then select your container app.

      2. Click Settings > Environment Variables.

      3. Add the following environment variables and save:

        CORECLR_ENABLE_PROFILING = 1
CORECLR_PROFILER = {cf0d821e-299b-5307-a3d8-b283c03916dd}
CORECLR_PROFILER_PATH = /app/instana_tracing/CoreProfiler.so
DOTNET_STARTUP_HOOKS = /app/Instana.Tracing.Core.dll
INSTANA_ENDPOINT_URL = instana_endpoint_url
AZURE_SUBSCRIPTION_ID = your_azure_subscription_id
AZURE_RESOURCE_GROUP = your_azure_resource_group
INSTANA_SERVICE_NAME = your_service_name
INSTANA_AGENT_KEY = your_instana_agent_key

      INSTANA_SERVICE_NAME is the name of service that you want to monitor, for example, dotnetcore-webapp.

After you enable tracing, you can view the collected traces and insights from your .NET Core application in the Instana UI. To view the tracing data, complete the following steps:

  1. From the navigation menu in the Instana UI, select Applications > Services.
  2. Click your monitored service.