This add-on is operated by Keen.io LLC

Managed Kafka pipeline to stream, store, analyze, and visualize event data

Last updated June 25, 2020

The Keen IO add-on is a Heroku add-on for doing custom app analytics in minutes instead of days.

Keen IO allows developers to build powerful analytics features directly into their apps with ease. It supports arbitrary event collection, analysis over API, and easy to use SDKs to collect, analyze, and visualize your data.

Keen IO is accessible via an API and has supported client libraries for Java, Ruby, Python, and Node.js.

Documentation that is not specific to Heroku is available at Keen IO’s documentation page.

Provisioning the add-on

Keen IO can be attached to a Heroku application via the CLI:

$ heroku addons:create keen
-----> Adding keen to sharp-mountain-4005... done, v18 (free)

A list of all plans available can be found here.

Once Keen IO has been added, a number of environment variables/settings will be available for your app configuration. They are:

• KEEN_PROJECT_ID - The Project ID generated for your add-on.
• KEEN_WRITE_KEY - The Write Key generated for your add-on.
• KEEN_READ_KEY - The Read Key generated for your add-on.
• KEEN_API_URL - The URL to make API requests to.

This can be confirmed using the heroku config:get command.

$ heroku config:get KEEN_API_URL
https://api.keen.io

After installing Keen IO the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command to add the Keen IO config values retrieved from heroku config to your .env file.

$ heroku config -s | grep KEEN >> .env
$ more .env

For more information, see the Heroku Local article.

Using with Ruby/Rails 3.x

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Keen IO client library.

gem 'keen'

Update application dependencies with bundler.

$ bundle install

Then send Keen IO an event from anywhere in your code:

Keen.publish("sign_ups", { :username => "lloyd", :referred_by => "harry" })

This will publish an event to the sign_ups collection with the username and referred_by properties set.

Using with Python/Django

Install with pip:

$ pip install keen

Then send Keen IO an event from anywhere in your code:

import keen

keen.add_event("sign_ups", {
    "username": "lloyd",
    "referred_by": "harry"
})

This will publish an event to the ‘sign_ups’ collection with the username and referred_by properties set.

Using with Node (server side)

Install with npm:

npm install keen-tracking

Then send Keen IO an event from anywhere in your code:

const KeenTracking = require('keen-tracking');

// Configure instance. Only projectId and writeKey are required to send data.
const client = new KeenTracking({
  projectId: process.env['KEEN_PROJECT_ID'],
  writeKey: process.env['KEEN_WRITE_KEY']
});

client.recordEvent("sign_ups", {"username": "lloyd", "referred_by": "harry"}, function(err, res) {
    if (err) {
        console.log("Oh no, an error!");
    } else {
        console.log("Hooray, it worked!");
    }
});

This will publish an event to the ‘sign_ups’ collection with the username and referred_by properties set.

Using with Javascript (client side)

Install with npm:

npm install keen-tracking --save

Then send Keen IO an event from anywhere in your client-side app:

import KeenTracking from 'keen-tracking';

const client = new KeenTracking({
  projectId: 'PROJECT_ID',
  writeKey: 'WRITE_KEY'
});

client.recordEvent("sign_ups", {"username": "lloyd", "referred_by": "harry"}, function(err, res) {
    if (err) {
        console.log("Oh no, an error!");
    } else {
        console.log("Hooray, it worked!");
    }
});

This will publish an event to the ‘sign_ups’ collection with the username and referred_by properties set.

Optionally, you can also enable auto-tracking to automatically track a wide variety of events (browser only):

  KeenTracking.ready(function(){
    const client = new KeenTracking({
      projectId: 'YOUR_PROJECT_ID',
      writeKey: 'YOUR_WRITE_KEY'
    });
    client.initAutoTracking();
  });

Learn how to configure auto tracking here: https://github.com/keen/keen-tracking.js/blob/master/docs/auto-tracking.md

Using with Java

Download the jar from http://keen.io/static/code/KeenClient-Java.jar.

Add it to your other external libraries.

Then send Keen IO an event from anywhere in your code:

protected void track() {
    // create an event to upload to Keen
    Map<String, Object> event = new HashMap<String, Object>();
    event.put("username", "lloyd");
    event.put("referred_by", "harry");

    // add it to the "sign_ups" collection in your Keen Project
    try {
        KeenClient.client().addEvent("sign_ups", event);
    } catch (KeenException e) {
        // handle the exception in a way that makes sense to you
        e.printStackTrace();
    }
}

This will publish an event to the ‘sign_ups’ collection with the username and referred_by properties set.

Admin Panel

The Keen IO Admin Panel allows you to look at the events you’ve collected and their properties. It also has an API Workbench to make constructing queries super easy.

The dashboard can be accessed via the CLI:

$ heroku addons:open keen
Opening keen for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select Keen IO from the Add-ons menu.

Troubleshooting

Jump on the Keen IO Users Chat or e-mail team@keen.io!

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade keen:her-business-v1
-----> Upgrading keen:her-business-v1 to sharp-mountain-4005... done, v18 ($32/mo)
       Your plan has been updated to: keen:her-business-v1

Removing the add-on

Keen IO can be removed via the CLI.

This will make all associated data inaccessible. Contact support if you do this accidentally.

$ heroku addons:destroy keen
-----> Removing keen from sharp-mountain-4005... done, v20 (free)

Before removing Keen IO a data export can be performed by doing an Extraction.

Support

All Keen IO support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at team@keen.io.