Setting up .NET tracing on Docker containers

Set up .NET tracing for applications that run in Docker containers by using preconfigured Instana base images or manual configuration.

Important:
Instana .NET base images are available from .NET Core Tracer 1.319.7 onward. These images provide a preconfigured tracing setup and eliminate the need for manual configuration for containerized .NET applications.

For details about the working of .NET monitoring, see How .NET monitoring works.

Choosing your setup method

You can set up .NET tracing on Docker by using one of the following methods based on your requirements:

  • Using Instana .NET base images: Use preconfigured Docker images with a built-in Instana tracing agent. This approach eliminates manual configuration and simplifies tracing setup. Available from .NET Core Tracer 1.319.7 onwards. For details, see Setting up .NET tracing on Docker with Instana base images.
  • Using NuGet packages and configuring Dockerfile (manual setup): Install NuGet packages and configure environment variables in your Dockerfile. Use this method if you need custom configuration or are using .NET Core Tracer versions earlier than 1.319.7.

Manually setting up .NET tracing on Docker

To enable .NET tracing for applications running in Docker containers, complete the following steps:

Prerequisites

Before you enable .NET tracing for containers, ensure that the following prerequisites are met:

  • An Instana agent is installed, running, and accessible from your Docker container. See Installing the Instana agent on Docker.
  • Verify network connectivity between your Docker container and the Instana agent. The container must be able to reach the agent's host and port.
  • Review support information.

Installing NuGet packages and configuring environment variables

For applications and services that run inside containers, complete the following steps:

  1. Install the following NuGet packages in your .NET application:

    When the packages are distributed through NuGet.org, you can install them without recompiling the application. Use one of the following methods:

    • nuget.exe available: Restore the packages by using nuget.exe without compiling the project that is to be instrumented.
    • nuget.exe unavailable: Download the packages directly, extract them, and then set the environment variables to point to the extracted files as described in the following step.
    Note:
    You can add the package to your project or add it before publishing.

  2. Configure your Dockerfile: Add the required environment variables to your Dockerfile. The following example shows a Dockerfile with required environment variables:

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

    Replace the following values:

    • host_or_other_container_name_or_ip: The hostname, container name, or IP address where the Instana agent is running.
    • 42699: The port on which the Instana agent listens.
    • YourApp.dll: The name of your application DLL.
    • some,parameters: Any additional parameters that your application requires.
  3. Build and run your container.

Your application is instrumented, and the Instana agent automatically collects and displays trace data in the Instana UI.

To verify whether tracing is working, log in to your Instana dashboard. You can see traces appearing.

For a simplified setup, use Instana base images instead. See Instana base images.