Issue
When starting your application with Passenger, along with the Contrast Ruby agent, the startup times out and fails to start.
Cause
The most common issue faced when integrating with an application started and monitored by Passenger is the increase in application startup time introduced by the Ruby agent. Because the agent monkey patches at load time on require and similar methods, there's a one-time penalty incurred the first time a Module is loaded. As a result, the application startup and the first request to each controller may be delayed.
If your application startup is already close to the timeout for your Passenger instance, which defaults to 90 seconds, the application may not be able to start in time. In that case, Passenger will terminate the application with a SIGKILL signal and then attempt a restart. As the Contrast agent patching happens at runtime, restarting the application incurs the startup penalty again, which results in a loop of startups and shutdowns.
Resolution
While it's Contrast's goal to reduce the overhead of instrumenting and using the Contrast agent, there will always be an overhead to introducing it to the application. To account for this, Contrast recommends that you increase the timeout of your Passenger configuration.
Given your normal application startup time, Contrast recommends allocating at least five times that amount - or a minimum of 300 seconds - for timeout during troubleshooting. As you see how the agent behaves within your application, and as Contrast works to lessen the agent's startup impact, this number may decrease.
The manner in which you adjust this timeout depends on how you're using Passenger.
Apache timeout
From the Passenger documentation, you can see that the application timeout is controlled by PassengerStartTimeout. This value defaults to 90 seconds, but that may not be enough time. To increase this timeout, you must update your configuration file.
You can find the configuration file your deployment is using with the command which passenger-config. Within this file, there should be a series of Passenger configurations, starting with the prefix Passenger. Adjacent to these configurations, supply the configuration PassengerStartTimeout #{ seconds } where seconds is the timeout. For instance, PassengerStartTimeout 300 sets the timeout to 300 seconds. Once you've updated this timeout configuration, restart Apache to verify the change takes effect in all instances of Passenger.
For more information on Passenger configurations, refer to the documentation by RPM.
Note: If your configuration already has this value, or you're overriding with a configuration that has a higher precedence, you must replace it with the new seconds.
Nginx timeout
From the Passenger documentation, you can see that the application timeout is controlled by passenger_start_timeout. This value defaults to 90 seconds, but that may not be enough time. To increase this timeout, you must update your configuration file.
Because the configuration only honors the Nginx configuration file when running with Nginx, the following changes must be made there instead of the Passengerfile.json. By default, this configuration will be at /etc/nginx/nginx.conf for *nix systems and /usr/local/etc/nginx/nginx.conf for Mac. Within this file, there should be a section in which you've enabled Passenger with passenger_enabled
on;. In this section, add passenger_start_timeout #{ seconds } where seconds is the timeout. For instance, passenger_start_timeout 300 sets the timeout to 300 seconds. Once you've updated this timeout configuration, restart Nginx to verify the change takes effect in all instances of Passenger.
For more information on Nginx configurations, refer to the documentation by Digital Ocean.
Note: If your configuration is for multiple servers, each server on which the Ruby agent is installed must have the timeout configuration updated.