README.md

Keen IO Official Ruby Client Library

keen-gem is the official Ruby Client for the Keen IO API. The
Keen IO API lets developers build analytics features directly into their apps.

Installation

Add to your Gemfile:

gem 'keen'

or install from Rubygems:

gem install keen

keen is tested with Ruby 1.8 and 1.9 on:

MRI

Rubinius

jRuby (except for asynchronous methods - no TLS support for EM on jRuby)

Usage

Before making any API calls, you must supply keen-gem with a Project ID and one or more authentication keys.
(If you need a Keen IO account, sign up here - it's free.)

Setting a write key is required for publishing events. Setting a read key is required for running queries.
Setting a master key is required for performing deletes. You can find keys for all of your projects
on keen.io.

The recommended way to set keys is via the environment. The keys you can set are
KEEN_PROJECT_ID, KEEN_WRITE_KEY, KEEN_READ_KEY and KEEN_MASTER_KEY.
You only need to specify the keys that correspond to the API calls you'll be performing.
If you're using foreman, add this to your .env file:

If not, make a script to export the variables into your shell or put it before the command you use to start your server.

When you deploy, make sure your production environment variables are set. For example,
set config vars on Heroku. (We recommend this
environment-based approach because it keeps sensitive information out of the codebase. If you can't do this, see the alternatives below.)

Once your environment is properly configured, the Keen object is ready to go immediately.

Synchronous Publishing

Publishing events requires that KEEN_WRITE_KEY is set. Publish an event like this:

This will publish an event to the sign_ups collection with the username and referred_by properties set.
The event properties can be any valid Ruby hash. Nested properties are allowed. Lists of objects are also allowed, but not recommended because they can be difficult to query over. See alternatives to lists of objects here. You can learn more about data modeling with Keen IO with the Data Modeling Guide.

Protip: Marshalling gems like Blockhead make converting structs or objects to hashes easier.

The event collection need not exist in advance. If it doesn't exist, Keen IO will create it on the first request.

Asynchronous publishing

The Keen IO API is fast, but any synchronous network call you make will negatively impact response times. For this reason, we recommend you use the publish_async method to send events when latency is a concern. Alternatively, you can drop events into a background queue e.g. Delayed Jobs and publish synchronously from there.

To publish asynchronously, first add
em-http-request to your Gemfile. Make sure it's version 1.0 or above.

gem"em-http-request", "~> 1.0"

Next, run an instance of EventMachine. If you're using an EventMachine-based web server like
thin or goliath you're already doing this. Otherwise, you'll need to start an EventMachine loop manually as follows:

require'em-http-request'Thread.new { EventMachine.run }

The best place for this is in an initializer, or anywhere that runs when your app boots up.
Here's a useful blog article that explains more about this approach - EventMachine and Passenger.

And here's a gist that shows an example of Eventmachine with Unicorn, specifically the Unicorn config for starting and stopping EventMachine after forking.

Other code examples

Overwriting event timestamps

Two time-related properties are included in your event automatically. The properties “keen.timestamp” and “keen.created_at” are set at the time your event is recorded. You have the ability to overwrite the keen.timestamp property. This could be useful, for example, if you are backfilling historical data. Be sure to use ISO-8601 Format.

em-synchrony

keen-gem can be used with em-synchrony.
If you call publish_async and EM::Synchrony is defined the method will return the response
directly. (It does not return the deferrable on which to register callbacks.) Likewise, it will raise
exceptions 'synchronously' should they happen.

Beacon URLs

It's possible to publish events to your Keen IO project using the HTTP GET method.
This is useful for situations like tracking email opens using image beacons.

In this situation, the JSON event data is passed by encoding it base-64 and adding it as a request parameter called data.
The beacon_url method found on the Keen::Client does this for you. Here's an example:

You can use the scoped key created in Ruby for API requests from any client. Scoped keys are commonly used in JavaScript, where credentials are visible and need to be protected.

Additional options

HTTP Read Timeout

The default Net:HTTP timeout is 60 seconds. That's usually enough, but if you're querying over a large collection you may need to increase it. The timeout on the API side is 300 seconds, so that's as far as you'd want to go. You can configure a read timeout (in seconds) by setting a KEEN_READ_TIMEOUT environment variable, or by passing in a read_timeout option to the client constructor as follows:

keen =Keen::Client.new(:read_timeout => 300)

HTTP Proxy

You can set the KEEN_PROXY_TYPE and KEEN_PROXY_URL environment variables to enable HTTP proxying. KEEN_PROXY_TYPE should be set to socks5. You can also configure this on client instances by passing in proxy_type and proxy_url keys.

Troubleshooting

EventMachine

If you run into Keen::Error: Keen IO Exception: An EventMachine loop must be running to use publish_async calls or
Uncaught RuntimeError: eventmachine not initialized: evma_set_pending_connect_timeout, this means that the EventMachine
loop has died. This can happen for a variety of reasons, and every app is different. Issue #22 shows how to add some extra protection to avoid this situation.

publish_async in a script or worker

If you write a script that uses publish_async, you need to keep the script alive long enough for the call(s) to complete.
EventMachine itself won't do this because it runs in a different thread. Here's an example gist that shows how to exit the process after the event has been recorded.

0.7.8

Add support for redirect URL creation.

0.7.7

Add support for HTTP and SOCKS proxies. Set KEEN_PROXY_URL to the proxy URL and KEEN_PROXY_TYPE to 'socks5' if you need to. These
properties can also be set on the client instances as proxy_url and proxy_type.

Delegate the master_key fields from the Keen object.

0.7.6

Explicitly require CGI.

0.7.5

Use CGI.escape instead of URI.escape to get accurate URL encoding for certain characters

0.7.4

Allow event collection names for publishing/deleting methods to be symbols

0.7.3

Add batch publishing support

Allow event collection names for querying methods to be symbols. Thanks to cbartlett.

0.7.2

Fix support for non-https API URL testing

0.7.1

Allow configuration of the base API URL via the KEEN_API_URL environment variable. Useful for local testing and proxies.

0.7.0

BREAKING CHANGE! Added support for read and write scoped keys to reflect the new Keen IO security architecture.
The advantage of scoped keys is finer grained permission control. Public clients that
publish events (like a web browser) require a key that can write but not read. On the other hand, private dashboards and
server-side querying processes require a Read key that should not be made public.

0.6.1

Improved logging and exception handling.

0.6.0

Added querying capabilities. A big thanks to ifeelgoods for contributing!

0.5.0

Removed API Key as a required field on Keen::Client. Only the Project ID is required to publish events.

You can continue to provide the API Key. Future features planned for this gem will require it. But for now,
there is no keen-gem functionality that uses it.