StatsMix

Our API is bundled into the StatsMix ruby gem. To install it, just run:

$ gem install statsmix

You must have an API key to use the API. You can find it in the "My Account" section StatsMix. If you don't have an account, sign up for a free Developer account (limited to three metrics) here.

Once you have your API key, configure the gem according to your version of Rails.

For Rails 2

Add the following to config/environment.rb, then restart the server:

gem 'statsmix'
StatsMix.api_key = "YOUR API KEY"

For Rails 3

Add the following to your Gemfile, then restart the server:

gem 'statsmix'
StatsMix.api_key = "YOUR API KEY"

Using StatsMix to Track Events

Any time you want to track an event in your app, simply call:

StatsMix.track(name_of_metric, value = 1, options = {})

Examples

Track every time a new blog post is created:

# create a stat with the value 1 (default) for the metric called "Blog Posts"
StatsMix.track("Blog Posts")

Count the number of new user accounts in the last 24 hours (i.e. run daily in a daily rake task):

count = User.count(:conditions => ["created_at >= ?", 24.hours.ago]) 
# create a stat with the value count for the metric called "Daily New Users"
StatsMix.track("Daily New Users", count)

Adding Metadata

You optionally can "tag" your data with metadata in the :meta option. For example, if you have a file upload utility and want to track what kinds of files you are receiving:

# a user just uploaded a PDF file; track the type of file using metadata
StatsMix.track("File Uploads", 1, {:meta => {"file type" => "PDF"}})

You can include multiple key-value pairs in the same stat:

StatsMix.track("File Uploads", 1, {:meta => {"file type" => "PDF", "size" => "1 mb", "country of origin" => "Absurdistan"}})

Adding Your Own Identifier

If you need the ability to update a stat after the fact, you can pass in a unique identifier ref_id (scoped to that metric).

For example, perhaps you want to update the number of users every hour instead of every day. If you pass in the date as ref_id, StatsMix will check whether a stat with that ref_id already exists for that metric. If found, StatsMix will update instead of inserting.

count = User.count(:conditions => ["created_at >= ?", Time.now.strftime("%Y-%m-%d")]) 
# create/update a stat using today"s date as the unique identifier
StatsMix.track("Daily New Users", count, {:ref_id => Time.now.strftime("%Y-%m-%d")})

Additional Options

If you’d like to change the timestamp of a stat, pass in the parameter generated_at.

# backdate the stat to yesterday
StatsMix.track("Blog Posts", 1, {:generated_at => 1.days.ago})

Higher level StatsMix accounts can have additional profiles. A profile can be described as a grouping or "bucket" of metrics. For example, an agency may want to create a profile for each customer.

If you are tracking metrics with the same name in two different profiles, you must specify which profile to use with profile_id. (If you don't specify profile_id, StatsMix will default to the first profile in your account.)

StatsMix.track("Blog Posts", 1, {:profile_id => 789})

You can find the profile ID in StatsMix by creating a metric and looking at the API Details under Code Snippets in the Data & API section. (It will also be in the URL as /profiles/123/metrics/456 - in this case the profile id is 123.)

Limitations

If you hit a plan level limit (i.e. you go over the number of metrics available to your account), the API will return a 403 Forbidden error and an explanation.

The number of metrics and profiles you can create is based on the type of account you have. For example, Developer accounts are limited to three metrics. You can see the current options on our pricing page.

Local Setup

When running StatsMix in development, you can tell StatsMix to either ignore calls to it altogether or funnel them all into a single test metric.

For ignoring calls altogether, just put the following in a configuration file such as environment.rb:

StatsMix.ignore = true

For logging to a test metric, add this instead:

StatsMix.test_metric_name = "My Test Metric"

This routes all StatsMix.track calls to "My Test Metric" regardless of the name passed in.

Notice If StatsMix.ignore is set, then the test metric will not be used unless StatsMix.ignore is first reset to false.

API Documentation