We are happy to announce the release of the Snowplow Ruby Tracker version 0.3.0. This version adds support for asynchronous requests and POST requests, and introduces the new Subject and Emitter classes.
The rest of this post will cover:
- The Subject class
- The Emitter class
- Chainable methods
- Other changes
- Getting help
An instance of the Subject class represents a user who is performing an event in the Subject–Verb–Direct Object model proposed in our Snowplow event grammar. User-specific data like timezone and language are attached to instances of the Subject class.
If your tracker will only be tracking one user, you don’t have to create a Subject instance at all – one will be created automatically for you. The only change you need to make is setting the new
subject argument to
nil when initializing your tracker:
(The first argument,
my_emitter, will be explained later.)
If you want more than one subject:
Each tracker instance must now be initialized with an Emitter which is responsible for firing events to a Collector. An Emitter instance is initialized with two arguments: an endpoint and an optional configuration hash. For example:
Every setting in the configuration hash is optional. Here is what they do:
:protocoldetermines whether events will be sent using HTTP or HTTPS. It defaults to “http”
:methoddetermines whether events will be sent using GET or POST. It defaults to “get”
:portdetermines the port to use
:buffer_sizeis the number of events which will be queued before they are all sent, a process called “flushing”. When using GET, it defaults to 0 because each event has its own request. When using POST, it defaults to 10, and the buffered events are all sent together in a single request
:on_successis a callback which is called every time the buffer is flushed and every event in it is sent successfully (meaning with status code 200). It should accept one argument: the number of requests sent this way
on_failureis a callback which is called if the buffer is flushed but not every event is sent successfully. It should accept two arguments: the number of successfully sent events and an array containing the unsuccessful events
Once the emitter is created, create a tracker like this:
You can then track events as in previous versions of the Ruby Tracker.
The AsyncEmitter class
The AsyncEmitter works just like the Emitter, but is asynchronous – whenever the buffer is flushed a new thread is created. This means that the requests the AsyncEmitter sends do not block.
It is also possible to initialize a tracker with an array of emitters, in which case events will be sent to all of them:
You can also add new emitters after creating a tracker with the
You can manually flush all emitters associated with a tracker using the
This is useful if you are about to halt the process but do not want to lose your buffered events.
The flush method takes an optional
sync argument which determines whether AsyncEmitters will be flushed synchronously. Set
true and the method will block until all flushing threads have finished.
All Tracker methods and Subject methods now return
self and so are chainable:
This release introduces logging using Ruby’s built-in Logger class. The log level is set to INFO by default but can be changed:
The levels are:
||Notification for requests with status code not equal to 200|
||Notification for all requests|
||Contents of all requests|
The Snowplow Ruby Tracker uses the Ruby Contracts gem for typechecking. Version 0.3.0 offers the option to turn contracts on or off:
We have also:
- Changed the default platform to “srv” (which is short for “server”) #37
- Made the screen name argument to
There are three breaking changes to the API, two of which involving the tracker constructor: the first argument is now an Emitter rather than a Sstring, and there is a new second argument which may be a Subject but otherwise defaults to
nil. An example of how to update your code:
The final change is that all tracker methods now return the tracker instance, self.
If you have an idea for a new feature or want help getting things set up, please get in touch. This is only the second release of the Ruby Tracker, so we’re keen to hear people’s opinions. And raise an issue if you spot any bugs!