Performance debugging tools for Constellation applications

Debugging DX API interactions focuses on optimizing server-client communication and identifying network-related performance bottlenecks.  

The Tracer Tool

The Tracer tool is a key performance debugging instrument for Constellation applications, providing detailed insights into server-side processing and DX API interaction timing.

Constellation applications operate on a stateless architecture, where each user action triggers a separate DX API call. This predictable request pattern allows the Tracer tool to capture and analyze performance characteristics across the full processing cycle. As a result, developers can pinpoint whether performance issues originate from authentication overhead, Rule processing inefficiencies, setup operations, core business logic, or response generation processes.

To support this analysis, it’s important to understand the concept of a Step Page, which plays a key role during Rule execution. A Step Page in Pega Platform is a reference to a clipboard page that is available to an activity or to a new page created by a Step. Each Step in an activity can have a designated Step Page, which becomes the primary page for the duration of the Step's execution. The Tracer tool can be used to open the current Step Page of any Rule that is run during a Constellation DX API call, or it can be set to watch for a particular Page. 

To trace a specific DX API, open the corresponding Service REST rule in Dev Studio and click on Trace from the Actions menu. Run the use case from the Constellation Portal.

As shown in the following image, the Trace button can be found in the Actions menu of Dev Studio:

To trace Views and investigate the View metadata being passed back to the client, enable the View Rules setting in the Tracer tool configuration. 

As shown in the following image, you must open the Tracer tool's settings and select the View Rules checkbox for the Tracer to capture the relevant information:

Click on View Start entry in tracer to access metadata, context metadata, and dependencies for the View.

In the following image, the steps to access metadata are shown:

The following Tracer operations are particularly valuable for Constellation performance analysis: 

• Full trace execution for complete requestor session performance analysis, capturing the entire interaction lifecycle and enabling comprehensive performance assessment across multiple API calls.
• Service REST Rules tracing for debugging DX API calls, providing detailed insights into API performance characteristics and timing analysis. This functionality proves especially valuable during Service REST simulation scenarios, allowing developers to test performance under controlled conditions.
• Current Step page access for any Rule executed during a Constellation DX API call, enabling developers to examine processing states and performance bottlenecks at the individual Rule level.
• Page watching functionality that can be configured to monitor specific pages during API interactions, providing targeted performance analysis for critical application components.

For enhanced clarity in complex debugging scenarios, the Tracer results window groups events by request ID. This organizational approach proves essential for Constellation applications because multiple requests can be active simultaneously, each with distinct performance characteristics that require individual analysis and optimization consideration.

As shown in the following image, the Tracer results window groups events by request ID:

For enhanced API performance debugging, configure the DebugPegaAPI dynamic system setting to true, as shown in the following figure:

When set to true, this option logs additional fields in the Pega API Rest Service Info statements, helping to debug Page instructions and field level security.

When the DebugPegaAPI Rule is active, the following information is saved into the Pega log files:

• Input values used in the request body of the DX API calls
• Actions performed by the DX API
• Fields in the View where your DX API encounters errors and exceptions
• Descriptions of the cause for errors and exceptions
• Error codes and exception numbers

Browser DevTools

Modern browsers provide powerful built-in debugging capabilities essential for Constellation performance analysis. These tools offer direct access to the client-side execution environment where performance bottlenecks often occur.

Browser DevTools can be accessed by pressing F12 in Chrome, Firefox, or Edge. Several tabs provide specific performance debugging capabilities: 

• Application Tab: Allows inspection of items cached in Local and Session storage.
• Console Tab: Displays the working scripts on the web page and allows execution of debugging commands. Key performance debugging commands include: 
  • PCore.getDataPageUtils() - Lists cached Data Pages in the application's datastore for performance analysis. Data Pages in Constellation applications are cached on the client side within the browser's datastore. Performance issues often stem from inefficient data caching or excessive data retrieval.
  • Performance timing commands for measuring client-side execution:
    • console.time('label') and console.timeEnd('label') - Measure execution duration for specific operations.
    • console.timeLog('label') - Logs intermediate timing checkpoints during processing.
    • performance.now() - Provides high-resolution timestamps for precise performance measurements.
    • performance.mark() and performance.measure() - Create custom performance markers for detailed analysis.
• Network Tab: Monitors network requests and API interactions between the client and server, providing visibility into DX API communication patterns. Shows DX API calls (select filtering by Fetch/XHR) with detailed request and response information. To effectively use this tab for debugging, clear the network log before performing the actions you want to debug, then execute your Constellation application workflow while monitoring the API calls. Pay attention to the payload sizes, response times, and status codes of DX API endpoints. You can examine specific API calls by clicking on individual requests to view detailed timing information, request headers, and response data. This analysis helps identify delays in data fetching, oversized payloads, and inefficient API interaction patterns that impact overall application performance. The DX API calls in the Tracer tool should match the DX API calls that show up in the Network trace in the browser's DevTools.

Note:

In the following figure, the purpose of the Network tab (1) is to show all network interactions issued by the browser. Self-discovering Constellation begins with observing the DX API calls made by Constellation and then observing the JSON data that is exchanged in each of them.

XHR is an abbreviation for XMLHttpRequest, an underlying library that client-side code uses to perform ad-hoc HTTP requests when running code. 

The Fetch/XHR filter (2) is useful for showing the DX API calls without showing other types of content retrieved by your browser. On the left of item 3 is a Clear icon that removes all the events captured on the Network tab. 

In the following image, the location of these tabs within the Chrome browser's DevTools menu is shown:

Debugging client-side interactions addresses React component rendering, Redux state management, and UI responsiveness optimization.

React DevTools 

React DevTools is an open source browser extension providing React-specific performance debugging capabilities. Available for Chrome, Firefox, and as a standalone application, this tool enables developers to: 

• Monitor component re-render performance and frequency 
• Inspect the React component hierarchies
• Analyze component lifecycle performance 
• Profile component rendering times and optimization opportunities 

React DevTools integrates with browser DevTools, adding a dedicated React tab called Components with performance profiling capabilities specifically designed for React-based applications like Constellation. 

Redux DevTools 

Redux DevTools is a powerful browser extension for debugging Redux state management performance. It is particularly valuable for understanding Constellation's client-side data management. Redux tools help developers inspect and track the state of their application over time, view dispatched actions, and analyze state changes. Redux DevTools greatly simplifies debugging complex state logic by providing a visual interface to track and replay actions, inspect the Redux store, and monitor state mutations.

The following table contains links to the extensions for your preferred browser:

The UI Inspector

The UI Inspector is a built-in Pega Platform tool that enables you to select UI components on your screen to gain insight about their place in the UI hierarchy. It also lets you visualize information about the Constellation UI components, including metadata, field properties, and View properties.

Check your knowledge with the following interaction: