Union Station - www.unionstationapp.com/ Copyright (c) 2010-2015 Phusion Holding B.V.
"Union Station" and "Passenger" are trademarks of Phusion Holding B.V.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
| LIBROOT | = | File.expand_path(File.dirname(__FILE__)) |
The path to the `union_station_hooks_core` Ruby library directory.
@private |
|
| ROOT | = | File.dirname(LIBROOT) |
The path to the `union_station_hooks_core` gem root directory.
@private |
|
| MAJOR_VERSION | = | version_data[:major] | ||
| MINOR_VERSION | = | version_data[:minor] | ||
| TINY_VERSION | = | version_data[:tiny] | ||
| VERSION_STRING | = | version_data[:string] |
@note You do not have to call this! Passenger automatically calls
this for you! Just obtain the RequestReporter object that has been made available for you.
Indicates that a Rack request has begun. Given a Rack environment hash, this method returns {RequestReporter} object, which you can use for logging Union Station information about this request. This method should be called as early as possible during a request, before any processing has begun. Only after calling this method will it be possible to log request-specific information to Union Station.
The {RequestReporter} object that this method creates is also made available through the `union_station_hooks` key in the Rack environment hash, as well as the `:union_station_hooks` key in the current thread‘s object:
env['union_station_hooks']
# => RequestReporter object or nil
Thread.current[:union_station_hooks]
# => RequestReporter object or nil
If this method was already called on this Rack request, then this method does nothing and merely returns the previously created {RequestReporter}.
See {RequestReporter} to learn what kind of information you can log to Union Station about Rack requests.
@return [RequestReporter, nil] A {RequestReporter} object, or nil or
because of certain error conditions. See the RequestReporter class description for when this may be nil.
Called by Passenger after loading the application, to check whether or not the application developer forgot to call {UnionStationHooks.initialize!}. If so, it logs the problem and initializes now.
@private
Returns the configuration hash. This configuration is used by all `union_station_hooks_*` gems. You are supposed to set this hash before calling {UnionStationHooks.initialize!}.
At present, none of the `union_station_hooks_*` gems require additional configuration. All necessary configuration is pulled from Passenger. This may change if and when Union Station in the future supports application servers besides Passenger.
This hash is supposed to only contain symbol keys, not string keys. When {UnionStationHooks.initialize!} is called, that method will convert all string keys to symbol keys before doing anything else with the config hash, so assigning string keys works even though we don‘t recommend it. Furthermore, the config hash is frozen after initialization.
@return [Hash]
@note You do not have to call this! Passenger automatically calls
this for you!
Indicates that a Rack request, on which {begin_rack_request} was called, has ended. You should call this method as late as possible during a request, after all processing have ended. Preferably after the Rack response body has closed.
The {RequestReporter} object associated with this Rack request and with the current, will be closed (by calling {RequestReporter#close}), which finalizes the Union Station logs for this request.
This method MUST be called in the same thread that called {begin_rack_request}.
It is undefined what will happen if you call this method a Rack request on which {begin_rack_request} was not called, so don‘t do that.
This method does nothing if it was already called on this Rack request.
Returns a best-estimate delta (usec) between the wallclock and the monotonic clock (updated every request), such that: time_monotic_usec = time_wallclock_usec - delta
Initializes the Union Station hooks. If there are any other `union_station_hooks_*` gems loaded, then they are initialized too.
Applications must call this during startup. Hooks aren‘t actually installed until this method is called, so until you call this you cannot use the public APIs of any `union_station_hooks_*` gems (besides trivial things such as {UnionStationHooks.initialized?}).
A good place to call this is in the Rackup file `config.ru`. Or, if your application is a Rails app, then you should create an initializer file `config/initializers/union_station.rb` in which you call this.
If this method successfully initializes, then it returns true.
Calling this method may or may not actually initialize the hooks. If this gem determines that initialization is not desired, then this method won‘t do anything and will return `false`. See {UnionStationHooks#should_initialize?}.
Initialization takes place according to parameters set in the {UnionStationHooks.config configuration hash}. If a required configuration option is missing, then this method will raise a {ConfigurationError}.
Initializing twice is a no-op. It only causes this method to return true.
@raise [ConfigurationError] A required configuration option is missing. @return [Boolean] Whether initialization was successful.
An array of objects on which `initialize!` will be called when {UnionStationHooks.initialize!} is called. Other `union_station_hooks_*` gems register themselves in this list when they are loaded, so that a call to {UnionStationHooks.initialize!} will initialize them too.
@private
The currently active Union Station key. This is pulled from the {UnionStationHooks.config configuration}.
@private
Logs an exception that did NOT occur during a request.
This method should be used for logging exceptions outside the request-response cycle, e.g. exceptions in threads. If you want to log a request that occurred during a request, use {RequestReporter#log_exception} instead. That method will also log any related request-specific information, while this method does not.
@param [Exception] exception @since 2.1.0
Returns an opaque object (a {TimePoint}) that represents a collection of metrics about the current time.
This TimePoint samples monotonic time (with a fallback to wall clock time) as well as CPU time, time spent in userspace and kernel space, time spent context switching, etc. The exact information contained in the object is operating system specific, hence the object is opaque.
You should use it for the various API methods that require timing information. Those methods also accept standard Ruby `Time` objects, but we strongly recommended against doing this, because wall clock time can jump forwards and backwards, which may create issues.
See {RequestReporter#log_controller_action} for an example of an API method which expects timing information. `RequestReporter#log_controller_action` expects you to provide timing information about a controller action. That timing information is supposed to be obtained by calling `UnionStationHooks.now`.
@return [TimePoint]
Returns whether the Union Station hooks should be initialized. If this method returns false, then {UnionStationHooks.initialize!} doesn‘t do anything.
At present, this method only returns true when the app is running inside Passenger. This may change if and when in the future Union Station supports application servers besides Passenger.