Utiliser Application Insights pour la télémétrie .NET Aspire

Article
12/14/2024

Azure Application Insights, une fonctionnalité de Azure Monitor, excelle dans Application Performance Management (APM) pour les applications web actives. Projets .NET Aspire sont conçus pour utiliser OpenTelemetry pour la télémétrie des applications. OpenTelemetry prend en charge un modèle d’extension pour prendre en charge l’envoi de données à différentes API. .NET .NET Aspire utilise OTLP par défaut pour l’exportation de télémétrie, qui est utilisée par le tableau de bord pendant le développement. Azure Monitor ne prend pas encore en charge OTLP. Par conséquent, les applications doivent être modifiées pour utiliser l’exportateur Azure Monitor et configurées avec la chaîne de connexion.

Pour utiliser Application Insights, vous spécifiez sa configuration dans le projet hôte d’application et utilisez la distribution Azure Monitor dans le projet par défaut du service.

Choix de la façon dont Application Insights est provisionné

.NET Aspire a la possibilité de provisionner des ressources cloud dans le cadre du déploiement cloud, y compris Application Insights. Dans votre projet .NET Aspire, vous pouvez décider si vous souhaitez .NET Aspire approvisionner une ressource Application Insights lors du déploiement sur Azure. Vous pouvez également choisir d’utiliser une ressource Application Insights existante en fournissant sa chaîne de connexion. Les informations de connexion sont gérées par la configuration des ressources dans le projet hôte de l’application.

Approvisionnement d'Application Insights pendant le déploiement Azure

Avec cette option, une instance de Application Insights est créée pour vous lorsque l’application est déployée à l’aide du Azure Developer CLI (azd).

Pour utiliser l’approvisionnement automatique, vous spécifiez une dépendance dans le projet hôte d’application et référencez-la dans chaque projet/ressource qui doit envoyer des données de télémétrie à Application Insights. Les étapes sont les suivantes :

Ajoutez une référence de package Nuget à Aspire. Hébergement.Azure. ApplicationInsights dans le projet hôte d’application.
Mettez à jour le code hôte de l’application pour utiliser la ressource Application Insights et référencez-la à partir de chaque projet :

var builder = DistributedApplication.CreateBuilder(args);

// Automatically provision an Application Insights resource
var insights = builder.AddAzureApplicationInsights("MyApplicationInsights");

// Reference the resource from each project 
var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(insights);

builder.AddProject<Projects.Web>("webfrontend")
    .WithReference(apiService)
    .WithReference(insights);

builder.Build().Run();

Suivez les étapes décrites dans Déployer un projet de .NET Aspire sur Azure Container Apps à l’aide du Azure Developer CLI (guide détaillé) pour déployer l’application sur Azure Container Apps. azd crée une ressource Application Insights dans le cadre du même groupe de ressources et configure la chaîne de connexion pour chaque conteneur.

Approvisionnement manuel de la ressource Application Insights

Application Insights utilise une chaîne de connexion pour indiquer à l’exportateur OpenTelemetry où envoyer les données de télémétrie. La chaîne de connexion est spécifique à l’instance de Application Insights à laquelle vous souhaitez envoyer les données de télémétrie. Elle se trouve dans la page Vue d’ensemble de l’instance Application Insights.

Si vous souhaitez utiliser une instance de Application Insights que vous avez provisionnée manuellement, vous devez utiliser l’API AddConnectionString dans le projet hôte d’application pour indiquer aux projets/conteneurs où envoyer les données de télémétrie. La distribution Azure Monitor s’attend à ce que la variable d’environnement soit APPLICATIONINSIGHTS_CONNECTION_STRING, de sorte qu’elle doit être définie explicitement lors de la définition de la chaîne de connexion.

var builder = DistributedApplication.CreateBuilder(args);

var insights = builder.AddConnectionString(
    "myInsightsResource",
    "APPLICATIONINSIGHTS_CONNECTION_STRING");

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(insights);

builder.AddProject<Projects.Web>("webfrontend")
    .WithReference(apiService)
    .WithReference(insights);

builder.Build().Run();

Utilisation des ressources pendant le développement

Lors de l’exécution du projet .NET.NET Aspire localement, le code précédent lit la chaîne de connexion à partir de la configuration. Comme il s’agit d’un secret, vous devez stocker la valeur dans secrets d’application. Cliquez avec le bouton droit sur le projet hôte de l’application et choisissez Gérer les secrets dans le menu contextuel pour ouvrir le fichier de secrets du projet hôte de l’application. Dans le fichier, ajoutez la clé et votre chaîne de connexion spécifique, l’exemple ci-dessous est à des fins d’illustration.

{
  "ConnectionStrings": {
    "myInsightsResource": "InstrumentationKey=12345678-abcd-1234-abcd-1234abcd5678;IngestionEndpoint=https://westus3-1.in.applicationinsights.azure.com"
  }
}

Note

La name spécifiée dans le code hôte de l’application doit correspondre à une clé à l’intérieur de la section ConnectionStrings dans le fichier de paramètres.

Utilisation des ressources pendant le déploiement

Lors du déploiement de d’une application Aspire avec Azure Developer CLI (azd), il reconnaîtra la ressource de chaîne de connexion et sollicitera une valeur. Cela permet à une ressource différente d’être utilisée pour le déploiement à partir de la valeur utilisée pour le développement local.

Déploiement mixte

Si vous souhaitez utiliser un autre mécanisme de déploiement par contexte d’exécution, utilisez l’API appropriée de manière conditionnelle. Par exemple, le code suivant utilise une connexion pré-fournie au moment du développement et une ressource provisionnée automatiquement au moment du déploiement.

var builder = DistributedApplication.CreateBuilder(args);

var insights = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureApplicationInsights("myInsightsResource")
    : builder.AddConnectionString("myInsightsResource", "APPLICATIONINSIGHTS_CONNECTION_STRING");

var apiService = builder.AddProject<Projects.ApiService>("apiservice")
    .WithReference(insights);

builder.AddProject<Projects.Web>("webfrontend")
    .WithReference(apiService)
    .WithReference(insights);

builder.Build().Run();

Pourboire

Le code précédent vous oblige à fournir les informations de la chaîne de connexion dans les secrets d'application pour une utilisation durant le développement, et azd vous demandera la chaîne de connexion au moment du déploiement.

Utiliser la distribution Azure Monitor

Pour simplifier l’exportation vers Azure Monitor, cet exemple utilise le dépôt d’exportation Azure Monitor. Il s’agit d’un package wrapper autour du package Azure Monitor OpenTelemetry Exporter qui facilite l’exportation vers Azure Monitor avec un ensemble de valeurs par défaut courantes.

Ajoutez le package suivant au projet ServiceDefaults afin qu’il soit inclus dans chacun des services .NET.NET Aspire. Pour plus d’informations, consultez les paramètres par défaut du service .NET.NET Aspire.

<PackageReference Include="Azure.Monitor.OpenTelemetry.AspNetCore" 
                  Version="*" />

Ajoutez une instruction 'using' en haut du projet.

using Azure.Monitor.OpenTelemetry.AspNetCore;

Supprimez les marques de commentaire de la ligne dans AddOpenTelemetryExporters pour utiliser l'exportateur de moniteur Azure :

private static IHostApplicationBuilder AddOpenTelemetryExporters(
    this IHostApplicationBuilder builder)
{
    // Omitted for brevity...

    // Uncomment the following lines to enable the Azure Monitor exporter 
    // (requires the Azure.Monitor.OpenTelemetry.AspNetCore package)
    if (!string.IsNullOrEmpty(builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"]))
    {
        builder.Services.AddOpenTelemetry().UseAzureMonitor();
    }
    return builder;
}

Il est possible de personnaliser davantage l’exportateur Azure Monitor, notamment la personnalisation du nom de la ressource et la modification de l’échantillonnage. Pour plus d’informations, voir Personnaliser l'exportateur Azure du moniteur. En utilisant la version sans paramètre de UseAzureMonitor(), la chaîne de connexion sera récupérée à partir de la variable d'environnement APPLICATIONINSIGHTS_CONNECTION_STRING que nous avons configurée via le projet hôte d'application.

Partager via