Partager via

Guide pratique pour intégrer la Gestion des API Azure avec Azure Application Insights

  • Article

S’APPLIQUE À : Tous les niveaux de Gestion des API

Vous pouvez facilement intégrer Azure Application Insights avec Gestion des API Azure. Azure Application Insights est un service extensible permettant aux développeurs web de créer et de gérer des applications sur de nombreuses plateformes. Dans ce guide, vous allez :

  • Parcourir les étapes de l’intégration d’Application Insights dans Gestion des API.
  • Découvrir les stratégies permettant de réduire l’impact sur les performances de votre instance de service Gestion des API.

Remarque

Dans un espace de travail Gestion des API, un propriétaire de l’espace de travail peut intégrer Application Insights indépendamment et activer la journalisation Application Insights pour les API de l’espace de travail. Les conseils généraux pour intégrer un espace de travail à Application Insights sont similaires aux instructions d’une instance gestion des API ; toutefois, la configuration est limitée à l’espace de travail uniquement. Actuellement, vous devez intégrer Application Insights dans un espace de travail en configurant une chaîne de connexion (recommandé) ou une clé d’instrumentation.

Avertissement

Lorsque vous utilisez notre passerelle auto-hébergée, nous ne garantissons pas que toutes les données de télémétrie seront envoyées à Azure Application Insights, étant donné qu’elles dépendent de la mise en mémoire tampon d’Application Insights.

Prérequis

Présentation du scénario

Voici les étapes de haut niveau pour ce scénario.

  1. D’abord, créez une connexion entre Application Insights et la Gestion des API.

    Vous pouvez créer une connexion entre Application Insights et votre Gestion des API à l’aide du Portail Azure, de l’API REST ou des outils Azure associés. Gestion des API configure une ressource d’enregistreur d’événements pour la connexion.

    Important

    Actuellement, dans le portail, Gestion des API prend uniquement en charge les connexions à Application Insights à l’aide d’une clé d’instrumentation Application Insights. Pour renforcer la sécurité, nous vous recommandons d’utiliser une chaîne de connexion Application Insights avec une identité managée Gestion des API. Pour configurer la chaîne de connexion avec des informations d’identification d’identité managée, utilisez l’API REST ou les outils associés, comme indiqué dans une section ultérieure de cet article. En savoir plus sur le connecteur Application Insights.

    Remarque

    Si votre ressource Application Insights se trouve dans un autre locataire, vous devez créer l’enregistreur d’événements à l’aide de l’API REST ou des outils associés, comme indiqué dans une section ultérieure de cet article.

  2. Ensuite, activez la journalisation Application Insights pour votre ou vos API.

    Dans cet article, vous allez activer la journalisation Application Insights pour votre API à l’aide du Portail Azure. Gestion des API configure une ressource de diagnostic pour l’API.

Créer une connexion à l’aide du portail Azure

Suivez ces étapes pour utiliser le Portail Azure pour créer une connexion entre Application Insights et Gestion des API.

Remarque

Si possible, Microsoft recommande d’utiliser la chaîne de connexion avec les informations d’identification d’identité managée pour renforcer la sécurité. Pour configurer ces informations d’identification, utilisez l’API REST ou les outils associés, comme indiqué dans une section ultérieure de cet article.

  1. Accédez à votre instance de service Gestion des API Azure sur le Portail Azure.

  2. Sélectionnez Application Insights dans le menu de gauche.

  3. Sélectionnez Ajouter.
    Capture d’écran montrant où ajouter une nouvelle connexion

  4. Sélectionnez l’instance Application Insights que vous avez créée précédemment, et entrez une brève description.

  5. Pour activer la supervision de la disponibilité de votre instance de gestion des API dans Application Insights, cochez la case Ajouter un moniteur de disponibilité.

    • Ce paramètre valide régulièrement si le point de terminaison de la passerelle de gestion des API répond.
    • Les résultats s’affichent dans le volet Disponibilité de l’instance Application Insights.

  6. Sélectionnez Create (Créer).

  7. Vérifiez que le nouvel enregistreur d’événements d’Application Insights figure désormais dans la liste.

    Capture d’écran montrant où afficher l’enregistreur d’événements Application Insights nouvellement créé avec la clé d’instrumentation.

Notes

En arrière-plan, une entité Enregistreur d’événements est créée dans votre instance de gestion des API, qui contient la clé d’instrumentation de l’instance Application Insights.

Conseil

Si vous devez mettre à jour la clé d’instrumentation configurée dans l’enregistreur d’événements Application Insights, sélectionnez la ligne de l’enregistreur d’événements dans la liste (et non le nom de l’enregistreur d’événements). Entrez la clé d’instrumentation, puis sélectionnez Enregistrer.

Créer une connexion à l’aide de l’API REST, de Bicep ou d’un modèle ARM

Suivez ces étapes pour utiliser l’API REST, Bicep ou le modèle ARM pour créer un enregistreur d’événements Application Insights pour votre instance Gestion des API. Vous pouvez configurer un enregistreur d’événements qui utilise une chaîne de connexion avec des informations d’identification d’identité managée (recommandé) ou un enregistreur d’événements qui utilise uniquement une chaîne de connexion.

Consultez les conditions préalables à l’utilisation d’une identité managée Gestion des API.

Votre chaîne de connexion Application Insights s’affiche dans la section Vue d’ensemble de votre ressource Application Insights.

Chaîne de connexion avec identité managée affectée par le système

Utilisez l’enregistreur d’événements gestion des API - Créer ou mettre à jour l’API REST avec le corps de la requête suivant.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with system-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"SystemAssigned"
    }
  }
}

Chaîne de connexion avec identité managée affectée par l’utilisateur

Utilisez l’enregistreur d’événements gestion des API - Créer ou mettre à jour l’API REST avec le corps de la requête suivant.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with user-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"<ClientID>"
    }
  }
}

Enregistreur d’événements avec des informations d’identification de chaîne de connexion uniquement

Votre chaîne de connexion Application Insights s’affiche dans la section Vue d’ensemble de votre ressource Application Insights.

Utilisez l’enregistreur d’événements gestion des API - Créer ou mettre à jour l’API REST avec le corps de la requête suivant.

Si vous configurez l’enregistreur d’événements pour un espace de travail, utilisez l’enregistreur d’événements d’espace de travail - Créer ou mettre à jour l’API REST.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."    
    }
  }
}

Activer la journalisation Application Insights pour l’API

Utilisez la procédure suivante pour activer la journalisation Application Insights pour une API. Vous pouvez également activer la journalisation Application Insights pour toutes les API.

  1. Accédez à votre instance de service Gestion des API Azure sur le Portail Azure.

  2. Sélectionnez API>API dans le menu de gauche.

  3. Sélectionnez une API, telle que Swagger Petstore. Si elle est configurée, sélectionnez une version.

    Conseil

    Pour activer la journalisation pour toutes les API, sélectionnez Toutes les API.

  4. Accédez à l’onglet Paramètres de la barre supérieure.

  5. Descendez jusqu’à la section Journaux de diagnostic.
    Capture d’écran de la configuration de Journaux de diagnostic dans le portail.

  6. Cochez la case Activer.

  7. Sélectionnez l’enregistreur d'événements joint dans la liste déroulante Destination.

  8. Entrez 100 pour Échantillonnage (%) et sélectionnez la case Toujours consigner les erreurs.

  9. Laissez le reste des paramètres tel quel. Pour plus d’informations sur les paramètres, consultez Informations de référence sur les paramètres des journaux de diagnostic.

    Avertissement

    Le remplacement de la valeur Nombre d’octets de charge utile à journaliser par défaut, 0, peut réduire considérablement les performances de vos API.

  10. Sélectionnez Enregistrer.

  11. En coulissez, une entité Diagnostic nommée applicationinsights’ est créée au niveau de l’API.

Notes

Les demandes aboutissent une fois que Gestion des API a envoyé l’intégralité de la réponse au client.

Enregistreurs d’événements pour une seule API ou toutes les API

Vous pouvez spécifier des enregistreurs d’événements à des différents niveaux :

  • Enregistreur d’événements pour une seule API
  • Enregistreur d’événements pour toutes les API

Spécification des deux :

  • Par défaut, l’enregistreur d’événements d’une seule API (niveau plus granulaire) remplacera celui de toutes les API.
  • Si les enregistreurs d’événements configurés aux deux niveaux sont différents et que vous avez besoin des deux enregistreurs d’événements pour recevoir des données de télémétrie (multiplexage), contactez Support Microsoft. Notez que le multiplexage n’est pas pris en charge si vous utilisez le même enregistreur d’événements (destination Application Insights) au niveau « Toutes les API » et au niveau de l’API unique. Pour que le multiplexage fonctionne correctement, vous devez configurer différents enregistreurs d’événements au niveau « Toutes les API » et au niveau de l’API individuelle, et demander de l’aide du support Microsoft pour activer le multiplexage pour votre service.

Données ajoutées à Application Insights

Application Insights reçoit :

Élément de télémétrie Description
Requête Pour chaque demande entrante :
  • Demande du serveur frontal
  • Réponse du serveur frontal
Dépendance Pour chaque demande transférée à un service principal :
  • Demande principale
  • Réponse principale
Exception Pour chaque demande ayant échoué :
  • A échoué en raison d’une interruption de la connexion cliente.
  • A déclenché une section on-error des stratégies d’API.
  • A un code d’état HTTP de réponse de type 4xx ou 5xx.
Trace Si vous configurez une stratégie de trace .
Le paramètre severity de la stratégie trace doit être supérieur ou égal au paramètre verbosity de journalisation d’Application Insights.

Notes

Consultez Limites d’Application Insights pour plus d’informations sur la taille maximale et le nombre d’événements et de métriques par instance d’Application Insights.

Émettre des métriques personnalisées

Vous pouvez émettre des métriques personnalisées vers Application Insights à partir de votre instance Gestion des API. Gestion des API émet des métriques personnalisées à l’aide de stratégies telles que emit-metric et azure-openai-emit-token-metric. La section suivante utilise la stratégie emit-metric comme exemple.

Remarque

Les métriques personnalisées sont une fonctionnalité de préversion d’Azure Monitor et soumises à des limitations.

Pour émettre des métriques personnalisées, effectuez les étapes de configuration suivantes.

  1. Activez Métriques personnalisées (préversion) avec des dimensions personnalisées dans votre instance Application Insights.

    1. Accédez à votre instance Application Insights dans le portail.
    2. Dans le menu de gauche, sélectionnez Utilisation et estimation des coûts.
    3. Sélectionnez Métriques personnalisées (préversion)>Avec des dimensions.
    4. Sélectionnez OK.

  2. Ajoutez la propriété "metrics": true à l’entité de diagnostic applicationInsights configurée dans Gestion des API. Actuellement, vous devez ajouter cette propriété à l’aide de l’API REST Gestion des API Diagnostic – Créer ou mettre à jour. Par exemple :

    PUT https://management.azure.com/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/diagnostics/applicationinsights

{
    [...]
    {
    "properties": {
        "loggerId": "/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/loggers/{ApplicationInsightsLoggerName}",
        "metrics": true
        [...]
    }
}

  3. Vérifiez que l’enregistreur d’événements Application Insights est configuré dans l’étendue vers laquelle vous envisagez d’émettre des métriques personnalisées (soit toutes les API, soit une seule API). Pour plus d’informations, consultez Activer la journalisation Application Insights pour votre API, plus haut dans cet article.

  4. Configurez la stratégie emit-metric dans une étendue où la journalisation Application Insights est configurée (toutes les API ou une seule API) et est activée pour les métriques personnalisées. Pour plus d’informations sur la stratégie, consultez la référence de stratégie emit-metric.

Limites pour les métriques personnalisées

Azure Monitor impose des limites d’utilisation pour les métriques personnalisées qui peuvent affecter votre capacité à émettre des métriques à partir de Gestion des API. Par exemple, Azure Monitor définit actuellement une limite de 10 clés de dimension par métrique et une limite de 50 000 séries chronologiques actives totales par région dans un abonnement (dans une période de 12 heures).

Ces limites ont les implications suivantes pour la configuration des métriques personnalisées dans une stratégie de gestion des API telle que emit-metric ou azure-openai-emit-token-metric :

  • Vous pouvez configurer un maximum de 10 dimensions personnalisées par stratégie .

  • Le nombre de séries chronologiques actives générées par la stratégie dans une période de 12 heures est le produit du nombre de valeurs uniques de chaque dimension configurée au cours de la période. Par exemple, si trois dimensions personnalisées ont été configurées dans la stratégie et que chaque dimension a 10 valeurs possibles au cours de la période, la stratégie contribuera à 1 000 (10 x 10 x 10) séries chronologiques actives.

  • Si vous configurez la stratégie dans plusieurs instances Gestion des API qui se trouvent dans la même région d’un abonnement, toutes les instances peuvent contribuer à la limite des séries chronologiques actives régionales.

Découvrez-en plus sur les limitations et considérations en matière de conception pour les métriques personnalisées dans Azure Monitor.

Conséquences sur les performances et échantillonnage des journaux

Avertissement

La journalisation de l’ensemble des événements peut avoir de grosses répercussions sur les performances en fonction du rythme des demandes entrantes.

Lors de tests de charge internes, cette fonctionnalité de journalisation a provoqué une baisse du débit de 40 %-50 % lorsque la fréquence des demandes a dépassé 1 000 par seconde. La fonctionnalité Application Insights est conçue pour évaluer les performances des applications à l’aide d’une analyse statistique. Elle n’est pas :

  • conçue pour être un système d’audit.
  • adaptée à la journalisation de chaque demande d’API de volume important.

Vous pouvez manipuler le nombre de demandes journalisées en réglant le paramètre Échantillonnage. Une valeur de 100 % signifie que toutes les demandes sont consignées, tandis que le 0 % indique une absence de journalisation.

L’échantillonnage permet de réduire le volume de télémétrie, ce qui permet de prévenir efficacement une dégradation significative des performances tout en conservant les avantages de la journalisation.

Pour améliorer les problèmes de performances, ignorez :

  • les en-têtes de demande et les réponses ;
  • la journalisation du corps de demande.

Vidéo

Dépannage

Résolution du problème de flux des données de télémétrie de Gestion des API vers Application Insights :

  • Vérifiez si une ressource d’étendue de liaison privée Azure Monitor (Azure Monitor Private Link Scope/AMPLS) liée existe dans le VNet où la ressource Gestion des API est connectée. Les ressources AMPLS ont une étendue globale entre les abonnements et sont responsables de la gestion des requêtes et de l’ingestion de données pour toutes les ressources Azure Monitor. Il est possible que l’AMPLS ait été configuré avec un mode d’accès Private-Only spécifiquement pour l’ingestion de données. Dans ce cas, incluez la ressource Application Insights et sa ressource Log Analytics associée dans l’AMPLS. Une fois cet ajout effectué, les données Gestion des API sont correctement ingérées dans la ressource Application Insights, ce qui résout le problème de transmission des données de télémétrie.

Contenu connexe