Enable Tracing to Monitor Endpoint Calls

When your application contains one or more business objects, enable tracing of an object's endpoint requests to diagnose performance bottlenecks.

Tracing tracks all REST requests made when the current user executes CRUD operations or invoke functions on business objects. It provides a visual representation of the operations taking place and the time it took to invoke each REST call—information you can use to locate bottlenecks in your application. You also enable tracing separately for a particular version of your application (development, stage, or live), so you can isolate issues in that version and fine-tune your app for better performance.

To enable tracing for an application:

Click Trace at the bottom of your application window.

Description of the illustration tracing-enable.png
If your app has staged or live versions, select the version you want to enable tracing for.
Click Enable Tracing.

Once tracing is enabled, all REST requests made by the current user are traced, both when running the app using Preview or when making updates in the Data tab. If you selected a staged or live version of your app, endpoint requests made at runtime are traced. (You'll need to be the app designer or a team member assigned to the app to view traces for these runtime requests.)

Click Refresh to view the latest traces.

Description of the illustration tracing-enabled.png

A trace is a collection of operations for an application transaction. When you edit business object data on a page, your application interacts, for example, with the object's GET endpoint to request the data to display, and then with the PATCH endpoint to update the data. You'll see each endpoint request as a separate entry, with the time spent by your application processing the REST request shown in the Request Duration column.

For GET requests, you'll also see an indicator of the maximum response size in the Total Possible Items column. This value is a theoretical maximum number of items in the response payload for the business object and for any child items returned by referenced business objects, for example, in the fields query parameter. It is calculated based on the limit query parameter and the relationships in the request and can help you determine whether you need to take steps to reduce the response size. (Click the Details icon () to view additional performance metrics in the REST Request Info tab.)

Note:
In a cluster with multiple nodes, a REST API request (particularly one made by tools such as cURL or Postman) won't be traced if it was handled by a node other than the one on which you enabled tracing. To avoid this issue, make sure you use the browser on which you enabled tracing to also make your REST requests.

View Trace Details

You can view a particular REST request's trace for details such as span data and elapsed time. Each trace consists of one or more spans and you can drill down an individual trace to view its root span, which is the beginning of a transaction. You can also view Groovy logs if you included the print or println function in custom Groovy code.

To view details of an individual trace:

Click the Details icon () for the REST request you want to view.

The REST request's tracing data is broken down and displayed in different tabs.
Click Spans and Top Elapsed to view the request's tracing data.
- The Spans view shows a Gantt chart that visually represents the steps in the REST request's execution path. You can hover your cursor over each step's bar graph to see the time the step took.
  
  Description of the illustration tracing-details-spans.png
  
  To drill down and see details of a selected span and its children, click a span to select it, then right-click and select Top Elapsed of Selected Span to use the span as the context for the Top Elapsed view.
- The Top Elapsed view shows operations performed during the request. Repetitive operations, for example, repeated calls to the same SQL Select statement or execution of the same Groovy function, are aggregated.
  
  Description of the illustration tracing-details-topelapsed.png
You can filter operations in your Spans and Top Elapsed views by selecting Groovy or Database in the drop-down list when in the Spans or Top Elapsed tab.
Click REST Request Info to view a summary of the REST request.

Description of the illustration tracing-details-restrequestinfo.png

For GET requests, you can view additional Performance Metrics to get a breakdown of the Total Possible Items column, which provides a theoretical maximum number of items in the response payload based on limit or expand query parameters or any accessors in the fields query parameter:

Description of the illustration tracing-details-restrequestinfo-performance.png

Use these metrics to determine whether a request that does adequately in testing might have a performance issue with a different data set (for example, live). Because the ideal response size for any request is the smallest possible size that contains all the information the client needs, you can take steps to reduce the response time (say) by requesting less data or by using pagination (where multiple smaller requests using a lower limit query parameter and incrementing the offset query parameter may help).
If you included log messages in your Groovy scripts (for example, by adding print or println statements), click Groovy Logs to view the messages your script has generated.

Description of the illustration tracing-details-groovylogs.png

Manage Tracing to Control Disk Usage

When tracing is enabled for an app, all its trace files are stored on Visual Builder server. To avoid disk-usage issues on the server's file system, Oracle sets a maximum disk space limit for all trace files. Once this limit is reached, the oldest trace files are removed to make way for new trace files.

Here are some options to help you manage your app's trace files:

Deselect Enable Tracing to pause tracing. Use this option to control the accumulation of trace files when you're not actively tracking your app's REST calls.
Click the Export icon () to export the trace files for an individual REST call. Use this option to save the files to your local file system and import it later when required. This way, you won't lose the data even if trace files hit the server's disk-usage limit.
Click the Delete icon () to delete trace files for individual REST calls. Use this option to remove trace files you don't need and clear up space.
Click Clear to remove all trace files for the app's current version. Use this option to delete tracing data for a particular version of an app. For example, when you're more interested in data for the staged and live versions of an app, you can clear trace files for the development version to remove previous data that might be taking up disk space on the server.

Export and Import a Trace File

You can export a particular REST call's trace files to your local file system to avoid losing data if the server reaches its disk-usage limit for trace files. Then, when you are ready to analyze the data, you can import the file back in to Visual Builder. Importing a trace file is a browser function that doesn't affect disk usage on the server.

To export and import a trace file:

Click the Export icon () for the REST call whose trace file you want to export.

The trace file is saved as a .JSON file in the directory specified for your browser’s downloads.
When you are ready to import the file back into the system, click Import From File in the drop-down list.

Description of the illustration tracing-import-file.png
Click the upload box and navigate to the .JSON file you previously exported. You can also drag and drop the file in the upload box.
The file's contents display in the Trace panel. You can now view the trace's details and spans.