Présentation des contextes implicites dans LogTape .0

Je suis ravi d'annoncer la sortie de LogTape 0.7.0, qui introduit des contextes implicites, une nouvelle fonctionnalité puissante qui facilite plus que jamais l'ajout d'informations contextuelles à vos journaux sur votre application entière.

Que sont les contextes implicites ?

Imaginez que vous gérez une requête HTTP dans votre application. Vous souhaitez que chaque message de journal généré lors du traitement de la demande inclue l'ID de la demande, quel que soit l'endroit où le journal est créé dans votre base de code. Avant les contextes implicites, vous devrez :

1. Transmettez l'ID de la demande à chaque appel de fonction
2. Créer un nouveau logger avec contexte pour chaque module
3. Ou utilisez des variables globales (qui ont leurs propres problèmes)

Avec les contextes implicites, vous pouvez désormais définir le contexte au début de votre gestionnaire de requêtes, et chaque message de journal dans ce contexte d'exécution inclura automatiquement ces informations. Voici un exemple simple :

function handleRequest(requestId: string) {
  withContext({ requestId }, () => {
    // Any log message in this function or any function it calls
    // will automatically include the requestId
    processRequest();
  });
}

function processRequest() {
  // Note that we don't need to pass the requestId explicitly
  getLogger("processor").info(
    "Processing request: {requestId}"
  );
}

Comment ça marche ?

Les contextes implicites utilisent les mécanismes de stockage contextuel local du runtime sous-jacent (comme AsyncLocalStorage de Node.js) pour conserver les informations contextuelles tout au long de l'exécution de votre code. Cela signifie que le contexte est correctement maintenu même lors d'opérations asynchrones.

Pour activer les contextes implicites dans votre application, vous devez configurer LogTape avec un stockage local contextuel :

import { AsyncLocalStorage } from "node:async_hooks";
import { configure } from "@logtape/logtape";

await configure({
  // ... other settings ...
  contextLocalStorage: new AsyncLocalStorage(),
});

Contextes imbriqués et priorité

L'une des fonctionnalités puissantes des contextes implicites est qu'ils peuvent être imbriqués. Lorsque vous imbriquez des contextes, le contexte interne hérite et peut remplacer les valeurs du contexte externe :

function handleRequest(requestId: string) {
  withContext({ requestId, stage: "request" }, () => {
    // stage is "request" here
    processUser(1234);
  });
}

function processUser(userId: number) {
  withContext({ userId, stage: "user" }, () => {
    // stage is "user" here, but requestId is still available
    getLogger("processor").info(
      "Processing user: {userId} for request: {requestId}"
    );
  });
}

Lorsqu'il s'agit de résoudre les valeurs de contexte, LogTape suit un ordre de priorité clair :

1. Les propriétés explicites dans le message de journal ont la priorité la plus élevée
2. Le contexte explicite défini via Logger.with() est la deuxième priorité
3. Le contexte implicite défini via withContext() a la priorité la plus basse

Prise en charge de l'exécution

Depuis octobre 2024, les contextes implicites sont pris en charge dans :

• Node.js
• Déno
• Chignon

Les navigateurs Web ne prennent pas encore en charge les contextes implicites, car ils attendent la mise en œuvre de la proposition TC39 Async Context.

Cas d'utilisation

Les contextes implicites sont particulièrement utiles pour :

1. Traçage des demandes : ajoutez des ID de demande, des ID d'utilisateur ou des ID de session à tous les journaux d'une demande
2. Surveillance des transactions : suivez les identifiants de transaction sur plusieurs opérations
3. Contexte d'erreur : assurez-vous que les journaux d'erreurs contiennent toujours des informations contextuelles pertinentes
4. Surveillance des performances : ajoutez des informations de synchronisation sur plusieurs opérations
5. Contexte du locataire : dans les applications multi-locataires, suivez les informations sur les locataires dans toutes les opérations

Meilleures pratiques

Lorsque vous utilisez des contextes implicites, tenez compte de ces bonnes pratiques :

1. Utiliser des contextes implicites pour les informations qui appartiennent réellement à l'ensemble du contexte d'exécution
2. Gardez la légèreté des données contextuelles : n'oubliez pas qu'elles sont transmises tout au long de l'exécution
3. Utilisez des noms de clés significatifs et cohérents dans votre application
4. Envisagez d'utiliser TypeScript pour garantir la cohérence de la structure du contexte
5. Documentez la structure de contexte attendue pour votre application

Guide de migration

Si vous utilisez déjà LogTape, la mise à niveau pour utiliser des contextes implicites est simple :

1. Mise à jour vers LogTape 0.7.0
2. Ajoutez un stockage contextuel local à votre configuration LogTape
3. Identifier les endroits où le contexte est transmis manuellement
4. Remplacer par les appels withContext() aux limites appropriées

Conclusion

Les contextes implicites dans LogTape 0.7.0 offrent un moyen puissant d'ajouter des informations contextuelles à vos journaux sans encombrer votre code ni transmettre manuellement le contexte via votre pile d'appels. Ils sont particulièrement utiles dans les services Web, les API et autres applications où le suivi du contexte entre les opérations est important.

Je suis impatient de voir comment vous utiliserez cette fonctionnalité pour améliorer la journalisation et l'observabilité de votre application. Essayez-le et dites-moi ce que vous en pensez !

Pour plus d'informations, consultez la documentation complète sur les contextes implicites.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!