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

2025-04-17

Cet article fournit une vue d’ensemble de l’activation de la journalisation dans les 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 SLF4J, car il est bien connu dans l’écosystème Java et il est bien documenté. Pour plus d’informations, consultez le manuel de l’utilisateur SLF4J .

Cet article est lié à d’autres articles qui couvrent la plupart des frameworks de journalisation Java populaires. Ces autres articles fournissent des exemples de configuration et décrivent 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 journalisation est disponible dans les deux cas, car toutes les sorties de journalisation dans les bibliothèques clientes Azure pour Java sont routées via une abstraction azure-core ClientLogger .

Le reste de cet article détaille 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 les détails fournis par le niveau HEADERS et incluent également les corps de requête et de réponse à condition qu'ils soient 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 masquées à l’exception de la valeur api-version. Les bibliothèques clientes individuelles peuvent ajouter d’autres paramètres de requête considérés comme sûrs à la liste blanche.

Par exemple, l’URL de la signature d’accès partagé (SAS) du Stockage Blob Azure 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 méthode httpLogOptions 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 de réponse Accept-Ranges et le paramètre de requête label aux listes d’autorisation correspondantes. Après cette modification, ces valeurs doivent apparaître dans les journaux générés.

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é, toutes les bibliothèques clientes Azure utilisent SLF4J pour la journalisation, mais il existe un enregistreur d’événements par défaut 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 présente les valeurs autorisées pour cette variable d’environnement :

Niveau du journal	Valeurs de variable d’environnement autorisées
DÉTAILLÉ	`verbose`, `debug`
INFORMATIONNEL	`info`, `information`, `informational`
Avertissement	`warn`, `warning`
ERREUR	`err`, `error`

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

La journalisation SLF4J

Par défaut, vous devez configurer la journalisation à l’aide d’une infrastructure de journalisation prise en charge par SLF4J. Tout d’abord, incluez une implémentation de journalisation SLF4J pertinente en tant que dépendance de votre projet. Pour plus d’informations, consultez Déclaration des dépendances de projet pour la journalisation dans le manuel de l’utilisateur SLF4J. Ensuite, configurez votre enregistreur pour qu’il fonctionne comme il se doit dans votre environnement, par exemple en définissant les niveaux de journalisation, en configurant les classes journalisées et celles qui ne le sont 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 az.sdk.message avec un 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 Application Insights 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 :

Partager via