api_design.rb

# De toplevel module is UnionStationHooks. Maar het heeft ook een alias.
version = UnionStationHooks::VERSION_STRING
version = USH::VERSION_STRING  # hetzelfde

# Initialization. Passenger roept dit aan aan het begin van een request.
reporter = UnionStationHooks.begin_request(rack_env)

# Een Reporter object is een high-level object om *request-specifieke*
# informatie te versturen naar Union Station. De applicatie kan het
# object als volgt verkrijgen:
reporter = rack_env['union_station_hooks']
reporter = rack_env['ush']
reporter = Thread.current[:union_station_hooks]
reporter = Thread.current[:ush]

# Reporter object methoden.
reporter.measure_and_log_event(name) { do_something }
reporter.benchmark(title, name) { do_something }
reporter.log_controller_action(options)
reporter.log_exception(exception, options = {})
reporter.log_total_view_rendering_time(runtime) # ben de unit even vergeten
reporter.log_view_rendering_event { do_something }
reporter.log_database_query(name, begin_time, end_time, sql) { do_something }
reporter.log_cache_hit(name)
reporter.log_cache_miss(name, generation_time = nil)

# Finalization. Passenger roept dit aan aan het einde van een request.
UnionStationHooks.end_request(rack_env)
# => deletes rack_env['union_station_hooks']
# => deletes rack_env['ush']
# => deletes Thread.current[:union_station_hooks]
# => deletes Thread.current[:ush]

# Verder kan de applicatie ook non-request-specifieke informatie
# sturen naar Union Station, bijvoorbeeld excepties in achtergrond
# threads. Dat gebeurt niet via een Reporter object, maar via de
# UnionStationHooks module.
UnionStationHooks.log_exception(exception, options = {})

# Open vragen:
# - Is er een betere naam voor Reporter?
#   - "Logger" kan verward worden met het loggen van hoe de hook code zelf werkt,
#     dus debugging logs van de hook code zelf.