> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging-quickstart-revamp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn about best practices for debugging.

# Debugging Best Practices

## Rule debugging

<Warning>
  The `consoleOut` property is a log output generated by customers within the Auth0 platform through Actions, Rules, Hooks, Extensions, and DB Scripts. 

  Auth0 recommends using the `consoleOut` property for testing and debugging purposes only. You should not log personal data or other sensitive data into the web console or the log output will include such data.
</Warning>

Out of the box, typically, you [debug a rule during runtime](/docs/customize/rules/debug-rules) via console logging by using the `console.log` facility. To learn more, read [console.log() in MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Console/log). There is no interactive debugging of a rule available within the Auth0 platform (though one could employ the testing automation technique described below in conjunction with some external interactive source-debugging facility; to learn more, read [Rules Testing Best Practices](/docs/rules-best-practices/rules-testing-best-practices)).

## Add line comments

Adding sufficient line (i.e., `//`) or block (i.e., `/* */`) comments to a rule, particularly around non-obvious functionality, is invaluable to both code debugging and also code understanding, particularly as there are many occasions where the initial implementer of a rule may not be the same person responsible for maintaining it going forward.

## Real-time Webtask logging

By default, console log output is unavailable for display during normal execution. However, you can [use the Real-time Webtask Logs extension](/docs/customize/extensions/real-time-webtask-logs) to display all console logs in real-time for all implemented extensibility in an Auth0 tenant, including rules. The real-time console log display provided by the extension includes all `console.log` output, `console.error` output, and `console.exception` output. To learn more, read [console.error() in MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Console/error).

## Enable and disable debug logging

In a production environment, debug logging isn’t something that’s desirable all the time; given the performance considerations associated with rules, it would not be prudent to have it continuously enabled. To learn more, read [Performance Best Practices](/docs/troubleshoot/performance-best-practices).

However, in a development or testing environment, the option to enable it on a more continuous basis is much more desirable. Further, excessive debug logging could create substantial “noise”, which could make identifying problems that much harder.

Modifying a rule to enable or disable debug logging dependent on the environment would be messy and prone to error. To learn more, read [Rules Environment Best Practices](/docs/rules-best-practices/rules-environment-best-practices). Instead, the environment configuration object can be leveraged to implement conditional processing in a fashion similar to the following:

```js lines expandable
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);
  }
```

In the example above, a `DEBUG` environment configuration variable has been created, which can be set to `true` or `false` depending on the execution environment (e.g., production, testing, development). The setting of this variable is used to determine when debug logging is performed. Further, a `DEBUGLEVEL` environment `configuration` variable, say, could be created, which could be used to control the debugging log level (e.g., verbose, medium, sparse).

The above example also demonstrates declaration of a named function. For convenience, providing a function name—using some compact and unique naming convention—can assist with diagnostic analysis. Anonymous functions make it hard in debugging situations to interpret the call-stack generated as a result of any exceptional error condition and providing a unique function name addresses this. To learn more, read [Error Handling Best Practices](/docs/troubleshoot/error-handling-best-practices).

### Static analysis

The rule editor in the <Tooltip tip="Auth0 Dashboard-Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> provides some rudimentary syntax checking and analysis of rule semantics. However, no provision is made for more complex static code analysis, such as overwrite detection, loop detection, or vulnerability detection. To address this, consider leveraging the use of third-party tooling—such as [JSHint](https://jshint.com/about/), [SonarJS](https://www.sonarsource.com/products/codeanalyzers/sonarjs.html), or [Coverity](https://www.synopsys.com/software-integrity/security-testing/static-analysis-sast.html)—in conjunction with rule testing as part of your deployment automation process. To learn more, read [Deployment Best Practices](/docs/deploy-monitor/deployment-best-practices).