Partager via

Configurer la journalisation dans le Kit de développement logiciel (SDK) Azure pour Java

  • Article

Cet article fournit une vue d’ensemble de l’activation de la journalisation dans des applications qui utilisent le kit de développement logiciel (SDK) Azure pour Java. Les bibliothèques clientes Azure pour Java offrent deux options de journalisation :

  • Un framework de journalisation intégré à des fins de débogage temporaire.
  • Prise en charge de la journalisation à l’aide de l’interface SLF4J.

Nous vous recommandons d’utiliser l’interface SLF4J, car elle est bien connue dans l’écosystème Java et elle est bien documentée. Pour plus d’informations, consultez le manuel de l’utilisateur SLF4J.

Cet article contient des liens vers d’autres articles qui traitent de nombreux frameworks de journalisation Java populaires. Ces autres articles fournissent des exemples de configuration et expliquent comment les bibliothèques clientes Azure peuvent utiliser les frameworks de journalisation.

Quelle que soit la configuration de journalisation que vous utilisez, la même sortie de journal est disponible dans les deux cas, car toute la sortie de journalisation dans les bibliothèques clientes Azure pour Java est routée via une abstraction ClientLogger azure-core.

Le reste de cet article décrit en détail la configuration de toutes les options de journalisation disponibles.

Activer la journalisation des requêtes/réponses HTTP

La journalisation des requêtes et des réponses HTTP est désactivée par défaut. Vous pouvez configurer les clients qui communiquent avec les services Azure via HTTP pour écrire un enregistrement de journal pour chaque demande et réponse (ou exception) qu’ils reçoivent.

Si vous utilisez OpenTelemetry, envisagez d’utiliser le suivi distribué au lieu de journaliser les requêtes HTTP. Pour plus d’informations, consultez Configurer le suivi dans le Kit de développement logiciel (SDK) Azure pour Java.

Configurer la journalisation HTTP avec une variable d’environnement

Vous pouvez utiliser la variable d’environnement AZURE_HTTP_LOG_DETAIL_LEVEL pour activer les journaux HTTP globalement. Cette variable prend en charge les valeurs suivantes :

  • NONE: les journaux HTTP sont désactivés. Cette valeur est la valeur par défaut.
  • BASIC: les journaux HTTP contiennent la méthode de requête, l’URL de requête nettoyée, le nombre d’essais, le code de réponse et la longueur du contenu pour les corps de requête et de réponse.
  • HEADERS: les journaux HTTP incluent tous les détails de base et incluent également les en-têtes connus pour être sécurisés à des fins de journalisation, c’est-à-dire qu’ils ne contiennent pas de secrets ou d’informations sensibles. La liste complète des noms d’en-têtes est disponible dans la classe HttpLogOptions .
  • BODY_AND_HEADERS: les journaux HTTP incluent tous les détails fournis par le HEADERS niveau et incluent également les corps de requête et de réponse tant qu’ils sont inférieurs à 16 Ko et imprimables.

Remarque

L’URL de la requête est nettoyée, c’est-à-dire que toutes les valeurs de paramètre de requête sont régérées à l’exception de la api-version valeur. Les bibliothèques clientes individuelles peuvent ajouter d’autres paramètres de requête connus pour être fiables dans la liste verte.

Par exemple, l’URL Stockage Blob Azure signature d’accès partagé (SAP) est enregistrée au format suivant :https://myaccount.blob.core.windows.net/pictures/profile.jpg?sv=REDACTED&st=REDACTED&se=REDACTED&sr=REDACTED&sp=REDACTED&rscd=REDACTED&rsct=REDACTED&sig=REDACTED

Avertissement

La journalisation des corps de demande et de réponse n’est pas recommandée en production, car elles peuvent contenir des informations sensibles, affecter considérablement les performances, modifier la façon dont le contenu est mis en mémoire tampon et avoir d’autres effets secondaires.

Configurer la journalisation HTTP dans le code

Les générateurs de clients Azure qui implémentent l’interface HttpTrait<T> prennent en charge la configuration de journalisation HTTP basée sur le code. La configuration basée sur le code s’applique à des instances clientes individuelles et fournit davantage d’options et de personnalisations par rapport à la configuration des variables d’environnement.

Pour configurer les journaux, transmettez une instance de HttpLogOptions à la httpLogOptions méthode sur le générateur client correspondant. Le code suivant montre un exemple pour le service App Configuration :

HttpLogOptions httpLogOptions = new HttpLogOptions()
        .setLogLevel(HttpLogDetailLevel.HEADERS)
        .addAllowedHeaderName("Accept-Ranges")
        .addAllowedQueryParamName("label");

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .httpLogOptions(httpLogOptions)
        ...
        .buildClient();

Ce code active les journaux HTTP avec des en-têtes et ajoute l’en-tête Accept-Ranges de réponse et le label paramètre de requête aux listes d’autorisation correspondantes. Après cette modification, ces valeurs doivent apparaître dans les journaux produits.

Pour obtenir la liste complète des options de configuration, consultez la documentation HttpLogOptions .

Enregistreur d’événements par défaut (pour le débogage temporaire)

Comme indiqué précédemment, toutes les bibliothèques clientes Azure utilisent SLF4J pour la journalisation, mais il existe un enregistreur d’événements par défaut, de secours, intégré aux bibliothèques clientes Azure pour Java. Cet enregistreur d’événements par défaut est fourni pour les cas où une application est déployée et que la journalisation est requise, mais il n’est pas possible de redéployer l’application avec un enregistreur D’événements SLF4J inclus. Pour activer cet enregistreur d’événements, vous devez d’abord être certain qu’aucun enregistreur SLF4J n’existe (car il est prioritaire), puis définir la AZURE_LOG_LEVEL variable d’environnement. Le tableau suivant indique les valeurs autorisées pour cette variable d’environnement :

Niveau du journal Valeurs autorisées pour la variable d’environnement
DÉTAILLÉ verbose, debug
INFORMATIONNEL info, , informationinformational
AVERTISSEMENT warn, warning
ERROR err, error

Une fois la variable d’environnement définie, redémarrez l’application pour que la variable d’environnement prenne effet. Cet enregistreur d’événements se connecte à la console et ne fournit pas les fonctionnalités de personnalisation avancées d’une implémentation SLF4J, telles que la substitution et la journalisation dans le fichier. Pour désactiver la déconnexion, supprimez simplement la variable d’environnement et redémarrez l’application.

SLF4J logging

Par défaut, vous devez configurer la journalisation à l’aide d’un framework de journalisation pris en charge par SLF4J. Tout d’abord, incluez une implémentation de journalisation SLF4J appropriée en tant que dépendance de votre projet. Pour plus d’informations, consultez Déclaration des dépendances du projet pour la journalisation dans le manuel de l’utilisateur SLF4J. Ensuite, configurez votre enregistreur d’événements comme nécessaire dans votre environnement, par exemple la définition des niveaux de journalisation, la configuration des classes qui ne se connectent pas, etc. Certains exemples sont fournis via les liens de cet article, mais pour plus d’informations, consultez la documentation de votre infrastructure de journalisation choisie.

Format de journal

Les infrastructures de journalisation prennent en charge la mise en forme et les dispositions personnalisées des messages de journal. Nous vous recommandons d’inclure au moins les champs suivants pour permettre de résoudre les problèmes liés aux bibliothèques clientes Azure :

  • Date et heure avec précision en millisecondes
  • Gravité du journal
  • Nom de l’enregistreur d’événements
  • Nom du thread
  • Message

Pour obtenir des exemples, consultez la documentation relative à l’infrastructure de journalisation que vous utilisez.

Journalisation structurée

Outre la journalisation des propriétés communes mentionnées précédemment, les bibliothèques clientes Azure annotent les messages de journal avec un contexte supplémentaire le cas échéant. Par exemple, vous pouvez voir des journaux au format JSON contenant un az.sdk.message contexte écrit en tant qu’autres propriétés racines, comme illustré dans l’exemple suivant :

16:58:51.038 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP request","method":"GET","url":"<>","tryCount":"1","contentLength":0}
16:58:51.141 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP response","contentLength":"558","statusCode":200,"url":"<>","durationMs":102}

Lorsque vous envoyez des journaux à Azure Monitor, vous pouvez utiliser le langage de requête Kusto pour les analyser. La requête suivante fournit un exemple :

traces
| where message startswith "{\"az.sdk.message"
| project timestamp, logger=customDimensions["LoggerName"], level=customDimensions["LoggingLevel"], thread=customDimensions["ThreadName"], azSdkContext=parse_json(message)
| evaluate bag_unpack(azSdkContext)

Remarque

Les journaux de bibliothèque cliente Azure sont destinés au débogage ad hoc. Nous vous déconseillons de nous appuyer sur le format de journal pour alerter ou surveiller votre application. Les bibliothèques clientes Azure ne garantissent pas la stabilité des messages de journal ou des clés de contexte. À ces fins, nous vous recommandons d’utiliser le suivi distribué. L’agent Java Recommandations application offre des garanties de stabilité pour la télémétrie des demandes et des dépendances. Pour plus d’informations, consultez Configurer le suivi dans le Kit de développement logiciel (SDK) Azure pour Java.

Étapes suivantes

Maintenant que vous savez comment fonctionne la journalisation dans le Kit de développement logiciel (SDK) Azure pour Java, consultez les articles suivants. Ces articles fournissent des conseils sur la configuration de certaines infrastructures de journalisation Java les plus populaires pour utiliser SLF4J et les bibliothèques clientes Java :