Skip to content

Monitoring Hooks

Nina Ceban Ciocanu edited this page Aug 23, 2024 · 8 revisions

Alloy exposes some monitoring hooks which can be used to tap into system events. This is useful for developing debugging tools and to capture Alloy logs.

Alloy will look for an array of objects in a global variable called __alloyMonitors. To capture all Alloy events, you'll want to define monitors before the alloy code is loaded. Each monitor method captures an event in Alloy. Following is an example page with a monitor defined:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Title</title>
  <script>
    window.__alloyMonitors = window.__alloyMonitors || [];
    window.__alloyMonitors.push({
      onInstanceCreated(data) {
        // data.instanceName
        // data.instance
      },
      onInstanceConfigured(data) {
        // data.instanceName
        // data.config
      },
      onBeforeCommand(data) {
        // data.instanceName
        // data.commandName
        // data.options
      },
      // Added in version 2.4.0
      onCommandResolved(data) {
        // data.instanceName
        // data.commandName
        // data.options
        // data.result
      },
      // Added in version 2.4.0
      onCommandRejected(data) {
        // data.instanceName
        // data.commandName
        // data.options
        // data.error
      },
      onBeforeNetworkRequest(data) {
        // data.instanceName
        // data.requestId
        // data.url
        // data.payload
      },
      onNetworkResponse(data) {
        // data.instanceName
        // data.requestId
        // data.url
        // data.payload
        // data.body
        // data.parsedBody
        // data.status
        // data.retriesAttempted
      },
      onNetworkError(data) {
        // data.instanceName
        // data.requestId
        // data.url
        // data.payload
        // data.error
      },
      onBeforeLog(data) {
        // data.instanceName
        // data.componentName
        // data.level
        // data.arguments
      }
      onContentRendering(data) {
        // data.instanceName
        // data.componentName
        // data.payload
        // data.status
      },
      onContentHiding(data) {
        // data.instanceName
        // data.componentName
        // data.status
      }
    });
  </script>
  <script>
      !function(n,o){o.forEach(function(o){n[o]||((n.__alloyNS=n.__alloyNS||
      []).push(o),n[o]=function(){var u=arguments;return new Promise(
      function(i,l){n[o].q.push([i,l,u])})},n[o].q=[])})}
      (window,["alloy"]);
    </script>
    <script src="alloy.js" async></script>
</head>
<body>
  <h1>Monitor Test</h1>
</body>
</html>

Parameter documentation:

  • data.instanceName - The name of the global variable where the instance is stored.
  • data.instance - The instance function used to call commands.
  • data.config - The computed configuration. This is the options passed to the configure command with all the defaults added.
  • data.commandName - The executed command name.
  • data.options - The options passed to the command.
  • data.result - The result of the command.
  • data.requestId - The requestId generated by Alloy to enable debugging downstream.
  • data.url - The requested url.
  • data.payload - The payload object that will be converted to JSON and sent in the post body of the request.
  • data.body - The response body as a string
  • data.parsedBody - The parsed response body as an object. Undefined if there was an error while parsing the response body.
  • data.status - The integer response code.
  • data.retriesAttempted - The number of retries attempted when sending the request. Zero means it was successful on the first try.
  • data.error - The error message returned from the browser's network call (fetch in most cases).
  • data.componentName - The name of the component that generated the log message. (Optional)
  • data.level - The log level. ("log", "info", "warn", or "error")
  • data.arguments - The arguments of the log message.
  • data.status - The Personalization component notifies the status of rendering, it can have different values, like: rendering-started, no-offers, rendering-failed, rendering-succeeded, rendering-redirect.

Specifying monitors when using the NPM package

When using the NPM package, monitors can be specified in the createInstance function like this:

var monitor = {
  onBeforeCommand(data) {
    console.log(data);
  },
  ...
};
var alloyLibrary = require("@adobe/alloy");
var alloy = alloyLibrary.createInstance({ name: "alloy", monitors: [monitor] });
alloy("config", { ... });
alloy("sendEvent", { ... });

Monitors can also be specified using the global array window.__alloyMonitors as before.