<commit_before># Candies[![travis-ci](https://secure.travis-ci.org/martinciu/candies.png?branch=master)](http://travis-ci.org/martinciu/candies)
Invisible image based tracing service with Redis backend

## Requirements

Candies uses redis as a datastore.

Candies only supports redis 2.0 or greater.

If you're on OS X, Homebrew is the simplest way to install Redis:

    $ brew install redis
    $ redis-server /usr/local/etc/redis.conf

You now have a Redis daemon running on 6379.

## Setup

If you are using bundler add candies to your Gemfile:

    gem 'candies'

Then run:

    bundle install

Otherwise install the gem:

    gem install candies

and require it in your project:

    require 'candies'

## Usage

### Standalone service

Candies can be deployed as a standalone service (for example to heroku). To do it create a simple `config.ru` file:

    require 'rubygems'
    require 'candies'

    # Candies.redis = ENV['REDISTOGO_URL'], read below about redis configuration

    run Candies::Server.new

and deploy it to any `rack` compatybile environment (passenger, thin, unicorn, etc.)

### Mounted to the Rails app

Mount Candies in your `config/routes.rb` file:

    mount Candies::Server.new => "candies", :as => "candies"

It will be available under `http://yourapproot.tld/candies` url

### Image tag

When you have Candies server deployed you can add tracking payload by including `img` tag in your HTML code:

    <a href="http://candies.tld/anyfile.gif?id=tracing-id&foo=bar&baz=foo" />

or if you mounted candies in your rails app as `candies` then it will be:

    <a href="http://yourapproot.tld/candies/anyfile.gif?id=tracing-id&foo=bar&baz=foo" />

Also in rails app you can use `candies_image_tag` helper. To do so you have to set `Candies.url` to point to the candies service url. The best way is to put in `config/initializers/candies.rb` file:
    
    Candies.host = "http://yourapproot.tld/candies"

Now you can use `candies_image_tag` helper in controller views and in mailer views. Example:

    <%= candies_image_tag(:id => "<EMAIL>", :email_type => "hello") %>

Note that `id` parameter is required. It will be used to create a redis key under which paload will be stored. In this case redis key will be: `candies:<EMAIL>:2011-11-10T13:13:09+01:00` and value: `"{\"email_type\":\"hello\"}"`. If you don't specify `id` parameter not value will be stored. Invisible image will by served anyway.

## Configuration

### Redis

You may want to change the Redis host and port Candies connects to, or
set various other options at startup.

Candies has a `redis` setter which can be given a string or a Redis
object. This means if you're already using Redis in your app, Candies
can re-use the existing connection.

String: `Candies.redis = 'localhost:6379'`

Redis: `Candies.redis = $redis`

For our rails app we have a `config/initializers/candies.rb` file where
we load `config/candies.yml` by hand and set the Redis information
appropriately.

Here's our `config/redis.yml`:

    development: localhost:6379
    test: localhost:6379
    staging: redis1.example.com:6379
    fi: localhost:6379
    production: redis1.example.com:6379

And our initializer:<commit_msg>readme updated<commit_after># Candies
[![travis-ci](https://secure.travis-ci.org/martinciu/candies.png?branch=master)](http://travis-ci.org/martinciu/candies)
####Invisible image based tracing service with Redis backend

## Usage

### Standalone service

Candies can be deployed as a standalone service (for example to heroku). To do it create a simple `config.ru` file:

    require 'rubygems'
    require 'candies'

    # Candies.redis = ENV['REDISTOGO_URL'], read below about redis configuration

    run Candies::Server.new

and deploy it to any `rack` compatybile environment (passenger, thin, unicorn, etc.)

### Mounted to the Rails app

Mount Candies in your `config/routes.rb` file:

    mount Candies::Server.new => "candies", :as => "candies"

It will be available under `http://yourapproot.tld/candies` url

### Image tag

When you have Candies server deployed you can add tracking payload by including `img` tag in your HTML code:

    <a href="http://candies.tld/anyfile.gif?id=tracing-id&foo=bar&baz=foo" />

or if you mounted candies in your rails app as `candies` then it will be:

    <a href="http://yourapproot.tld/candies/anyfile.gif?id=tracing-id&foo=bar&baz=foo" />

Also in rails app you can use `candies_image_tag` helper. To do so you have to set `Candies.url` to point to the candies service url. The best way is to put in `config/initializers/candies.rb` file:
    
    Candies.host = "http://yourapproot.tld/candies"

Now you can use `candies_image_tag` helper in controller views and in mailer views. Example:

    <%= candies_image_tag(:id => "<EMAIL>", :email_type => "hello") %>

Note that `id` parameter is required. It will be used to create a redis key under which paload will be stored. In this case redis key will be: `candies:<EMAIL>.com:2011-11-10T13:13:09+01:00` and value: `"{\"email_type\":\"hello\"}"`. If you don't specify `id` parameter not value will be stored. Invisible image will by served anyway.

## Requirements

Candies uses redis as a datastore.

Candies only supports redis 2.0 or greater.

If you're on OS X, Homebrew is the simplest way to install Redis:

    $ brew install redis
    $ redis-server /usr/local/etc/redis.conf

You now have a Redis daemon running on 6379.

## Setup

If you are using bundler add candies to your Gemfile:

    gem 'candies'

Then run:

    bundle install

Otherwise install the gem:

    gem install candies

and require it in your project:

    require 'candies'

## Configuration

### Redis

You may want to change the Redis host and port Candies connects to, or
set various other options at startup.

Candies has a `redis` setter which can be given a string or a Redis
object. This means if you're already using Redis in your app, Candies
can re-use the existing connection.

String: `Candies.redis = 'localhost:6379'`

Redis: `Candies.redis = $redis`

For our rails app we have a `config/initializers/candies.rb` file where
we load `config/candies.yml` by hand and set the Redis information
appropriately.

Here's our `config/redis.yml`:

    development: localhost:6379
    test: localhost:6379
    staging: redis1.example.com:6379
    fi: localhost:6379
    production: redis1.example.com:6379

And our initializer:
{'fraction_non_alphanumeric': 0.0987211478477854, 'fraction_numerical': 0.015595757953836557, 'mean_word_length': 4.017996870109546, 'pattern_counts': {'":': 2, '<': 13, '<?xml version=': 0, '>': 21, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6754051', 'n_tokens_mistral': 2211, 'n_tokens_neox': 2074, 'n_words': 785}