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
• loadresource – tracks what fragments and JSON API endpoints are loaded for the site and how much time they take to load.
• 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
• 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.
• navigate - Helps discover internal navigation paths.
• enter - Helps discover external referrers. The value direct subsumes visitors entering the URL directly into their address bar, following browser bookmarks, or opening the page from iOS applications.
• language - content languages that are used and what the users choose to select as their preferred language.
• ally - tracks what accessibility features are detected on the site.
• consent - consent provider enabled on the site and how user interacts with it.
• acquisition - all the inorganic traffic sources for the site.
• redirect - the number of hops it took to reach the destination URL the user was looking for.
• 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.
• 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
• search – a site search on the page is performed, typically using a search input field
• fill - indicates that a form field was filled by the user. The source property contains the css selector of the field that was filled. The data that user entered is not captured.
• 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.