Phusion white papers Phusion overview

Phusion Blog

Introducing the Union Station filter language

By Hongli Lai on March 11th, 2011

Union Station is our state-of-the-art web application performance monitoring and behavior analysis service. It is currently in public beta, which started on March 2. You can follow us on Twitter through @unionstationapp.

One of the unique selling points of Union Station is that we collect data on all requests, not just the slow ones. Union Station is not just a performance monitor that warns you about slow requests, it’s a full web application behavior history browser: you can browse back into any point in time and see exactly what your web application was doing.

However we have noticed that there are quite some heavy-duty users on our beta who receive tons upon tons of traffic. For some of those people it might be unfeasible or undesirable to collect data on all requests. After our server cluster expansion we can process all that data just fine, but sending all that data to Union Station may still impose some stress on users’ network connections that they may want to avoid (note: Phusion Passenger already compresses data before sending to Union Station). Some users are just not interested in some data and don’t want them to be logged at all.

We are pleased to announce a new Union Station feature: the filter language. With this language one can specify which requests one wants and doesn’t want to log, e.g. because you are only interested in slow requests or only interested in requests to a certain controller. Filters are run on the client side and are supported since Phusion Passenger 3.0.5, released today. One writes filters in the Union Station filter language and specifies them in the web server config file. The result of a filter is either true (allow the given data to be sent to Union Station) or false (don’t allow the given data to be sent). After logging a request, Phusion Passenger runs all defined filters to determine whether to send the request’s data to Union Station.

Filters are defined with the UnionStationFilter directive (Apache) or the union_station_filter directive (Nginx).

The Union Station filter language somewhat resembles expressions in many popular languages such as C, Javascript and Ruby. Every filter is a combination of expressions, each of which evaluate to a boolean. An expression is either a matching expression or a function call.

Quick examples

Example 1: URI must be exactly equal to /foo/bar:

uri == "/foo/bar"

Example 2: Response time must be larger than 150 miliseconds (150000 microseconds):

response_time > 150000

Example 3: URI must match the regular expression /animals/(dog|cat)
and the response time must be larger than 60 miliseconds (60000 microseconds):

uri =~ /\/animals\/(dog|cat)/ && response_time > 60000

More information

Please read the Union Station help page for more information about this filter language.