Developing Operational Telemetry in AEM

Adobe Experience Manager uses Operational Telemetry to diagnose usage and performance of web sites running on Adobe Experience Manager. As a developer, you can use the Operational Telemetry APIs to observe additional events about how your site is used.

This document describes the key concepts of Real Use Monitoring, details the client-side APIs that you can use to send additional data to the Operational Telemetry collection service and alludes to the fact that the data can be queried.

How to add Operational Telemetry Instrumentation to your Site

If your website is not built using AEM Edge Delivery Services, it is recommended to set up Real Use Monitoring in standalone mode. To set up , simply add the following script to your pages.

<script defer type="text/javascript" src="https://rum.hlx.page/.rum/@adobe/helix-rum-js@^2/dist/rum-standalone.js"></script>

For better performance, it is recommended loading the script after the Largest Contentful Paint (LCP) event

Key Concepts

Every data point collected by Operational Telemetry is made up of following key parts:

• id – a unique identifier, generated by the Operational Telemetry library that identifies the current page view
• checkpoint – a named event in the sequence of loading the page, and interacting with the page
• source – identifies the DOM element that caused a particular interaction (optional)
• target – identifies an external resource or link that is the subject of an interaction (optional)

Checkpoints

By convention, checkpoint names are lowercase letters, without any special characters. The most common checkpoints used in Adobe Experience Manager projects are:

• top – the page loading sequence has begun and first JavaScript code is being executed by the page. This event fires even before blocks are decorated or content is visible
• load – corresponds to the Window: load event in JavaScript and is fired when the whole page has loaded, including all dependent resources such as stylesheets, scripts, iframes, and images.
• cwv – indicates that either the page is ready to collect Core Web Vitals (CWV) readings or that either the LCP, CLS, or FID CWV reading has been recorded. As these readings are asynchronous, multiple of these checkpoints can be passed during one page view
• lazy – the page is ready for lazy loading of non-essential resources as part of the Lazy stage of the ELD cycle.
• lcp – the Largest Contentful Paint (LCP) has been made by the browser, this is usually the most prominent image on the page
• viewblock – a block has scrolled into view and there is a chance that the content of that block is seen. The class name of the block will be shared in the source property.
• viewmedia – an image or video has scrolled into view and there is a chance that the content of that block is seen. The URL of the image or video is shared in the target property.
• click – a click event has been triggered, not just on links or buttons. If the element clicked is a link, then the link target is recorded in the target property. The source property contains information about which element of the DOM was clicked.
• experiment – an experiment (challenger or control) has been presented, which can be an A/B test or targeted content.
• error – a JavaScript error has occurred on the page and has not been handled by the application code. This usually indicates a bug.
• 404 – a 404, page not found page has been served. This checkpoint can indicate missing content or broken links
• unsupported – the page has been opened by a browser that does not support the more advanced Operational Telemetry collection features. This checkpoint is fired by less than a tenth of a percent of all page views. There is also the related noscript checkpoint for browsers that do not have JavaScript enabled, which is even less common.
• search – a site search on the page is performed, typically using a search input field
• formsubmit – a form is submitted on the page. The form action is recorded in the target property, while the source property keeps information of which form of the page was submitted.
• leave – corresponds to the Window: pagehide event or to Document: visibilitychange event (whichever happens first) if the new document.visibilityState is hidden. This checkpoint is triggered when the page is not visible anymore, e.g. when the browser is closed, or when switched to a different tab in the browser.