This add-on is operated by MemCachier

Reliable and powerful memcache-as-a-service

MemCachier

Last updated 20 October 2017

MemCachier is an implementation of the Memcache in-memory key/value store used for caching data. It is a key technology in modern web applications for scaling and reducing server loads. The MemCachier add-on manages and scales clusters of memcache servers so you can focus on your app. Tell us how much memory you need and get started for free instantly. Add capacity later as you need it.

Follow our blog or twitter (@memcachier), for status and product announcements.

Getting started

Start by installing the add-on:

$ heroku addons:create memcachier:dev

You can start with more memory if you know you’ll need it:

$ heroku addons:create memcachier:100
$ heroku addons:create memcachier:500
 ... etc ...

Once the add-on has been added you’ll notice three new variables in heroku config:

$ heroku config
...
MEMCACHIER_SERVERS    => mcX.ec2.memcachier.com
MEMCACHIER_USERNAME   => bobslob
MEMCACHIER_PASSWORD   => l0nGr4ndoMstr1Ngo5strang3CHaR4cteRS
...

Next, setup your app to start using the cache. We have documentation for the following languages and frameworks:

• Ruby
• Rails 3 & 4
• Rails 2
• Ruby Puma Webserver
• Rack::Cache
• Python
• Django
• PHP
• WordPress
• CakePHP
• Symfony2
• Laravel
• Node.js
• Java

Supported Protocols: ASCII & Binary

MemCachier supports both the memcache binary and ASCII protocols. Our preferred method is to use the binary protocol as it natively supports user authentication and improves the performance slightly over the ASCII protocol. All our documentation is written for using the binary protocol.

The ASCII protocol does not natively support user authentication. For MemCachier, where all connections require authentication, we extend the ASCII protocol in a very simple way. Once the connection is established, you should send a set command with your username as the key and your password as the value. For example:

$ telnet 35865.1e4cfd.us-east-3.ec2.prod.memcachier.com 11211
>
> set 15F38e 0 0 32
> 52353F9F1C4017CC16FD348B982ED47D
> STORED

You’ll need to do this quickly! As we timeout connections that don’t authenticate within a few seconds. Once authenticated, the full ASCII protocol is available to you.

Ruby

Start by adding the dalli gem to your Gemfile. Dalli is a Ruby memcache client.

gem 'dalli'

Then bundle install:

$ bundle install

You can now start writing some code. First, you’ll need to create a client object with the correct credentials and settings:

require 'dalli'
cache = Dalli::Client.new((ENV["MEMCACHIER_SERVERS"] || "").split(","),
                    {:username => ENV["MEMCACHIER_USERNAME"],
                     :password => ENV["MEMCACHIER_PASSWORD"],
                     :failover => true,
                     :socket_timeout => 1.5,
                     :socket_failure_delay => 0.2
                    })

Now you can use the cache through simple get and set operations, as well as many others.

cache.set("foo", "bar")
puts cache.get("foo")

Testing (Ruby)

The easiest way to test that your setup is working is through the heroku console:

$ heroku run console --app <app>
>> require 'dalli'
>> dc = Dalli::Client.new(ENV["MEMCACHIER_SERVERS"].split(","),
                    {:username => ENV["MEMCACHIER_USERNAME"],
                     :password => ENV["MEMCACHIER_PASSWORD"]
                    })
>> dc.set('memcachier', 'rocks')
=> true

And then fetch the value back:

>> dc.get('memcachier')
=> "rocks"

You can also get an insight into your cache usage (number of keys stored and bytes) with the stats command:

>> dc.stats
=> {"memcachier.example.net:11211" => {"cur_items" => "49982", "bytes" => "89982234"} }

Rails 3 and 4

We also have a tutorial on using MemCachier with Rails here.

Here we explain how you setup and install MemCachier with Rails. Refer to the Rails caching guide for information on how you use MemCachier with Rails. Rails supports automatic whole site caching, per-view caching and fragment caching.

Start by adding the dalli gem to your Gemfile. Dalli is a Ruby memcache client.

gem 'dalli'

Then run bundle install:

$ bundle install

Once this gem is installed you’ll want to configure the Rails cache_store appropriately. Modify your config/environments/production.rb with the following:

config.cache_store = :dalli_store,
                    (ENV["MEMCACHIER_SERVERS"] || "").split(","),
                    {:username => ENV["MEMCACHIER_USERNAME"],
                     :password => ENV["MEMCACHIER_PASSWORD"],
                     :failover => true,
                     :socket_timeout => 1.5,
                     :socket_failure_delay => 0.2,
                     :down_retry_delay => 60
                    }

From here you can use the following code examples to use the cache in your Rails app:

Rails.cache.write("foo", "bar")
puts Rails.cache.read("foo")

Testing (Rails)

To test locally you can simply use the rails console:

rails console
>> Rails.cache.write('memcachier', 'rocks')
=> true
>> Rails.cache.read('memcachier')
=> "rocks"

To test against MemCachier itself, refer to the Ruby testing instructions.

Rails 2

Start by adding the dalli gem to your Gemfile. You will need to use dalli v1.0.5 as later versions of Dalli don’t support Rails 2. Dalli is a Ruby memcache client.

gem 'dalli', '~>1.0.5'

Then run bundle install:

$ bundle install

Once this gem is installed you’ll want to configure the Rails cache_store appropriately. Modify config/environments/production.rb with the following:

require 'active_support/cache/dalli_store23'
config.cache_store = :dalli_store,
                    (ENV["MEMCACHIER_SERVERS"] || "").split(","),
                    {:username => ENV["MEMCACHIER_USERNAME"],
                     :password => ENV["MEMCACHIER_PASSWORD"],
                     :failover => true,
                     :socket_timeout => 1.5,
                     :socket_failure_delay => 0.2
                    }

In config/environment.rb:

config.gem 'dalli'

From here you can use the following code examples to use the cache in your Rails app:

Rails.cache.write("foo", "bar")
puts Rails.cache.read("foo")

Testing (Rails)

To test locally you can simply use the rails console:

rails console
>> Rails.cache.write('memcachier', 'rocks')
=> true
>> Rails.cache.read('memcachier')
=> "rocks"

To test against MemCachier itself, please refer to the Ruby testing instructions.

Ruby Puma Webserver

If you are using the Puma webserver for your Ruby app (Rails or otherwise), then you should take some additional steps due to the multi-threaded runtime being used. This applies to all threaded webservers for Ruby, not just Puma.

First, please refer to the documentation on Rails or Ruby above appropriately, and then take these additional steps.

Dalli by default uses a single connection to each server. This works fine normally, but can be come a bottleneck in a multi-threaded environment and limit performance. In this case, Dalli support connection pooling, where multiple connections are created to MemCachier’s servers. To use this, start by adding the connection_pool gem to your Gemfile:

gem 'connection_pool'

Next, you’ll need to set the :pool_size configuration option when setting up Dalli. For example, in Rails 3 & 4 your configuration would become:

config.cache_store = :dalli_store,
                    (ENV["MEMCACHIER_SERVERS"] || "").split(","),
                    {:username => ENV["MEMCACHIER_USERNAME"],
                     :password => ENV["MEMCACHIER_PASSWORD"],
                     :failover => true,
                     :socket_timeout => 1.5,
                     :socket_failure_delay => 0.2,
                     :pool_size => 5
                    }

Where the number 5 should be chosen according to how many threads you will be running and the available concurrency on the machines running your webserver.

Rails Rack::Cache

Rails can use a middle-ware component of the Rack web server architecture called Rack::Cache. This provides caching of static assets in Rails and is a simple alternative to use a full CDN.

Please see this article for information.

Python

Here we explain how you setup and install MemCachier with Python.

MemCachier has been tested with the pylibmc memcache client. This client relies on the C libmemcached library. This should be fairly straight-forward to install with your package manager on Linux or Windows. We also have a blog post for Ubuntu users on how to do this. You only need to be concerned about this for local development, the Heroku platform includes libmemcached.

Once it’s installed, then install pylibmc:

$ pip install pylibmc

Be sure to update your requirements.txt file with these new requirements (note that your versions may differ than what’s below):

pylibmc==1.5.1

Next, configure your settings.py file the following way:

import pylibmc

servers = os.environ.get('MEMCACHIER_SERVERS', '').split(',')
user = os.environ.get('MEMCACHIER_USERNAME', '')
pass = os.environ.get('MEMCACHIER_PASSWORD', '')

mc = pylibmc.Client(servers, binary=True,
                    username=user, password=pass,
                    behaviors={
                      # Faster IO
                      "tcp_nodelay": True,

                      # Keep connection alive
                      'tcp_keepalive': True,

                      # Timeout for set/get requests
                      'connect_timeout': 2000, # ms
                      'send_timeout': 750 * 1000, # us
                      'receive_timeout': 750 * 1000, # us
                      '_poll_timeout': 2000, # ms

                      # Better failover
                      'ketama': True,
                      'remove_failed': 1,
                      'retry_timeout': 2,
                      'dead_timeout': 30,
                    })

After this, you can start writing cache code in your Python app:

mc.set("foo", "bar")
print mc.get("foo")

Django

Here we explain how you setup and install MemCachier with Django. Please see the Django caching guide for how you effectively use MemCachier. Django supports whole site caching, per-view caching and fragement caching.

For Python and Django we recommend the pylibmc client library. It relies on the C libmemcached library, meaning that to use this client library on your local machine you’ll need to install libmemcached. This should be fairly straight-forward to install with your package manager on Linux or Windows. For Mac OSX users, homebrew provides and easy solution.

The pylibmc client relies on the C libmemcached library. This should be fairly straight-forward to install with your package manager on Linux or Windows. We also have a blog post for Ubuntu users on how to do this. You only need to be concerned about this for local development, the Heroku platform includes libmemcached.

Once libmemcached is installed, then install pylibmc and django-pylibmc:

$ pip install pylibmc django-pylibmc

Be sure to update your requirements.txt file with these new requirements (note that your versions may differ than what’s below):

pylibmc==1.5.1
django-pylibmc==0.6.1

Next, configure your settings.py file the following way:

os.environ['MEMCACHE_SERVERS'] = os.environ.get('MEMCACHIER_SERVERS', '').replace(',', ';')
os.environ['MEMCACHE_USERNAME'] = os.environ.get('MEMCACHIER_USERNAME', '')
os.environ['MEMCACHE_PASSWORD'] = os.environ.get('MEMCACHIER_PASSWORD', '')

CACHES = {
    'default': {
        # Use pylibmc
        'BACKEND': 'django_pylibmc.memcached.PyLibMCCache',

        # Use binary memcache protocol (needed for authentication)
        'BINARY': True,

        # TIMEOUT is not the connection timeout! It's the default expiration
        # timeout that should be applied to keys! Setting it to `None`
        # disables expiration.
        'TIMEOUT': None,

        'OPTIONS': {
            # Enable faster IO
            'tcp_nodelay': True,

            # Keep connection alive
            'tcp_keepalive': True,

            # Timeout settings
            'connect_timeout': 2000, # ms
            'send_timeout': 750 * 1000, # us
            'receive_timeout': 750 * 1000, # us
            '_poll_timeout': 2000, # ms

            # Better failover
            'ketama': True,
            'remove_failed': 1,
            'retry_timeout': 2,
            'dead_timeout': 30,
        }
    }
}

Finally, we also strongly recommend that you place the following code in your wsgi.py file to correct a serious performance bug (#11331) with Django and memcached. The fix enables persistent connections under Django, which by default uses a new connection for each request:

# Fix django closing connection to MemCachier after every request (#11331)
from django.core.cache.backends.memcached import BaseMemcachedCache
BaseMemcachedCache.close = lambda self, **kwargs: None

After this, you can start writing cache code in your Django app:

from django.core.cache import cache
cache.set("foo", "bar")
print cache.get("foo")

You may be interested in the django-heroku-memcacheify pip, which fully configures MemCachier with one line of code for any Django app the pip supports.

PHP

We recommended you use the PHP Memcached client to connect with MemCachier. It supports the full protocol and has great performance.

First, you’ll need to modify your composer.json file to include the module:

{
    "require": {
        "php": ">=5.3.2",
        "ext-memcached": "*"
    }
}

Next, ensure that your new requirements are “frozen” to composer.lock by running:

$ composer update

For more information on enabling the extension and potential troubleshooting (e.g. when you don’t have the memcached extension available on your local computer), refer to the using optional extensions extensions section of Heroku’s PHP reference documentation.

Then, you can connect to MemCachier using the client:

// create a new persistent client
$m = new Memcached("memcached_pool");
$m->setOption(Memcached::OPT_BINARY_PROTOCOL, TRUE);

// some nicer default options
$m->setOption(Memcached::OPT_NO_BLOCK, TRUE);
$m->setOption(Memcached::OPT_AUTO_EJECT_HOSTS, TRUE);
$m->setOption(Memcached::OPT_CONNECT_TIMEOUT, 2000);
$m->setOption(Memcached::OPT_POLL_TIMEOUT, 2000);
$m->setOption(Memcached::OPT_RETRY_TIMEOUT, 2);

// setup authentication
$m->setSaslAuthData( getenv("MEMCACHIER_USERNAME")
                   , getenv("MEMCACHIER_PASSWORD") );

// We use a consistent connection to memcached, so only add in the
// servers first time through otherwise we end up duplicating our
// connections to the server.
if (!$m->getServerList()) {
    // parse server config
    $servers = explode(",", getenv("MEMCACHIER_SERVERS"));
    foreach ($servers as $s) {
        $parts = explode(":", $s);
        $m->addServer($parts[0], $parts[1]);
    }
}

You should look at the PHP Memcached client documentation for a list of API calls you can make against MemCachier.

Session Support

You can configure PHP to store sessions in MemCachier as follows.

First, start by configuring an appropriate .user.ini in your document root (see heroku ini guide). It should contain the following:

session.save_handler=memcached
memcached.sess_binary=1
session.save_path="PERSISTENT=myapp_session ${MEMCACHIER_SERVERS}"
memcached.sess_sasl_username=${MEMCACHIER_USERNAME}
memcached.sess_sasl_password=${MEMCACHIER_PASSWORD}

In your code you should then be able to run:

// Enable MemCachier session support
session_start();
$_SESSION['test'] = 42;

Alternative PHP Client

You should first install the PHPMemcacheSASL client. You can either grab the code directly or use composer for package management. We suggest composer.

First, if using composer, you’ll need to modify your composer.json file to include the module:

{
    "require": {
        "php": ">=5.3.2",
        "memcachier/php-memcache-sasl": ">=1.0.1"
    }
}

Then, you can connect to MemCachier using the client:

require 'vendor/autoload.php';
use MemCachier\MemcacheSASL;

// Create client
$m = new MemcacheSASL();
$servers = explode(",", getenv("MEMCACHIER_SERVERS"));
foreach ($servers as $s) {
    $parts = explode(":", $s);
    $m->addServer($parts[0], $parts[1]);
}

// Setup authentication
$m->setSaslAuthData( getenv("MEMCACHIER_USERNAME")
                   , getenv("MEMCACHIER_PASSWORD") );

// Test client
$m->add("foo", "bar");
echo $m->get("foo");

WordPress

We support WordPress through two different options. The first you can find here, and uses the binary memcache protocol and is supported by us. It should be easy to install, simply follow the instructions on the Git repo.

We also have a community support alternative approach that uses the ASCII memcache protocol, which is far easier to get running on your own servers if you aren’t using a hosted platform like Heroku. You can find it on GitHub here. Please follow the instructions on the repo page.

CakePHP

The CakePHP framework has excellent support for caching and can be easily used with MemCachier as the provider. To setup CakePHP with MemCachier, you’ll need to edit the file app/Config/bootstrap.php and add the following lines:

Cache::config('default', array(
    'engine' => 'Memcached',
    'prefix' => 'mc_',
    'duration' => '+7 days',
    'servers' => explode(',', getenv('MEMCACHIER_SERVERS')),
    'compress' => false,
    'persistent' => 'memcachier',
    'login' => getenv('MEMCACHIER_USERNAME'),
    'password' => getenv('MEMCACHIER_PASSWORD'),
    'serialize' => 'php'
));

After that, you should be able to use caching throughout your application like so:

class Post extends AppModel {

    public function newest() {
        $model = $this;
        return Cache::remember('newest_posts', function() use ($model){
            return $model->find('all', array(
                'order' => 'Post.updated DESC',
                'limit' => 10
            ));
        }, 'longterm');
    }
}

The above will fetch the value associated with the key newest_posts from the cache if it exists. Otherwise, it will execute the function and SQL query, storing the result in the cache using the newest_posts key.

You can find much more information on how to use caching with CakePHP here.

Symfony2

The Symfony2 framework is a great choice with Heroku and MemCachier. It supports caching and storing sessions in MemCachier.

First, start by configuring an appropriate .user.ini in your document root (see heroku ini guide). It should contain the following:

session.save_handler=memcached
memcached.sess_binary=1
session.save_path="PERSISTENT=myapp_session ${MEMCACHIER_SERVERS}"
memcached.sess_sasl_username=${MEMCACHIER_USERNAME}
memcached.sess_sasl_password=${MEMCACHIER_PASSWORD}

Laravel

We have community provided support for the Laravel PHP webframework. You can find a caching backend with MemCachier support on Github here. Please follow the instructions on the repo page.

Node.js

For Node.js we recommend the use of the memjs client library. It is written and supported by MemCachier itself! To install, use the node package manager (npm):

$ npm install memjs

Using it is straight-forward as memjs understands the MEMCACHIER_SERVERS, MEMCACHIER_USERNAME and MEMCACHIER_PASSWORD environment variables that the MemCachier add-on setups. For example:

var memjs = require('memjs')
var mc = memjs.Client.create()
mc.get('hello', function(val) {
    alert(val)
})

Java

For Java we recommend using the SpyMemcached client. We also recommend using the Apache Maven build manager for working with Java applications. If you aren’t using maven and are instead using Apache Ant or your own build system, then simply add the spymemcached jar file as a dependency of your application.

For maven however, start by configuring it to have the proper spymemcached repository:

<repository>
  <id>spy</id>
  <name>Spy Repository</name>
  <layout>default</layout>
  <url>http://files.couchbase.com/maven2/</url>
  <snapshots>
    <enabled>false</enabled>
  </snapshots>
</repository>

Then add the spymemcached library to your dependencies:

<dependency>
  <groupId>spy</groupId>
  <artifactId>spymemcached</artifactId>
  <version>2.12.1</version>
  <scope>provided</scope>
</dependency>

Once your build system is configured, you can start adding caching to your Java app:

import java.io.IOException;
import net.spy.memcached.AddrUtil;
import net.spy.memcached.MemcachedClient;
import net.spy.memcached.ConnectionFactoryBuilder;
import net.spy.memcached.auth.PlainCallbackHandler;
import net.spy.memcached.auth.AuthDescriptor;

public class Foo {
  public static void main(String[] args) {
    AuthDescriptor ad = new AuthDescriptor(new String[] { "PLAIN" },
        new PlainCallbackHandler(System.getenv("MEMCACHIER_USERNAME"),
            System.getenv("MEMCACHIER_PASSWORD")));

    try {
      MemcachedClient mc = new MemcachedClient(
          new ConnectionFactoryBuilder()
              .setProtocol(ConnectionFactoryBuilder.Protocol.BINARY)
              .setAuthDescriptor(ad).build(),
          AddrUtil.getAddresses(System.getenv("MEMCACHIER_SERVERS")));
      mc.set("foo", "bar");
      System.out.println(mc.get("foo"));
    } catch (IOException ioe) {
      System.err.println("Couldn't create a connection to MemCachier: \nIOException "
              + ioe.getMessage());
    }
  }
}

You may want to set the above code up as a new MemCachierClient class:

package com.memcachier.examples.java;

import java.io.IOException;
import java.net.InetSocketAddress;
import java.util.ArrayList;
import java.util.List;

import javax.security.auth.callback.CallbackHandler;

import net.spy.memcached.ConnectionFactory;
import net.spy.memcached.ConnectionFactoryBuilder;
import net.spy.memcached.MemcachedClient;
import net.spy.memcached.auth.AuthDescriptor;
import net.spy.memcached.auth.PlainCallbackHandler;

public class MemCachierClient extends MemcachedClient {

   public MemCachierClient(String username, String password, String servers) throws IOException {
       this(new SASLConnectionFactoryBuilder().build(username, password), getAddresses(servers));
   }

   public MemCachierClient(ConnectionFactory cf, List<InetSocketAddress> addrs) throws IOException {
       super(cf, addrs);
   }

   private static List<InetSocketAddress> getAddresses(String servers) {
       List<InetSocketAddress> addrList = new ArrayList<InetSocketAddress>();
       for (String server : servers.split(",")) {
           String addr = server.split(":")[0];
           int port = Integer.parseInt(server.split(":")[1]);
           addrList.add(new InetSocketAddress(addr, port));
       }
       return addrList;
   }
}

class SASLConnectionFactoryBuilder extends ConnectionFactoryBuilder {
   public ConnectionFactory build(String username, String password){
       CallbackHandler ch = new PlainCallbackHandler(username, password);
       AuthDescriptor ad = new AuthDescriptor(new String[]{"PLAIN"}, ch);
       this.setProtocol(Protocol.BINARY);
       this.setAuthDescriptor(ad);
       return this.build();
   }
}

You may wish to look the spymemcached JavaDocs or some more example code to help in using MemCachier effectively. There is also a guide on using WebRunner, Heroku’s framework to handle sessions with MemCachier.

Client library support

MemCachier will work with any memcached binding that supports SASL authentication and the binary protocol. We have tested MemCachier with the following language bindings, although the chances are good that other SASL binary protocol packages will also work.

Sample applications

We’ve built a number of working sample apps:

• Sinatra Example
• Rails Example
• Django Example
• PHP Example
• Node.js Example
• Java Example

Local usage

To test your Heroku application locally, you will need to run a local memcached server. MemCachier can only run in Heroku, but because MemCachier and memcached speak the same protocol, you shouldn’t have any issues testing locally. Installation depends on your platform.

On Ubuntu:

$ sudo apt-get install memcached

Or on OS X (with Homebrew):

$ brew install memcached

For further information and resources (such as the memcached source code) please refer to the Memcache.org homepage

To run memcached simply execute the following command:

$ memcached -v

Usage analytics

Our analytics dashboard is a simple tool that gives you more insight into how you’re using memcache. Here’s a screenshot of the dashboard:

To access your application’s analytics dashboard run:

$ heroku addons:open memcachier

Or open MemCachier from your application’s dashboard on heroku.com.

The analytics displayed are:

• Limit – Your current cache size and memory limit. Once usage comes close to this amount you will start seeing evictions.
• Live Connections – Number of connections currently open to your cache.
• Total connections – Number of connections ever made to your cache. (So always larger than live connections).
• Items – Number of items currently stored in your cache.
• Evictions – Number of items ever evicted from your cache due to memory pressure. Items are evicted in an LRU order.
• New Evictions – Number of evictions that have occured since the last time we sampled your cache.
• Hit Rate – The ratio of get commands that return an item (hit) vs. the number that return nothing (miss). This ratio is for the period between now and when we last sampled your cache.
• Set Cmds – Number of times you have ever performed a set command.
• Flush Cmds – Number of times you have ever performned a flush command.

With the basic analytics dashboard we sample your cache once per hour. With the advance dashboard we sample it once every 30 minutes.

Advanced analytics

We offer higher paying customers an advance version of our analytics dashboard. Currently, this offers two primary advantages:

• Higher Sample Rate – We sample the cache for collecting analytics once every thirty minutes, twice the rate of the basic analytics dashboard. We don’t sample more often than that as a higher granularity hasn’t proven to be useful, it leads to more noise and less signal.
• More Graphs – We offer two additional graphs for the advanced analytics dashboard.
  • Eviction Graph – Your new evictions tracked over time.
  • Connection Graph – Your new connecions tracked over time.

Analytics API

You can also access features available on the analytics dashboard via the API.

• Authenticate
• Memcachier API ID
• Stats
• History
• Flush
• List Credentials
• Create Credentials
• Update Credentials
• Promote Credentials
• Delete Credentials

Authentication

Memcachier uses credentials to allow access to the API. After you’ve created a cache, you can find your credentials on the analytics dashboard. Only credentials that have the API capability will be allowed to use this API.

Memcachier expects for your credentials to be included in the header of all API requests.

curl "https://analytics.memcachier.com/api/v1/:memcachier_id/:action"
  --user CRED_USERNAME:CRED_PASSWORD

Make sure to replace CRED_USERNAME:CRED_PASSWORD with your credential username and password found on the analytics dashboard.

Memcachier API ID

All of the API paths include a <memcachier_id> variable. In order to find this ID, you’ll need to use the /login path.

This is not the same thing as the “Memcachier ID” listed on your analytics dashboard.

HTTP Request

GET https://analytics.memcachier.com/api/login

Response

Example:

curl "https://analytics.memcachier.com/api/v1/login"
  --user CRED_USERNAME:CRED_PASSWORD

Returns:

{
    "cache_id": 1561
}

Stats

This endpoint retrieves all the statistics for your cache.

HTTP Request

GET https://analytics.memcachier.com/api/v1/<memcachier_id>/stats

Response

Example:

curl "https://analytics.memcachier.com/api/v1/<memcachier_id>/stats"
  --user "CRED_USERNAME:CRED_PASSWORD"

Returns:

{
    "a.b.c.totallyaserver.com:12345": {
        "auth_cmds": 19,
        "auth_errors": 0,
        "bytes": 0,
        "bytes_read": 960,
        "bytes_written": 22233,
        "cas_badval": 0,
        "cas_hits": 0,
        "cas_misses": 0,
        "cmd_delete": 0,
        "cmd_flush": 0,
        "cmd_get": 0,
        "cmd_set": 0,
        "cmd_touch": 0,
        "curr_connections": 0,
        "curr_items": 0,
        "decr_hits": 0,
        "decr_misses": 0,
        "delete_hits": 0,
        "delete_misses": 0,
        "evictions": 0,
        "expired": 0,
        "get_hits": 0,
        "get_misses": 0,
        "incr_hits": 0,
        "incr_misses": 0,
        "limit_maxbytes": 28835840,
        "time": 1500651085,
        "total_connections": 19,
        "total_items": 0,
        "touch_hits": 0,
        "touch_misses": 0
    }
}

History

This endpoint retrieves the statistical history of a cache.

HTTP Request

GET https://analytics.memcachier.com/api/v1/<memcachier_id>/history

Response

Example:

curl "https://analytics.memcachier.com/api/v1/<memcachier_id>/history"
  --user "CRED_USERNAME:CRED_PASSWORD"

Returns:

  [{
    "memcachier_id": "11",
    "server": "a.b.c.totallyaserver.memcachier.com",
    "stats": {
        "auth_cmds": 158,
        "auth_errors": 0,
        "bytes": 0,
        "bytes_read": 3840,
        "bytes_written": 178754,
        "cas_badval": 0,
        "cas_hits": 0,
        "cas_misses": 0,
        "cmd_delete": 0,
        "cmd_flush": 0,
        "cmd_get": 0,
        "cmd_set": 0,
        "cmd_touch": 0,
        "curr_connections": 2,
        "curr_items": 0,
        "decr_hits": 0,
        "decr_misses": 0,
        "delete_hits": 0,
        "delete_misses": 0,
        "evictions": 0,
        "expired": 0,
        "get_hits": 0,
        "get_misses": 0,
        "incr_hits": 0,
        "incr_misses": 0,
        "limit_maxbytes": 1153433600,
        "time": 1490731542,
        "total_connections": 158,
        "total_items": 0,
        "touch_hits": 0,
        "touch_misses": 0
    },
    "timestamp": "1490731541096"
    }, … ]

Flush

This endpoint will flush all of the data from the cache cache.

HTTP Request

POST https://analytics.memcachier.com/api/v1/<memcachier_id>/flush

Response

Example:

curl "https://analytics.memcachier.com/api/v1/<memcachier_id>/flush" -X POST
  --user "CRED_USERNAME:CRED_PASSWORD"

Certain credentials may not have permission to flush the cache, which will produce a 403 error.

List Credentials

The endpoint returns a list of all the credentials connected to the cache.

HTTP Request

GET https://analytics.memcachier.com/api/v1/<memcachier_id>/credentials

Response

Example:

curl "https://analytics.memcachier.com/api/v1/<memcachier_id>/credentials"
  --user "CRED_USERNAME:CRED_PASSWORD"

Returns:

  [
    {
        "cache_id": 14,
        "flush_capability": false,
        "id": 44,
        "sasl_username": "CRED_USERNAME",
        "uuid": null,
        "write_capability": true,
        "api_capability": true,
        "primary": true,
    },
    {
        "cache_id": 14,
        "flush_capability": false,
        "id": 43,
        "sasl_username": "789101",
        "uuid": null,
        "write_capability": true,
        "api_capability": true,
        "primary": false,
    }, ...
]

Create Credentials

This endpoint creates a new set of credentials which can be used to connect to the cache.

HTTP Request

POST https://analytics.memcachier.com/api/v1/<memcachier_id>/credentials

Response

Example:

curl "https://analytics.memcachier.com/api/v1/<memcachier_id>/credentials" -X POST
  --user "CRED_USERNAME:CRED_PASSWORD"

Returns:

{
    "cache_id": 14,
    "id": null,
    "sasl_password": "CRED_PASSWORD",
    "sasl_username": "CRED_USERNAME",
    "uuid": null,
    "primary": false,
    "flush_capability": true,
    "write_capability": true,
    "api_capability": true,
}

Update Credentials

This endpoint updates the capabilities of a specific set of credentials.

HTTP Request

POST https://analytics.memcachier.com/api/v1/<memcachier_id>/credentials/<cred_id>

Query Parameters

Response

Example:

curl "https://analytics.memcachier.com/api/v1/<memcachier_id>/credentials/<cred_username>" -X PATCH
  -d '{"flush_capability":"false"}'
  --user "CRED_USERNAME:CRED_PASSWORD"

Returns:

{
    "flush_capability": false,
    "write_capability": true,
    "api_capability": true,
}

Promote Credentials

This endpoint promotes a set of credentials to primary.

HTTP Request

POST https://analytics.memcachier.com/api/v1/<memcachier_id>/credentials/primary/<cred_id>

Response

Example:

curl "https://analytics.memcachier.com/api/v1/<memcachier_id>/credentials/primary/<cred_username>" -X POST
  --user "CRED_USERNAME:CRED_PASSWORD"

Returns:

{
    "cache_id": 14,
    "id": null,
    "sasl_username": "CRED_USERNAME",
    "uuid": null,
    "primary": true,
    "flush_capability": false,
    "write_capability": true,
    "api_capability": true,
}

Delete Credentials

This endpoint deletes a set of credentials

HTTP Request

POST https://analytics.memcachier.com/api/v1/<memcachier_id>/credentials/primary/<cred_id>

Response

Example:

curl "https://analytics.memcachier.com/api/v1/<memcachier_id>/credentials/primary/<cred_username>" -X DELETE
  --user "CRED_USERNAME:CRED_PASSWORD"

New Relic integration

MemCachier supports integration with your New Relic dashboard if you happen to be a customer of both MemCachier and New Relic. Currently this feature is only available to caches of 500MB or larger. A blog post showing the integration can be found here.

To setup the integration you will need to find your New Relic license key. This can be done by going to your “Account Settings” page when logged in to New Relic by click on your New Relic username in the top right corner. Then you will find your license key in the right side information column. It should be exactly 40 characters long. Please refer to the blog post for a visual walkthrough.

Once you have your New Relic licence key, it can be entered for your cache on the analytics dashboard page. In the bottom right corner there is a button to do this.

Credentials

In order to connect a memcache client to MemCachier, you use a username and password listed on the dashboard for your cache. Each cache can have multiple sets of credentials. One of these sets of credentials is distinguished as primary, meaning that it is linked to the Heroku MemCachier addon.

From the Credentials panel on the analytics dashboard, it is possible to create new credentials, delete existing credentials and promote secondary credentials to primary credentials. This makes it possible to rotate credentials by creating a new set of secondary credentials and promoting them to primary. Promoting a set of secondary credentials to primary causes an update of the MEMCACHIER_USERNAME and MEMCACHIER_PASSWORD Heroku configuration variables on your Heroku app and a restart of your dynos to pick up the new values.

Each set of credentials for a cache can be given different capabilities, in the sense that sets of credentials can be restricted to read-only access to the cache, or prevented from flushing the cache via the memcache API. These capabilities are controlled by checkboxes on the Credentials panel of the analytics dashboard. (The exact error conditions that a client will receive if it attempts to perform an action for which it does not have the capability depends on the details of the client library used. The most common cases are likely to be for the Dalli Ruby library and the pylibmc Python library. For both of these client libraries, attempting to set a cache entry using credentials that do not have the write capability will simply result in a “value not set” response from the library.)

Disabled Caches

Development caches are disabled after 30 days of inactivity. Disabled caches can no longer be accessed (authentication will fail). To use the caches again it can be re-enabled on the analytics dashboard under the Settings panel.

Encrypted Connections (TLS)

It is possible to connect to MemCachier using TLS encrypted sockets. While no existing clients support TLS connections natively, we provide a buildpack for Heroku customers that proxies the connection to MemCachier and wraps it in a TLS connection. This can be useful for the extra paranoid among us, or to securely access your cache from outside the datacenter.

The buildpack installs and sets up stunnel on localhost listening on port 11211. It configures stunnel to connect to the MemCachier servers specified in your environment variable and to verify certificates as signed by the MemCachier Root CA.

Use the buildpack in conjunction with another buildpack that actually runs your app, using Heroku’s multiple buildpack feature:

$ heroku buildpacks:add https://github.com/memcachier/memcachier-tls-buildpack.git

Finally, configure your app to connect to localhost:11211 instead of using the MEMCACHIER_SERVERS environment variable, but, leave your MEMCACHIER_SERVERS environment variable unchanged as the TLS buildpack uses it to connect to MemCachier.

Upgrading and downgrading

Changing your plan, either by upgrading or downgrading, can be done easily at any time through Heroku.

• No code changes are required.
• Your cache won’t be lost or reset*.
• You are charged by the hour for plans, so try experimenting with different cache sizes with low cost.

Using MemCachier

Please refer to your client or framework documentation for how to use MemCachier effectively.

MemCachier Guides:

• Advanced Memcache Usage
• Building a Rails 3 App with MemCachier
• Rails + Rack::Cache + MemCachier
• Django and MemCachier
• Java Webapp Runner Guide
• Heroku’s Guide to Caching

Framework and Client Documentation:

• Dalli (Ruby Client) API
• Rails Caching Guide
• PHP Memcached client
• CakePHP Caching Guide
• Pylibmc (Pytnon Client) API
• Django Caching Guide
• MemJS (node.js client) API
• Spymemcached JavaDocs

Key-Value size limit (1MB)

MemCachier has a maximum size that a key-value object can be of 1MB. This applies to both key-value pairs created through a set command, or existing key-value pairs grown through the use of an append or prepend command. In the later case, the size of the key-value pair with the new data added to it, must still be less than 1MB.

The 1MB limit applies to the size of the key and the value together. A key of size 512KB with a value of 712KB would be in violation of the 1MB limit.

The reason for this has partially to do with how memory is managed in MemCachier. A limitation of the high performance design is a restriction on how large key-value pairs can become. Another reason is that storing values larger than 1MB doesn’t normally make sense in a high-performance key-value store. The network transfer time in these situations becomes the limiting factor for performance. A disk cache or even a database makes sense for this size value.

Errors about app trying to connect to localhost

By default, most memcache client look for the environment variables, MEMCACHE_SERVERS, MEMCACHE_USERNAME and MEMCACHE_PASSWORD for their configuration. These variables are used when the initialization code for the memcache client doesn’t specifically specify these values.

If these environment variables aren’t set, clients generally default to connecting to 127.0.0.1:11211 (i.e., localhost), with no username and password.

The MemCachier add-on sets the MEMCACHIER_SERVERS, MEMCACHIER_USERNAME and MEMCACHIER_PASSWORD environment variables. So you need to either set the equivalent MEMCACHE_* variables from these, or pass these values to your client when you create a new one in your code.

For example, pseudo-code for the first approach is:

env[MEMCACHE_SERVERS] = env[MEMCACHIER_SERVERS]
env[MEMCACHE_USERNAME] = env[MEMCACHIER_USERNAME]
env[MEMCACHE_PASSWORD] = env[MEMCACHIER_PASSWORD]

While pseudo-code for the second approach is:

memClient = new MemcacheClient(ENV['MEMCACHIER_SERVERS'],
                               ENV['MEMCACHIER_USERNAME'],
                               ENV['MEMCACHIER_PASSWORD'])

Please be careful that you have setup the your client in all locations. Many frameworks, such as Rails, use memcache in multiple ways and may require you to setup initialization properly in a few locations. Generally the first approach is preferred as it is global while the second approach is local to each initialization.

For example, with Ruby on Rails, you’ll need to setup cache_store, Rack::Cache and the session_store.

Support

All MemCachier support and runtime issues should be submitted via on of the Heroku Support channels. You can also reach us directly at support@memcachier.com. We encourage you to CC us on any urgent support tickets sent to Heroku. Please include your MEMCACHIER_USERNAME with support tickets.

Any non-support related issues or product feedback is welcome via email at: support@memcachier.com.

Any issues related to MemCachier service are reported at MemCachier Status.

Please also follow us on twitter, @memcachier, for status and product announcements.