Partager via

Utiliser Azure Log Analytics dans le générateur d’API de données

Azure Log Analytics est une plateforme de journalisation centralisée qui agrège les journaux d’activité à partir d’applications, de ressources Azure, de machines virtuelles, de conteneurs, etc. L’intégration à Data API Builder (DAB) aide les entreprises à respecter les exigences de conformité, de gouvernance et d’observabilité. Contrairement à Application Insights (qui se concentre sur l'APM), Log Analytics offre une agrégation de journaux plus étendue avec la prise en charge du langage de requête Kusto (KQL).

Diagramme montrant le flux de télémétrie Log Analytics.

Prerequisites

  • Fichier de configuration DAB existant.
  • Un abonnement Azure avec des autorisations pour créer des ressources Log Analytics.
  • Espace de travail Azure Log Analytics avec :
    • Une table personnalisée (se terminant par _CL)
    • Règle de collecte de données (DCR)
    • Point de terminaison de collecte de données (DCE)
  • Identité managée activée sur votre hôte DAB (Azure App Service, Container Apps, machine virtuelle, etc.).
  • CLI du générateur d'API de données. Installer l’interface CLI

Configurer des ressources Azure Log Analytics

Avant de configurer DAB, créez les ressources Azure requises.

Créer un espace de travail Log Analytics

  1. Accédez auxespaces de travail Log Analytics> Azure.
  2. Sélectionnez + Créer.
  3. Choisissez votre abonnement, votre groupe de ressources et votre région.
  4. Fournissez un nom d’espace de travail.
  5. Sélectionnez Vérifier + créer>Créer.

Créer une table personnalisée

Les tables personnalisées pour l’API de collecte de journalisation doivent se terminer par _CL.

  1. Dans votre espace de travail Log Analytics, accédez aux tables.
  2. Sélectionnez + Créer un>journal personnalisé (basé sur DCR).
  3. Entrez le nom de la table (par exemple, DabLogs_CL).
  4. Définissez le schéma avec ces colonnes :
    • Time (dateheure)
    • LogLevel (chaîne)
    • Message (chaîne)
    • Component (chaîne)
    • Identifier (chaîne)
  5. Cliquez sur Créer.

Créer un point de terminaison de collecte de données (DCE)

  1. Accédez à Surveiller les>points de terminaison de collecte de données.
  2. Sélectionnez + Créer.
  3. Choisissez votre abonnement, votre groupe de ressources et votre région.
  4. Fournissez un nom (par exemple, my-dce).
  5. Sélectionnez Vérifier + créer>Créer.
  6. Copiez l’URL du point de terminaison d’ingestion des journaux (par exemple). https://my-dce.eastus-1.ingest.monitor.azure.com

Créer une règle de collecte de données (DCR)

  1. Accédez à Monitor>les règles de collecte de données.
  2. Sélectionnez + Créer.
  3. Choisissez l’abonnement, le groupe de ressources, la région.
  4. Fournissez un nom (par exemple, my-dcr).
  5. Dans les sources de données, sélectionnez Journaux de texte personnalisés.
  6. Configurer:
    • Point de terminaison de collecte de données : sélectionnez votre DCE.
    • Destination : votre espace de travail Log Analytics.
    • Table : Votre table personnalisée (DabLogs_CL).
  7. Sélectionnez Vérifier + créer>Créer.
  8. Copiez l’ID immuable (commence par dcr-).

Configurer l’authentification

DAB utilise l’identité managée Azure pour s’authentifier auprès de Log Analytics. Aucune information d’identification n’est stockée dans votre configuration.

Activer l’identité managée

az webapp identity assign \
  --name my-app \
  --resource-group my-rg

Attribuer des autorisations

Accordez le rôle Éditeur de métriques de surveillance à votre identité managée sur la DCR.

# Get Managed Identity principal ID
PRINCIPAL_ID=$(az webapp identity show \
  --name my-app \
  --resource-group my-rg \
  --query principalId -o tsv)

# Get DCR resource ID
DCR_ID=$(az monitor data-collection rule show \
  --name my-dcr \
  --resource-group my-rg \
  --query id -o tsv)

# Assign role
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Monitoring Metrics Publisher" \
  --scope $DCR_ID

Important

Sans cette attribution de rôle, DAB ne peut pas envoyer de journaux à Log Analytics même avec une configuration correcte.

Configurer Log Analytics

Ajoutez une azure-log-analytics section sous runtime.telemetry dans votre fichier de configuration.

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": true,
        "dab-identifier": "my-dab-instance",
        "flush-interval-seconds": 10,
        "auth": {
          "custom-table-name": "DabLogs_CL",
          "dcr-immutable-id": "dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

Propriétés de configuration

Propriété Descriptif Par défaut Constraints
enabled Activez ou désactivez l’intégration de Log Analytics. false Booléen
dab-identifier Chaîne unique pour identifier les entrées de journal de cette instance DAB. DabLogs Toute chaîne de caractères
flush-interval-seconds Fréquence (en secondes) de transmission des journaux vers Log Analytics. 5 Doit être > 0
auth.custom-table-name Nom de table personnalisé dans votre espace de travail Log Analytics. (obligatoire) Doit se terminer par _CL
auth.dcr-immutable-id ID immuable de votre règle de collecte de données. (obligatoire) Commence par dcr-
auth.dce-endpoint URL du point de terminaison de collecte de données. (obligatoire) HTTPS URL

Command-line

Configurer Log Analytics via dab configure.

Activer Log Analytics

dab configure \
  --runtime.telemetry.azure-log-analytics.enabled true

Définir l’identificateur DAB

dab configure \
  --runtime.telemetry.azure-log-analytics.dab-identifier my-dab-instance

Définir l’intervalle de vidage

dab configure \
  --runtime.telemetry.azure-log-analytics.flush-interval-seconds 10

Définir le nom de la table personnalisée

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.custom-table-name DabLogs_CL

Définir l'identifiant immuable DCR

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.dcr-immutable-id dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Définir le point de terminaison DCE

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.dce-endpoint https://my-dce.eastus-1.ingest.monitor.azure.com

Exécuter DAB

Démarrez DAB avec votre fichier de configuration :

dab start

Vérifiez les journaux de démarrage de DAB pour :

Azure Log Analytics is enabled.

Fonctionnement

Lorsque Log Analytics est activé, DAB :

  1. S’authentifie auprès d’Azure à l’aide de l’identité managée de l’hôte.
  2. Groupement par lots des entrées de journal selon flush-interval-seconds.
  3. Envoie les journaux au point de terminaison de collecte de données (DCE).
  4. DCE achemine les logs via la règle de collecte de données (DCR) pour la transformation.
  5. DCR ingère les journaux dans votre table Log Analytics personnalisée.

Flux de données

DAB Application
    ↓
ILogger (ASP.NET Core)
    ↓
Log Analytics Logger Provider
    ↓
Managed Identity Authentication
    ↓
Data Collection Endpoint (DCE)
    ↓
Data Collection Rule (DCR)
    ↓
Log Analytics Workspace (Custom Table)

Ce qui est capturé

Type de télémétrie Origine Examples
Traces ILogger appels dans le DAB Journaux d’activité de démarrage, journaux d’exécution des requêtes, avertissements
Errors Gestion des exceptions Erreurs d’exécution, erreurs de configuration, erreurs de base de données
Informations sur le composant DAB internes Quel module a généré le journal des événements
ID d’instance Paramétrage dab-identifier valeur pour le filtrage

Structure de journal

Chaque entrée de journal envoyée à Log Analytics contient les champs suivants :

Terrain Type Descriptif Example
Time datetime Horodatage (ISO 8601) 2026-01-27T14:30:00Z
LogLevel ficelle Gravité de la journalisation Information, WarningError
Message ficelle Message de log Request completed successfully
Component ficelle Composant DAB qui a généré le journal Azure.DataApiBuilder.Service.Startup
Identifier ficelle Valeur de la dab-identifier configuration my-dab-instance

Note

Les colonnes de table personnalisées dans Log Analytics ajoutent des suffixes : _s pour les chaînes, _d pour les doubles, _t pour les datetimes, etc.

Journaux de requêtes dans Log Analytics

  1. Ouvrez votre espace de travail Log Analytics dans le portail Azure.

  2. Accédez aux journaux et exécutez une requête KQL :

    DabLogs_CL
| where Identifier_s == "my-dab-instance"
| where LogLevel_s in ("Warning", "Error")
| where TimeGenerated > ago(1h)
| project TimeGenerated, LogLevel_s, Message_s, Component_s
| order by TimeGenerated desc

Exemples de requêtes

Compter les logs par niveau :

DabLogs_CL
| where TimeGenerated > ago(24h)
| summarize Count=count() by LogLevel_s

Recherchez des erreurs dans un composant spécifique :

DabLogs_CL
| where Component_s contains "SqlQueryExecutor"
| where LogLevel_s == "Error"
| project TimeGenerated, Message_s

Considérations relatives aux performances et aux coûts

Comportement de traitement par lots

Les lots DAB enregistrent et les envoient tous les flush-interval-secondséléments suivants :

  • 5 secondes (par défaut) : bon équilibre pour la plupart des scénarios.
  • 1 à 2 secondes : journalisation en temps quasi réel (appels d’API plus élevés, coût plus élevé).
  • 10 à 60 secondes : appels d’API réduits mais journaux différés.

Optimisation des coûts

La tarification de Log Analytics est basée sur les points suivants :

  1. Ingestion de données : par Go ingéré.
  2. Rétention des données : par Go par mois après le niveau gratuit.

Réduire les coûts :

  • Augmentez flush-interval-seconds pour traiter plus de journaux par lots.
  • Utilisez des filtres de niveau de journalisation pour exclure les logs verbaux. Pour plus d’informations, consultez Personnaliser la verbosité du journal de bord.
  • Définissez la rétention des données appropriée dans votre espace de travail Log Analytics.

Exemple : Filtrer pour réduire le volume

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "Default": "Warning",
        "Microsoft": "Error"
      },
      "azure-log-analytics": {
        "enabled": true,
        "flush-interval-seconds": 30,
        "auth": {
          "custom-table-name": "DabLogs_CL",
          "dcr-immutable-id": "dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

Cela permet de réduire considérablement le volume en envoyant uniquement les logs d’avertissement et d’erreur.

Conservation des données

La rétention des données Log Analytics est configurable par espace de travail :

Niveau Rétention par défaut Rétention maximale
Formule gratuite 7 jours 7 jours
Paiement à l’utilisation 30 jours 730 jours (2 ans)

Configurer la rétention : espace de travail Log Analytics → Utilisation et coûts estimés → rétention des données.

Conseil / Astuce

Pour les exigences de conformité, envisagez d’archiver des journaux plus anciens dans Stockage Azure pour une conservation à long terme.

Résolution des problèmes

Journaux d’activité non affichés dans Log Analytics

Symptôme : DAB démarre correctement, mais aucun journal n’apparaît dans votre espace de travail Log Analytics.

Causes possibles :

  • Configuration incomplète : vérifiez les journaux de démarrage DAB pour les erreurs telles que Logs won't be sent to Azure Log Analytics because the Custom Table Name is not available in the config file. Vérifier toutes les propriétés d’authentification requises : custom-table-name, dcr-immutable-id, dce-endpoint.

  • Identité managée non affectée : vérifiez que l’identité managée est activée avec az webapp identity show --name my-app --resource-group my-rg. Vérifiez l’attribution de rôle avec az role assignment list --assignee <principal-id> --scope <dcr-id>.

  • Point de terminaison DCE incorrect ou ID DCR : vérifiez que le format du point de terminaison DCE est https://<dce-name>.<region>-1.ingest.monitor.azure.com. Vérifiez que l’ID immuable DCR commence par dcr-.

  • La table personnalisée n’existe pas : les tables personnalisées doivent se terminer par _CL. Le schéma de table doit correspondre à la structure des logs.

Erreur : l’intervalle de vidage doit être positif

Cause : flush-interval-seconds est définie sur 0 ou valeur négative.

Solution : définir flush-interval-seconds sur un entier positif (minimum 1).

Les journaux DAB indiquent que « Azure Log Analytics est désactivé ».

Cause : enabled est false ou manquant dans la configuration.

Solution : définir enabled: true dans votre configuration.

Log Analytics et Application Insights

Capacité Application Insights Log Analytics
Concentration Analyse des performances des applications (APM) Agrégation centralisée des logs
Langage de requête KQL KQL
Scope Application unique Applications, machines virtuelles, conteneurs, ressources Azure
Cas d’utilisation Performance, exceptions, traces Conformité, gouvernance, corrélation entre ressources
Authentication Chaîne de connexion Identité managée (via DCR/DCE)

Utilisez Application Insights lorsque vous avez besoin de fonctionnalités APM telles que le suivi des demandes, le mappage des dépendances et le profilage des performances. Utilisez Log Analytics lorsque vous avez besoin d’une journalisation centralisée sur plusieurs ressources avec des exigences de conformité d’entreprise.

Contenu connexe

  • Last updated on