As more users build and use Retool apps within your organization, it’s helpful to understand adoption patterns to better make decisions about your use of Retool. If you’re self-hosting Retool, you might run multiple instances, and seeing which users are using which apps can be difficult.
Retool offers a built-in Retool Usage Analytics page to admins that aggregates usage across all your Retool instances.
Enable usage analytics on self-hosted Retool
If you self-host Retool, you might deploy multiple instances to isolate your production and non-production environments. Enabling Usage Analytics on a single instance allows you to view application usage (and other sensitive data) across all of your instances. We recommend choosing whichever instance is the most secure and has the proper admins for viewing access to the Usage Analytics page. All Admins of that instance will have the ability to view usage in Settings > Usage Analytics.
To enable Usage Analytics and view usage across all instances in an organization, set the
USAGE_API_TOKEN environment variable on the chosen Retool instance. This environment variable is a manually granted Usage Analytics access token to ensure security.
If you are not set up with Usage Analytics, please reach out to your Retool account manager to receive a Usage Analytics access token.
View usage analytics
Once Usage Analytics is enabled, admins can view Settings > Usage Analytics:
Retool surfaces a variety of metrics per active instance of Retool:
- Aggregate app usage over time
- Aggregate active users over time
- Individual app usage summaries
- Individual user usage summaries
You can hover over the details of each metrics to learn more.
Enable access for more users
By default, Usage Analytics is only shown to admins, but you can let non-admins view Usage Analytics through permission groups. Navigate to your permission group and under Additional > Settings page visibility, select View usage analytics. Users in this permission group can view organization-wide Retool usage.
Are users de-duplicated across multiple instances? How?
We assume emails uniquely identify users. If a user is accessing multiple Retool instances, they must use the same email on each instance to avoid being counted multiple times in active-user counts. This also means that we expect to see a temporary spike in usage for an organization undergoing a domain migration.
I’m currently using the imported Usage Analytics app. What changes for me?
Previously, we provided an importable Usage Analytics App that you could import into your instance to view usage on that instance. Moving forward, you should remove the Usage Analytics app and set up a Usage Analytics access token so that you can get accurate and comprehensive usage data for all your Retool instances. Retool is no longer maintaining the importable Usage Analytics Retool app.
How do I get a usage analytics environment variable?
If you’re self-hosting Retool, please reach out to your account manager for a usage analytics access token.
How is the usage analytics environment variable generated, and why do we need it?
The usage analytics environment variable is a password that you need in order to get Usage Analytics data on your deployments from Retool’s Usage Analytics API. The token follows JWT format, but doesn’t contain any sensitive info and can be treated as a random string.
Which instance should I choose to surface usage analytics?
We recommend customers choose whichever instance is the most secure and has the proper admins for viewing access to the Usage Analytics page.