Troubleshooting Scenarios with NED ToolsSummaryThis troubleshooting guide offers common scenarios where using this tool would be impactful and how to maximize its benefits such as: Focusing on Look and FeelFocusing on BehaviorTroubleshooting Frontend PerformanceComparing profilesFollow-up Troubleshooting ReleaseNED Tools are compatible with Seismic-based frontends from the San Diego release onwards. Workspaces would be a typical functionality with a lot of Seismic code in it. *Please note that NED Tools do not work with UI16-based pages. InstructionsFor a basic understanding of how NED Tools work and how to use them, consider reviewing Using Next Experience Developer Tools [ServiceNow Dev site] So Much Data, Where Do I Start The NED Tools' new Home tab is designed to assist users and developers with their initial troubleshooting steps by introducing a set of Health Indicators. These indicators visualize common errors that may occur in ServiceNow frontends. Each Health Indicators section displays relevant health indicator cards, with the total components or events card always visible and others appearing if issues are detected. Each health indicator includes a help section describing the issue and typical root causes. By clicking the "Details" button, users can navigate to the specific components or events identified as the source of the issue. For instance, the "Undelivered Events" Health Indicator leads to the Events tab, highlighting all events that were not delivered. Component Health Indicators Total components: Shows the total count of Next Experience UI Framework components on a page. Always visible, even if the total count is zero.Broken selectable props: Counts all broken selectable props on a page, displayed only if any are present. Broken properties disrupt value flow between components, causing inconsistencies and compromising user experience.Components with same ID: Visible if multiple components share the same ID, showing the total count. Shared IDs disrupt application structure, causing event handling conflicts and rendering issues.State too big: Visible if a component's state has more than 1000 nodes (depth and width combined), showing the total count of such components. Oversized states slow down rendering and increase management complexity.Excessive DOM Depth: Visible if a component's DOM depth exceeds 32, showing the total count of such components. Excessive depth degrades performance, causing longer rendering times and decreased UI responsiveness. Events Health Indicators Total events: Shows the total count of events on a page. Always visible, even if the total count is zero.Undelivered Events: Counts the number of undelivered DOM events on a page, showing the total count if any are present. These occur due to undefined event names or components disconnecting before events are handled, causing broken interactions and unresponsive features.Events Took Too Long To Process: Displays the total count of events taking longer than 50ms to process, visible when such delays occur. Long processing times, caused by complex re-renders, resource-intensive operations, or synchronous tasks, make the application appear sluggish and disrupt user interactions. Scenario 1: Focusing on Look and Feel When dealing with frontend issues, especially those related to component behavior and appearance in Seismic-based pages (predominantly Workspaces), it's important to understand the role of properties (props) and state. These elements play a pivotal role in shaping how components behave and look on your web application. Understanding Properties and State: Properties: These are used for data communication from parent to child components, defining how components look and behave. For instance, props can control whether an element should be enabled or disabled, visible or hidden.State: Component-specific data that changes over time, often driven by incoming actions. In essence, state changes are responsible for reflecting updates in the user interface, ensuring that your application behaves as expected. Starting a Troubleshooting Session: Now that we understand the significance of props and state, let's dive into the practical side of troubleshooting. Begin by navigating to the Seismic-based page where you've encountered frontend issues.Access the Developer Tools within your web browser.Locate and click on the `🔎 Next UI Inspector` tab.From the displayed DOM, select the specific component that's causing the issue.Ensure the `Properties` tab is selected in the right-hand panel. Troubleshooting Props and State: When components misbehave or look different than expected, it's often due to discrepancies in their properties or state. Here's how to address these issues effectively: For Component Experts: Assess the component's properties and whether they align with the current state of the page. Sometimes, properties might consist of composite objects, so don't forget to expand them to see the actual values in nested objects or arrays. For Non-Experts: If you're not familiar with the implementation details of the component, a practical approach is to compare properties with an unaffected instance. You can achieve this by copying and comparing the JSON-formatted text. Any differences should stand out as a concern. Once you've identified a component whose props don't match your expectations, you can use the tool to manually update them (double-click). This is a useful way to validate that the changes yield the desired output. In such cases, it makes sense to reach out to the owner of the parent component since props are typically passed down from parent to child components. A similar approach applies to state variables. However, state changes are typically initiated through actions (as an action handler). That means it's essential to verify that the expected action, which triggers the state change, was indeed received (more about that in the Behavior-based troubleshooting). If not, communicating with the team responsible for sending or handling actions is a logical next step in resolving issues related to state changes. Sometimes the action may be dropped due to a specific DOM update (e.g. the originating component moves in the DOM). Bullet 4. in the Behavior-based troubleshooting describes how re-dispatching specific action can help verify that the logic is present, but the code may be experiencing race condition. ℹ️ One of the new Health Indicators, "Broken Selectable Props" (which allows the definition of component properties as a subset of other component's properties), indicates when a property chain reference is broken. Be sure to check the Home tab and review all the components identified in that Health Indicator. Scenario 2: Focusing on Behavior Actions serve as the primary method for components to signal events within the application, typically in response to user interactions. When troubleshooting, it's essential to address issues related to action flow. Starting an Event Troubleshooting Session: Go to the Seismic-based page.Open Developer Tools.Navigate to the `🔎 Next UI Inspector` tab.Switch to the `Events` tab in the right-hand side menu bar.Ensure you can view the list of all dispatched events. Troubleshooting Using Events A typical workspace page may have an extensive list of events after loading. To narrow down the results to relevant ones, consider the following approaches: 1. Clear the list before triggering the problematic action (e.g., just before clicking the Save button). This often results into first few actions being a sequence directly related to the issue. 2. Apply filters using the filter icon. Predominantly, filtering by actions dispatched by specific components or by a specific action name proves effective. 3. After refining the list to a few key events, inspect each one to ensure the payload aligns with expectations for the given situation. If you're not an expert, try using a comparison approach between affected and unaffected instances as described in the section above. If a specific action is missing from the list, consider dispatching it from the NED Tools interface (using the `⨁` icon in the status bar). To define the action payload accurately, you may, again, copy data from a healthy instance. 4. A similar scenario applies when an action that should produce a particular output/state exists in the list, but the UI state doesn't reflect it. In this case, consider re-dispatching that specific action directly from the list using the `↻` icon. If dispatching or re-dispatching brings the UI to the expected state, it's advisable to reach out to both the component owner that dispatches the action and the component owner that should receive it. The root cause may lie with either of them and the issue may be due to a race condition. A simple example may be a component dispatches an action (e.g. Save action after button click in the modal form) and then the whole form hides (disconnects and reconnects in different location in the DOM). Because all actions dispatched by disconnected components are dropped from the execution queue, the Save action is never executed although the form disappeared. Starting a Trace Troubleshooting Session: Go to the Seismic-based page.Open Developer Tools.Navigate to the `🔎 Next UI Inspector` tab.Switch to the `Trace` tab in the right-hand side menu bar.❗️Reload the page to propagate the intent to start tracing to the page/backend.Ensure you can view the list of all captured traces. Troubleshooting Using Traces A typical workspace page may have an extensive list of traces after loading. To narrow down the results to relevant ones, consider the following approaches: 1. Clear the list of traces before triggering the problematic action (e.g., just before clicking the Save button). This often results into first few actions being a sequence directly related to the issue. 2. Apply filters using the filter icon. Predominantly, focusing on client or server traces may lead to a smaller list of traces: 3. Explore remaining traces. Traces are a perfect tool to visualize a sequence of events that lead to a new state. They start from a root and every event is a new child within its parent. This is how to read trace waterfall: First line: The initial event that caused this waterfall of events.Bars: A series of bars that go down from the first line. The length of each bar shows how much it affects the overall timing.Color coding: The bars are color-coded to differentiate between frontend, backend and infrastructure execution.Leaf lines: Actual execution time for that particular step.Intermediate lines: The cumulative timing of all the contributing events within this step. 4. You can troubleshoot functional issues by using traces to follow the flow of events and actions within your application. Traces provide a detailed timeline of function calls, network requests, and state changes, helping you pinpoint discrepancies between expected and actual behaviors. This allows you to identify where a failure occurs, facilitating accurate diagnosis and resolution. Additionally, traces help you visualize interactions between different components and services, which is especially useful in our complex applications. By analyzing trace waterfall, you can observe data flow (click on the `i` icon on every line to see additional data) and component interactions, identifying bottlenecks and functional problems. This all-in-one view enhances the ability to ensure all parts of the application work as expected. Scenario 3: Troubleshooting Frontend Performance Using Traces Traces (see details about how to navigate to Traces in the section above) can be also used to troubleshoot performance problems by analyzing the detailed timeline of events and actions within your application. Traces provide a clear view of function calls, network requests, and state changes, allowing you to identify slow operations and performance bottlenecks. Each line in a trace represents a cumulative value of all its children, helping you understand the total time spent on nested operations. This cumulative view enables you to pinpoint specific areas where performance improvements are needed. By examining traces, you can observe how different components and services interact, which is crucial for identifying inefficient processes. The cumulative values help you quickly locate the most time-consuming operations, making it easier to pinpoint source of performance degradation and prioritize optimization efforts. In this figure, we can clearly see what parts of macroponent's render event are taking the most, which is what we should be focusing on. Additionally, traces can be used to compare the performance of code changes over time. We do not support built-in traces comparison feature just yet, but by analyzing traces for the same user action in different releases may help point on the source of degradation. Scenario 4: Troubleshooting Frontend Performance Using Profiler NED Tools provide a dedicated `📈 Next UI Profiler` tab to troubleshoot frontend performance issues. Starting a Troubleshooting Session: Click on the Reload and record icon (`⟳`) to initiate a new profile recording.Wait for the page to load (ensure page content is stable, and events are not increasing significantly).Click `[Done]` to stop recording. The newer versions of NED Tools have a feature to auto-stop after the page is fully loaded. Analyzing Performance with Flamecharts Flamecharts are powerful tools for web performance profiling. They visually represent the call hierarchy and execution flow. Flamecharts help pinpoint performance bottlenecks and optimize your frontend code. Here's how to use them: Boxes represent components' execution time, nested to show the call hierarchy.Wide boxes indicate functions that consume significant time.Focus on functions that spend time without calling nested components.Examine nesting to identify components calling others excessively. Scenario 4: Comparing Profiles Comparing performance profiles can give direct insights into what changed exactly and where. This is an option user may use when we can get previous performance profiles (e.g. from a last known working version, from previous family release). Launch Compare Mode: Record and save profile from a last working version. Let's call it a baseline profile.Reload and record the page on a version that has performance regression.Click `[Compare]` button and import the baseline profile from your disk, set the freshly recorded one as a target.Confirm by `[Compare]` button in the modal. Compare Profiles Pane The comparison panel provides an overview of metrics, including the overall difference and the differences for five selected events (`RENDER_END`, `EFFECT_START`, `UPDATE_STATE`, `UPDATE_PROPERTIES`, and `DISPATCH`). The table below the metrics section shows detailed information for all tagnames. Each cell represents the difference for a specific component and event, calculated as: $$ \text{{target}} - \text{{baseline}} $$ Positive numbers indicate degraded performance, while negative numbers indicate an improvement. Clicking on a particular row expands it to display absolute numbers for the corresponding component and events. Scenario 5: Follow-up Troubleshooting Once we sort the `RENDER_END` column descending, first line should identify a component that potentially has the largest performance impact (assuming that rendering and re-rendering is the most expensive operation). To narrow down results to only components that have changed between these 2 runs, we can select `Non Zero` option in the View dropdown. To understand more about the reasons behind increased render counts, let's narrow down the results to the component identified above. Click `[Exit compare]`In the 3rd pane, click the `Events` tabFilter down the table to only `RENDER_END` using the `⋮` icon in the Event Type columnFilter down the table to only the component identified above using the `⋮` icon in the Component Tag column. Once the table shows only relevant records, we can flip between the profiles using the top-most `[Baseline]` profile selector. When the target profile is selected, we will see all the extra renders together with reasons why they were initiated.