Configuration du traçage « .NET » sur Docker à l'aide des images de base Instana

Modifier en ligne

Utilisez les images de base « Instana » (.NET ) dotées d'un agent de traçage intégré pour simplifier la configuration du traçage dans les applications conteneurisées .NET.

Instana .NET Les images de base sont des images « Docker » préconfigurées, dérivées des images d'exécution officielles de Microsoft disponibles à l'adresse .NET. Ils intègrent l'agent de traçabilité « Instana » et sont livrés avec les outils d'instrumentation déjà installés et configurés.

Important : les images de base « Instana » et « .NET » sont disponibles à partir de la version .NET Core Tracer 1.319.7.

Pour la configuration manuelle, consultez la section « Configuration manuelle du suivi d'.NET » sur Docker.

Fonctions principales

Modifier en ligne

Les images de base de l' Instana .NET comprennent :

  • Instana.NET Core Tracer préinstallé
  • Variables d'environnement préconfigurées pour le profileur
  • Prise en charge de plusieurs architectures ( amd64 et arm64 )
  • Plusieurs variantes du système d'exploitation ( Alpine, Ubuntu Noble et Ubuntu Resolute)
  • .NET 10.0 assistance à l'exécution
  • Prêt pour l'instrumentation sans code

Prérequis

Modifier en ligne

Avant d'utiliser les images de base Instana .NET, assurez-vous que les conditions préalables suivantes sont remplies :

  • Docker est installé et fonctionne sur votre système.
  • Vous disposez de votre clé d'agent Instana et de votre point de terminaison URL.

Utilisation d'images de base pour le traçage d'.NET

Modifier en ligne

Pour utiliser les images de base Instana .NET dans votre application conteneurisée, procédez comme suit :

  1. Choisissez la variante d'image de base adaptée à votre application. Consultez les variantes d'images disponibles pour connaître les options proposées.
  2. Mettez à jour votre fichier Dockerfile pour utiliser l'image de base « Instana » :
    FROM artifact-public.instana.io/dotnet-tracers/dotnet-runtime-10.0-{variant}-{architecture}:{version}

    Remplacez {variant} et {architecture} par les valeurs adaptées à votre environnement. Pour le tag « {version} », utilisez latest pour obtenir la version la plus récente de l'image ou une version spécifique (par exemple, 1.319.7) afin de l'associer à une version particulière. Pour plus d'informations, consultez les sections « Prise en charge des architectures » et « Conventions de nommage des images ».

Votre application s'exécute avec le traçage « Instana » activé et envoie automatiquement les données de traçage à Instana.

Exemple 1 : Application simple d' ASP.NET Core

Modifier en ligne

L'exemple suivant présente une application simple d' ASP.NET Core, utilisant l'image de base « Instana » :

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

Compiler et exécuter :

# 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

Exemple 2 : Compilation en plusieurs étapes avec le SDK

Modifier en ligne

L'exemple suivant illustre un fichier Dockerfile à plusieurs étapes :

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

Compiler et exécuter :

# 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

Exemple 3 : « Docker Compose » avec plusieurs services

Modifier en ligne

L'exemple suivant montre comment utiliser Docker Compose pour exécuter plusieurs services avec le traçage Instana :

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

Démarrer les services :

docker-compose up -d

Valeurs de configuration :

Remplacez les valeurs suivantes dans votre configuration :

  • your-instana-agent-key: Votre clé d'agent « Instana »
  • serverless-end-point-url: Votre point de terminaison Instana URL
  • my-service ou noms de service : Le nom de votre service

Pourquoi utiliser les images de base d' Instana .NET?

Modifier en ligne

En l'absence d'images de base, vous devez :

  1. Téléchargez manuellement les paquets Instana NuGet dans vos fichiers Dockerfile
  2. Configurer des variables d'environnement complexes pour le profileur CLR
  3. Gérer les binaires du profileur spécifiques à l'architecture ( amd64 vs arm64 )
  4. Gérer différentes versions du profileur pour Alpine (musl-libc) et Ubuntu (glibc)
  5. Répétez cette configuration pour plusieurs microservices

Grâce aux images de base « Instana » .NET, vous pouvez utiliser des images préconfigurées prêtes à l'emploi.

Détails de l'image de base

Modifier en ligne

Vous pouvez choisir parmi trois images de base différentes, en fonction de vos besoins.

Variantes d'images disponibles

Modifier en ligne

Le tableau suivant présente un aperçu des images de base disponibles sur Instana .NET :

Tableau 1. Instana .NET variantes de l'image de base
Variante Image de base bibliothèque C Cas d'utilisation Taille
Alpine mcr.microsoft.com/dotnet/aspnet:10.0-alpine3.23 musl-libc Conteneurs minimalistes, de taille optimisée 110 Mo
Noble mcr.microsoft.com/dotnet/aspnet:10.0-noble glibc Ubuntu 24.04 LTS (Numbat noble) 220 Mo
Résolue mcr.microsoft.com/dotnet/aspnet:10.0-resolute glibc Ubuntu 25.04 (Colibri à queue en anneau résolu) 220 Mo

Prise en charge de l'architecture

Modifier en ligne

Chaque variante prend en charge :

  • amd64 ( x86_64 ) : processeurs Intel ou AMD standard
  • arm64 ( aarch64 ) : processeurs ARM (Apple Silicon, AWS Graviton et autres processeurs)

Conventions de nommage des images

Modifier en ligne

Le nom de l'image respecte le modèle suivant :

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

Options de balise de version :

  • Utilisez latest pour obtenir automatiquement la version la plus récente de l'image
  • Utilisez un numéro de version spécifique (par exemple, 1.319.7) pour associer cette version à une version particulière

Exemples avec une version précise :

  • 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

Exemples avec le tag « latest » :

  • 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

Structure de répertoire

Modifier en ligne

Les images de base présentent la structure de répertoires suivante :

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

Variables d'environnement préconfigurées

Modifier en ligne

Toutes les images de base incluent les variables d'environnement préconfigurées suivantes :

Tableau 2. Variables d'environnement préconfigurées
Variables Valeur Fonction
CORECLR_ENABLE_PROFILING 1 Active le profilage CLR
CORECLR_PROFILER {CF0D821E-299B-5307-A3D8-B283C03916DD} Instana GUID du profileur
CORECLR_PROFILER_PATH /opt/instana/profiler/CoreProfiler.so Chemin d'accès au profileur natif
DOTNET_STARTUP_HOOKS /opt/instana/lib/Instana.Tracing.Core.dll Hook de démarrage du traceur géré

Avantages

Modifier en ligne

Les images de base offrent des avantages considérables par rapport à une configuration manuelle :

  • Aucune configuration manuelle : pas besoin d'installer des paquets d' NuGet s ni de définir des variables d'environnement
  • Configuration uniforme : même configuration dans tous les environnements
  • Réduction des erreurs : élimine les erreurs de configuration courantes
  • Déploiement plus rapide : les images préconfigurées accélèrent le démarrage des conteneurs
  • Prise en charge multi-architecture : un seul fichier Dockerfile fonctionne sur différentes architectures de processeur
  • Maintenance simplifiée : mises à jour gérées de manière centralisée par Instana