Setting up .NET tracing on Docker with Instana base images

Edit online

Use Instana .NET base images with a built-in tracing agent to simplify tracing setup in containerized .NET applications.

Instana .NET base images are preconfigured Docker images based on Microsoft's official .NET runtime images. They include the Instana tracing agent and come with instrumentation already installed and configured.

Important: Instana .NET base images are available from .NET Core Tracer 1.319.7 onwards.

For manual setup, see Manually setting up .NET tracing on Docker.

Key features

Edit online

The Instana .NET base images include:

  • Preinstalled Instana .NET Core Tracer
  • Preconfigured profiler environment variables
  • Multi-architecture support (amd64 and arm64)
  • Multiple OS variants (Alpine, Ubuntu Noble, and Ubuntu Resolute)
  • .NET 10.0 runtime support
  • Zero-code instrumentation ready

Prerequisites

Edit online

Before you use Instana .NET base images, ensure that the following prerequisites are met:

  • Docker is installed and running on your system.
  • You have your Instana agent key and endpoint URL.

Using base images for .NET tracing

Edit online

To use Instana .NET base images in your containerized application, complete the following steps:

  1. Choose the appropriate base image variant for your application. See Available image variants for options.
  2. Update your Dockerfile to use the Instana base image: 
    FROM artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-{variant}-{architecture}:{version}

    Replace {variant} and {architecture} with the appropriate values for your environment. For the {version} tag, use latest to get the most recent image version or a specific version (for example, 1.319.7) to pin to a particular release. For more information, see Architecture support and Image naming conventions sections.

Your application runs with Instana tracing enabled and automatically sends trace data to Instana.

Example 1: Simple ASP.NET Core application

Edit online

The following example shows a simple ASP.NET Core application using the Instana base image:

Dockerfile:

# Use Instana base image with specific version
FROM artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-alpine-amd64:1.319.7

# Copy published application
COPY ./publish /app

# Set entrypoint
ENTRYPOINT ["dotnet", "MyApp.dll"]

Build and run:

# Build your application
dotnet publish -c Release -o ./publish

# Build Docker image
docker build -t myapp:latest .

# Run with Instana configuration
docker run -d \
  -e INSTANA_AGENT_KEY="your-instana-agent-key" \
  -e INSTANA_ENDPOINT_URL="serverless-end-point-url" \
  -e INSTANA_SERVICE_NAME=my-service \
  -p 8080:8080 \
  myapp:latest

Example 2: Multi-stage build with SDK

Edit online

The following example demonstrates a multi-stage Dockerfile:

Dockerfile:

# Build stage
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["MyApp.csproj", "./"]
RUN dotnet restore
COPY . .
RUN dotnet publish -c Release -o /app/publish

# Runtime stage with Instana (using specific version)
FROM artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-noble-arm64:1.319.7

# Or use latest tag to get the most recent version
# FROM artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-noble-arm64:latest

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

Build and run:

# Build Docker image (this also builds your application)
docker build -t myapp:latest .

# Run with Instana configuration
docker run -d \
  -e INSTANA_AGENT_KEY="your-instana-agent-key" \
  -e INSTANA_ENDPOINT_URL="serverless-end-point-url" \
  -e INSTANA_SERVICE_NAME=my-service \
  -p 8080:8080 \
  myapp:latest

Example 3: Docker Compose with multiple services

Edit online

The following example shows how to use Docker Compose to run multiple services with Instana tracing:

docker-compose.yml:

version: '3.8'

services:
  api-service:
    build:
      context: ./api
      dockerfile: Dockerfile
    image: myapp-api:latest
    environment:
      - INSTANA_ENDPOINT_URL=serverless-end-point-url
      - INSTANA_AGENT_KEY=your-instana-agent-key
      - INSTANA_SERVICE_NAME=api-service
    ports:
      - "8080:8080"

  worker-service:
    build:
      context: ./worker
      dockerfile: Dockerfile
    image: myapp-worker:latest
    environment:
      - INSTANA_ENDPOINT_URL=serverless-end-point-url
      - INSTANA_AGENT_KEY=your-instana-agent-key
      - INSTANA_SERVICE_NAME=worker-service

Start services:

docker-compose up -d

Configuration values:

Replace the following values in your configuration:

  • your-instana-agent-key: Your Instana agent key
  • serverless-end-point-url: Your Instana endpoint URL
  • my-service or service names: Your service name

Why use Instana .NET base images

Edit online

Without base images, you need to:

  1. Manually download Instana NuGet packages in your Dockerfiles
  2. Configure complex environment variables for the CLR profiler
  3. Handle architecture-specific profiler binaries (amd64 vs arm64)
  4. Manage different profiler builds for Alpine (musl-libc) vs Ubuntu (glibc)
  5. Repeat this setup across multiple microservices

With Instana .NET Base Images, you can use preconfigured images that work out of the box.

Base image details

Edit online

You can choose from three different base images depending on your needs.

Available image variants

Edit online

The following table summarizes the available Instana .NET base images:

Table 1. Instana .NET base image variants
Variant Base image C library Use case Size
Alpine mcr.microsoft.com/dotnet/aspnet:10.0-alpine3.23 musl-libc Minimal containers, size-optimized 110 MB
Noble mcr.microsoft.com/dotnet/aspnet:10.0-noble glibc Ubuntu 24.04 LTS (Noble Numbat) 220 MB
Resolute mcr.microsoft.com/dotnet/aspnet:10.0-resolute glibc Ubuntu 25.04 (Resolute Ringtail) 220 MB

Architecture support

Edit online

Each variant supports:

  • amd64 (x86_64): Standard Intel or AMD processors
  • arm64 (aarch64): ARM processors (Apple Silicon, AWS Graviton, and other processors)

Image naming conventions

Edit online

The image name follows this pattern:

{registry}/dotnet-runtime-10.0-{variant}-{architecture}:{version}

Version tag options:

  • Use latest to automatically get the most recent image version
  • Use a specific version number (for example, 1.319.7) to pin to a particular release

Examples with specific version:

  • artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-alpine-amd64:1.319.7
  • artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-noble-arm64:1.319.7
  • artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-resolute-amd64:1.319.7

Examples with latest tag:

  • artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-alpine-amd64:latest
  • artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-noble-arm64:latest
  • artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-resolute-amd64:latest

Directory structure

Edit online

The base images include the following directory structure:

/opt/instana/
├── lib/
│   └── Instana.Tracing.Core.dll          # Managed tracer library
└── profiler/
    ├── CoreProfiler.so                    # Native profiler (architecture-specific)
    └── instrumentation.json               # Instrumentation configuration

Preconfigured environment variables

Edit online

All base images include the following preconfigured environment variables:

Table 2. Preconfigured environment variables
Variable Value Purpose
CORECLR_ENABLE_PROFILING 1 Enables CLR profiling
CORECLR_PROFILER {CF0D821E-299B-5307-A3D8-B283C03916DD} Instana profiler GUID
CORECLR_PROFILER_PATH /opt/instana/profiler/CoreProfiler.so Path to native profiler
DOTNET_STARTUP_HOOKS /opt/instana/lib/Instana.Tracing.Core.dll Managed tracer startup hook

Benefits

Edit online

The base images provide significant advantages over manual setup:

  • Zero manual configuration: No need to install NuGet packages or set environment variables
  • Consistent setup: Same configuration across all environments
  • Reduced errors: Eliminates common configuration mistakes
  • Faster deployment: Preconfigured images speed up container startup
  • Multi-architecture support: Single Dockerfile works across different CPU architectures
  • Simplified maintenance: Updates managed centrally by Instana