Meilleures pratiques de débogage

En règle générale, vous déboguez une règle pendant l’exécution via la journalisation de la console en utilisant la fonction console.log. Pour en savoir plus, lisez console.log() dans MDN Web Docs. Le débogage interactif d’une règle n’est pas disponible au sein de la plateforme Auth0 (bien que l’on puisse utiliser la technique d’automatisation des tests décrite ci-dessous en conjonction avec une fonction externe de débogage interactif des sources; pour en savoir plus, lisez les Meilleures pratiques en matière de test des règles).

L’ajout de suffisamment de commentaires de ligne (par exemple, //) ou de bloc (c.-à-d. /* */) à une règle, en particulier autour des fonctionnalités non évidentes, est inestimable pour le débogage et la compréhension du code, en particulier parce que, dans de nombreux cas, le maître d’œuvre initial d’une règle peut ne pas être la même personne que celle chargée de la maintenir à l’avenir.

Par défaut, la sortie du journal de la console n’est pas disponible à l’affichage pendant une exécution normale. Cependant, vous pouvez utiliser l’extension Journaux Webtask en temps réel pour afficher tous les journaux de la console en temps réel pour toutes les extensions mises en œuvre dans un locataire Auth0, y compris les règles. L’affichage du journal de la console en temps réel fourni par l’extension comprend toutes les sorties console.log, console.error et console.exception. Pour en savoir plus, lisez console.error() dans MDN Web Docs.

Dans un environnement de production, la journalisation de débogage n’est pas souhaitable en permanence; compte tenu des considérations de performance associées aux règles, il ne serait pas prudent de l’activer en permanence. Pour en savoir plus, veuillez lire Meilleures pratiques en matière de performances.

Toutefois, dans un environnement de développement ou de test, la possibilité de l’activer de manière plus continue est beaucoup plus souhaitable. En outre, une journalisation de débogage excessive pourrait créer un « bruit » important, ce qui rendrait l’identification des problèmes encore plus difficile.

Modifier une règle pour activer ou désactiver la journalisation de débogage en fonction de l’environnement serait fastidieux et source d’erreurs. Pour en savoir plus, consultez Meilleures pratiques en matière d’environnement des règles. En revanche, l’objet de configuration de l’environnement peut être utilisé pour mettre en œuvre un traitement conditionnel de la manière suivante :

function NPClaims(user, context, callback) {
    /*
     * This rule (https://auth0.com/docs/rules) is used to derive
     * effective claims associated with the Normalized User Profile:
     *   https://auth0.com/docs/user-profile/normalized/auth0
     */
    var LOG_TAG = '[NORMALIZED_PROFILE_CLAIMS]: ';
    var DEBUG = configuration.DEBUG ? console.log : function () {};
    DEBUG(LOG_TAG, "identities=", user.identities);
    user.user_metadata = user.user_metadata || {};

    //
    user.family_name =
      user.family_name ||
      user.identities.filter(function(identity) {
        /* Filter out identities which do not have anything synonymous with
         * Family Name
         */
        return(
          identity.profileData &&
          identity.profileData.family_name);
      }).map(function(identity) {
        return identity.profileData.family_name;
      })[0];
    DEBUG(LOG_TAG, "Computed user.family_name as '", user.family_name, "'");
      .
      .

    //
    return callback(null, user, context);
  }

Dans l’exemple ci-dessus, une variable de configuration de l’environnement DEBUG a été créée, qui peut être définie sur true ou false en fonction de l’environnement d’exécution (par exemple, production, test, développement). Cette variable permet de déterminer quand la journalisation de débogage est effectuée. En outre, une variable de configuration de l’environnement DEBUGLEVEL, par exemple, pourrait être créée et utilisée pour contrôler le niveau du journal de débogage (par exemple, verbose, medium, sparse).

L’exemple ci-dessus montre également la déclaration d’une fonction nommée. Pour des raisons de commodité, la fourniture d’un nom de fonction - en utilisant une convention de dénomination compacte et unique - peut faciliter l’analyse diagnostique. Les fonctions anonymes rendent difficile, dans les situations de débogage, l’interprétation de la pile d’appels générée à la suite d’une condition d’erreur exceptionnelle, et le fait de fournir un nom de fonction unique permet de remédier à ce problème. Pour en savoir plus, consultez Meilleures pratiques en matière de traitement des erreurs.

L’éditeur de règles dans Auth0 Dashboard permet une vérification rudimentaire de la syntaxe et une analyse de la sémantique des règles. Cependant, aucun provisionnement n’est prévu pour une analyse statique plus complexe du code, telle que la détection d’écrasement, la détection de boucle ou la détection de vulnérabilités. Pour remédier à ce problème, envisagez d’utiliser des outils tiers, tels que JSHint, SonarJS ou Coverity, en conjonction avec les tests de règles dans le cadre de votre processus d’automatisation du déploiement. Pour en savoir plus, lisez les Meilleures pratiques en matière de déploiement.

• Meilleures pratiques de test des règles
• Meilleures pratiques du déploiement
• Meilleures pratiques de la gestion des erreurs
• Meilleures pratiques des performances