StatsMix

This add-on is operated by Copper Cloud Inc

Track, chart, and share application and business metrics on dashboards.

StatsMix

Last Updated: 10 April 2014

addons test

Table of Contents

StatsMix is an add-on making it easy to track, chart, and share application and business metrics on dashboards.

Track, monitor, and consolidate your metrics in just minutes. From third-party services to custom metrics, StatsMix delivers unified dashboards for all your metrics. View your entire business at a glance and gain a deeper understanding of what drives your key metrics.

Use StatsMix to:

  • Log every time a particular event happens (such as a user creating a new blog post)
  • View real-time charts and dashboards of application events
  • Share charts and dashboards with users inside and outside your organization
  • Create and share custom dashboards that aggregate multiple metrics together Example dashboard, Example embedded dashboard

StatsMix is accessible via an API and has supported client libraries for Ruby, PHP, Java, and C#. In addition, we have user contributed libraries for Python and Node.js. For more details, visit the code libraries section on our website.

Provisioning the add-on

StatsMix can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

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

Once StatsMix has been added a STATSMIX_URL setting will be available in the app configuration and will contain your StatsMix API key. This can be confirmed using the heroku config command.

$ heroku config
...
STATSMIX_URL => http://www.statsmix.com/api_key/YOUR_API_KEY
...

If you need to set a new API key, either write the new key to a Heroku config variable or do the following (e.g. in an initializer):

StatsMix.api_key = "YOUR_API_KEY"

After installing StatsMix, 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.

Though less portable it’s also possible to set local environment variables using export STATSMIX_URL=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the STATSMIX_URL values retrieved from heroku config to .env.

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

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Using with Rails 3.x

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

gem 'statsmix'

Update application dependencies with bundler.

$ bundle install

The following is an example of using StatsMix to track metrics in your Ruby on Rails application.

The basic pattern in your code will look like this to track any event or action in your Rails app:

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

To push a stat with the value 1 (the default) to a metric called “My First Metric”, you would add this code:

StatsMix.track("My First Metric")

To push the value 20 to that metric:

StatsMix.track("My First Metric", 20)

Stats are individual data points that can also contain descriptive metadata. Metadata is useful for adding granularity to your stats and to track its varying dimensions. Add metadata via the :meta option in the options hash. The following is an example that tracks file uploads by type. For each type in the metadata, this will appear as a series on the metric’s chart.

StatsMix.track("File Uploads", 1, {:meta => {"file type" => "PDF"}})

If you need the ability to update a stat after the fact(i.e. you’re updating the same stat several times a day), you can pass in a unique identifier called ref_id (scoped to that metric, so you can use the same ref_id across metrics). The following example uses today’s date (in UTC) for ref_id, which is useful if you want to do intraday updates to a stat:

StatsMix.track("File Uploads", 1, {:ref_id => Time.now.strftime('%Y-%m-%d'), :meta => {"file type" => "PDF"}})

If you need to timestamp the stat for something other than now, pass in a UTC datetime called :generated_at:

StatsMix.track("File Uploads", 1, {:generated_at => 1.days.ago})

To turn off tracking in your development environment:

StatsMix.ignore = true

In development and test environments, it’s useful to test that StatsMix is working without affecting your production data. To redirect all stats to a test metric, set the following config variable in your respective environment:

StatsMix.test_metric_name = "My Test Metric"

Additional documentation for the StatsMix Ruby gem can be found here.

Using with PHP

PHP applications can use the StatsMix PHP library.

The following is an example of using StatsMix to track metrics in your PHP application. The basic pattern in your code will look like this to track any event or action in your PHP app:

require "StatsMix.php";
StatsMix::set_api_key("YOUR API KEY");
StatsMix::track($name_of_metric, $value = 1, $options = array());

To push a stat with the value 1 (the default) to a metric called “My First Metric”, you would add this code:

StatsMix::track("My First Metric");

To push the value 20 to that metric:

StatsMix::track("My First Metric", 20);

Stats are individual data points that can also contain descriptive metadata. Metadata is useful for adding granularity to your stats and to track its varying dimensions. Add metadata via the meta option in $options. The following is an example that tracks file uploads by type. For each type in the metadata, this will appear as a series on the metric’s chart.

StatsMix::track("File Uploads", 1, array('meta' => array("file type" => "PDF")));

If you need the ability to update a stat after the fact (i.e. you’re updating the same stat several times a day), you can pass in a unique identifier called ref_id, (scoped to that metric, so you can use the same ref_id across metrics). The following example uses today’s date (in UTC) for ref_id, which is useful if you want to do intraday updates to a stat:

StatsMix::track("File Uploads", 1, array('ref_id' => gmstrftime('%Y-%m-%d'), 'meta' => array("file type" => "PDF")));

If you need to timestamp the stat for something other than now, pass in a UTC datetime with the key generated_at

StatsMix::track("File Uploads", 1, array('generated_at' => gmstrftime('%Y-%m-%d %H:%I:%S',strtotime('yesterday'))));

To turn off tracking in your development environment:

StatsMix::set_ignore(true);

To redirect all stats in development environment to a test metric:

StatsMix::set_test_metric_name("My Test Metric");

To create metrics and stats using a more object oriented approach, examine the classes SmMetric and SmStat in StatsMix.php. As an example, you can use them to create a new metric like this:

$metric = new SmMetric;
$metric->name = "My Test Metric";
$metric->save();
if($metric->error){
  echo "<p>Error: {$metric->error}</p>";
}
//view the xml response:
echo $metric->get_response();

Additional documentation for the StatsMix PHP library can be found here.

Using with Java

Java applications will need to download and install several dependencies.

Include the following jars in your build path:
The jar file: statsmix-1.1.0.jar
And its dependencies: statsmix-lib-dependencies.tar.gz
If you need to resolve version errors, these are the links to each of the depedencies:

The following is an example of using StatsMix to track metrics in your Java application.

First initialize and create a new StatsMix Client:

import com.statsmix.*
Client smClient = new Client("YOUR_API_KEY");

The track method sends a request to the track API and returns the XML response as a string. The following snippets were taken from this example file.

For basic metric tracking, the following code adds a new stat with default value of 1 to the metric:

smClient.track("Metric Name");

To track a metric with a value other than one:

smClient.track("Metric Name", 5.2);

To track a metric with additional properties:

List<NameValuePair> properties = new ArrayList<NameValuePair>(2);
properties.add(new BasicNameValuePair("value", "5.2"));  //if you do not include the value, it will default to 1
properties.add(new BasicNameValuePair("ref_id", "java01"));
properties.add(new BasicNameValuePair("generated_at", getDateTime()));
smClient.track("Metric Name", properties);

Tracking with metadata:

JSONObject meta = new JSONObject();
meta.put("food", "ice cream");
meta.put("calories", 500);
smClient.track("Metric Name", properties, meta);

To format the date:

public String getDateTime() {
    DateFormat dateFormat = new SimpleDateFormat("yyyy/MM/dd HH:mm:ss");
    Date date = new Date();
    return dateFormat.format(date);
}

Additional documentation for the StatsMix Java library can be found here.

Using with Python

StatsMix doesn’t have an officially supported library for Python, but we do have user contributed code here.

Using with Node.js

StatsMix doesn’t have an officially supported library for Node.js, but we do have user contributed code here.

StatsMix Launchpad

For more information on the features available within StatsMix, please see the documentation at support.statsmix.com.

The launchpad allows you to manage all your metrics and dashboards within StatsMix from a single web view.

StatsMix Launchpad

The StatsMix launchpad can be accessed via the CLI:

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

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

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

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

$ heroku addons:upgrade statsmix:standard
-----> Upgrading statsmix:standard to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: statsmix:standard

Removing the add-on

StatsMix can be removed via the CLI.

This will destroy all associated data and cannot be undone!

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

Before removing StatsMix, a data export can be performed by request at support.statsmix.com.

Additional documentation

Additional documentation for developers, including a full API resource, can be found on the StatsMix Developers section

Support

All StatsMix 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 support.statsmix.com.