App performance monitoring

Monitor web app performance by connecting to Datadog and Sentry.

Performance monitoring is currently in on Retool Cloud and on Self-hosted Retool.

Use Retool's performance monitoring integration to send page load and query traces to Datadog or Sentry. Once enabled, you can view detailed performance information that helps provide context on potential performance issues on which you can improve.

Queries and page loads that occur while editing an app are not reported.

If you don't use Datadog or Sentry, reach out to iva@retool.com or your account team and let us know which provider(s) you use.

1. Configure observability provider

Perform the following steps to configure your chosen observability provider.

Datadog

To configure Datadog:

1. Create a Datadog pipeline to consume traces. Retool spans will stream from service:retool_performance_monitoring.
2. Create a Datadog API key to use in the next step. Note your organization's Datadog Site.
3. Contact your Datadog account manager for access to the Datadog OTLP Traces Intake Endpoint, which is in preview.

Sentry

To configure Sentry:

1. Create a Sentry project for Retool performance monitoring.
2. Navigate to the Client Keys (DSN) section of your Sentry project's settings. Copy the DSN key to use in the next step.

2. Connect providers to Retool

Next, configure your Retool organization to connect to your observability provider. You can configure the connection by either:

• Navigating to Settings > Observability.
• Using the Retool API to programmatically configure observability provider connections.

Datadog

Configure the API key setting with the Datadog API key you created in the previous step. Make sure you specify the correct Datadog Site

Sentry

Configure the DSN key setting with the Sentry DSN key you created in the previous step.

Traces

Retool sends traces to Sentry and Datadog, where they appear in the form of a flame graph. Traces are primarily made up of query spans. A query span includes raw query duration and the time that Retool takes to process the result and update the app model. Child spans are included only if they take longer than 10 ms.

• For resource queries, the raw query duration measures the time spent retrieving the result from an external service.
• For JavaScript queries, the raw query duration measures the time spent executing the code (including waiting on async functions called from JavaScript).

Refer to the Query best practices documentation for more information on how to optimize your queries. Retool provides traces in the following categories:

• Page initialization
• Page navigation
• User interaction

Page initialization

Page initialization traces show how your app performs from initial page load until all initialization queries are completed. Page initialization is broken down into the following metrics:

• Init: Time from when the app is opened to when all queries that were triggered on load have completed or the end of Time to Productivity, whichever is longest.
• Time to First Query (TTFQ): Time from when the app is opened to when the first query is run. Can be affected by app size, number of plugins, and complexity of custom Javascript.
• Time to Productivity (TTP): Time from when the first query is run to when the first long task (longer than 50 ms) has been completed. This is a proxy for when the app is ready to interact.

The rest of the span shows traces of initialization queries and any dependent queries.

Page navigation

Page navigation traces show how your app performs when switching pages. Page navigation is broken down into the following metrics:

• Time to First Query (TTFQ): Time from when the user initiates a page transition to when the first query on the new page runs.
• updatePreloadedJS: Time to run the preloaded JS of the items on the new page. Subset of TTFQ.
• batchedUpdateTemplate: Time to load the components on the page. Subset of TTFQ.
• Time to Productivity (TTP): Time from when the first query is run to when the first long task (longer than 50 ms) has been completed. This is a proxy for when the page is ready to interact.

This trace also includes the previousPage and currentPage attributes, which help identify the pages that the user navigated between.

User interaction

User interaction traces are triggered when a user performs an action, such as clicking a Button or typing into a Text Input, that triggers query runs.

Query subspans

Query subspans are portions of the query run that show a breakdown of what the different actions Retool takes when executing a query.

Metric	Definition
Prepare	Measures the time to calculate all query inputs, format them, and send requests to the Retool backend.
Backend	For resource queries only. Measures the time to execute the query and transfer data to and from the Retool backend. This usually makes up the majority of the query duration.
Response handling	Measures the time to handle the raw query response by downloading a file containing query data, or uploading a file to a cloud provider (as in S3 and GCS queries).
Frontend	For JavaScript queries, parentWindow queries, and Query JSON with SQL. Measures the duration of the JavaScript function. This usually makes up the majority of the query duration.
Transformer	If the query transforms data, measures the time to transform the data.
Post-processing	Measures the time for Retool to process the data and update the app state.

Tags

Retool provides tags on traces and individual spans to provide additional context around the conditions that generated a specific measurement.

Trace tags

Tag	Definition	Example
appName	The name of the app.	Pets
appUuid	The app identifier.	16423e12-eef4-11ef-b170-eb7362451ab0
browser	The browser type.	chrome
browserVersion	The browser version.	133.0.0
environment	The app environment.	production
os	The host operating system.	Mac OS
release	The Retool version.	3.165.0
traceType	The type of action the trace represents.	init
url	The page URL.	http://localhost:3000/apps/16423e12-eef4-11ef-b170-eb7362451ab0/Pets/page1
user	The user info.	username:Alex Wang
viewMode	The app view mode.	presentation

Span tags

Tag	Context	Example
appName	The name of the app.	Store Manager
appTemplatePlugins	The number of components.	22 (number)
currentPage	The current page.	franchises
dbconnectortime	The time to execute resource on backend.	600.00ms
isEmbedded	Whether the app is embedded.	false
isFirstPageLoad	Whether the user navigated to the page directly.	true
javaScriptLinks	The number of pre-loaded JS queries.	3 (number)
operation	The type of action the span represents.	pageload
previousPage	The previous page.	home
queryId	The query identifier.	dogAPI
queryParams	The additional query parameters.	{}
resourceId	The resource identifier.	92c3cbec-bf16-4872-a859-2a8975dd4cf3
resourceType	The type of resource.	restapi
responsesize	The query response size.	3.1 KiB
servedFromCache	Whether the result was served from a cache.	false
status	The query completion status.	Success
traceType	The type of action the trace represents.	init
truncated	Whether the trace ended before the span could complete.	false

Troubleshooting performance monitoring metrics

Use the recommendations in this section to address issues that you identify with your app performance. Refer to the web app best practices and query best practices guides for more general recommendations.

Time to First Query (TTFQ)

Most of the TTFQ value can be attributed to Retool's initialization process, but there are some areas where the app itself can affect load times. To improve your TTFQ metric, Retool recommends investigating the following spans:

Span	Recommendations
generateDependencyGraph	This reflects how long it took for Retool to initialize the app’s dependency graph. If this span is long, consider reducing the number of app plugins across all pages. You can also simplify complex and deep dependency chains by pulling logic from components into JavaScript queries, calculating iterative values only once, and removing nested modules and containers. Complex modules should be used sparingly as they can quickly bloat the dependency graph. It is better to use a module once and populate the data dynamically rather than reusing a module multiple times with different data.
fetchScripts	This reflects the time spent running your org’s pre-loaded JavaScript. If this span is long, consider reducing complexity or removing unnecessary functions in pre-loaded JavaScript.

Time to Productivity (TTP)

To improve your TTP metric, Retool recommends investigating the following:

• Identify the bottleneck query: Look for the query or query chain in the flamegraph that extends TTP the furthest. Reducing the run time of this query or its downstream events will shorten TTP.
• Find opportunities to parallelize queries: If a chain of queries is extending TTP, consider re-architecting the app to run more queries in parallel.

Query run times

To improve your query run times, Retool recommends investigating the following:

• Consider whether the query needed to run: By default, many queries run on page load or when referenced values change. If the query was not needed at the time it ran, you could modify your query’s run behavior to be more controlled.
• Use the run time breakdown: If a lot of time is spent on the backend, this suggests the query itself needs to be more performant. If a lot of time is spent on the frontend, this suggests that the dependencies downstream of the query need to be simplified.
• Look at query response size: A large payload slows down both backend and frontend processing. Modify the query or use pagination to reduce response size.
• Check the servedFromCache tag: If the query hasn’t been cached yet and the app doesn’t need immediate data updates, consider caching the query.