Integration Guide - Ruby (Rack, Rails) SDK

Built For rack Latest Version Total Downloads Software License Source Code

Rack Middleware that logs API calls and sends to Moesif for API analytics and log analysis.

Supports Ruby on Rails apps and other Ruby frameworks built on Rack.

Source Code on GitHub

How to install

gem install moesif_rack

and if you have a Gemfile in your project, please add this line to

gem 'moesif_rack', '~> 1.4.0'

How to use

Create the options

moesif_options = {
  'application_id' => 'Your Moesif Application Id',
  'log_body' => true,
}

Your Moesif Application Id can be found in the Moesif Portal. After signing up for a Moesif account, your Moesif Application Id will be displayed during the onboarding steps.

You can always find your Moesif Application Id at any time by logging into the Moesif Portal, click on the top right menu, and then clicking Installation.

Add to middleware

Using strings or symbols for middleware class names is deprecated for newer frameworks like Ruby 5.0, so you should pass the class directly.

For Rails 5.0 or newer:

  class Application < Rails::Application
    # snip

    config.middleware.use MoesifRack::MoesifMiddleware, moesif_options

    # snip
  end

For other frameworks:

within config/application.rb

  class Application < Rails::Application
    # snip

    config.middleware.use "MoesifRack::MoesifMiddleware", moesif_options

    # snip
  end

Order of Middleware Matters

Since Moesif Rack is a logging middleware, the ordering of middleware matters for accuracy and data collection. Many middleware are installed by default by Rails.

The best place for “MoesifRack::MoesifMidleware” is on top (so it captures the data closest to the wire). Typically, right above the default logger of Rails apps, “Rails::Rack::Logger” is a good spot. Or if you want to be as close as wire as possible, put it before “ActionDispatch::Static”

To insert the Moesif middleware before “Rails::Rack::Logger”, you can use the insert_before method instead of use

  class Application < Rails::Application
    # snip

    config.middleware.insert_before Rails::Rack::Logger, MoesifRack::MoesifMiddleware, moesif_options

    # snip
  end

If you are using “Rack::Deflater” or other compression middleware, make sure Moesif is after it, so it can capture the uncompressed data.

To see your current list of middleware:

  bin/rails middleware

Configuration options

The options is a hash with these possible key value pairs.

application_id

Required. String. This is the Moesif application_id under settings from your Moesif account.

api_version

Optional. String. Tag requests with the version of your API.

identify_user

Optional. identify_user is a Proc that takes env, headers, and body as arguments and returns a user_id string. This helps us attribute requests to unique users. Even though Moesif can automatically retrieve the user_id without this, this is highly recommended to ensure accurate attribution.

moesif_options['identify_user'] = Proc.new { |env, headers, body|

  # Add your custom code that returns a string for user id
  '12345'
}

identify_company

Optional. identify_company is a Proc that takes env, headers, and body as arguments and returns a company_id string. This helps us attribute requests to unique company.


moesif_options['identify_company'] = Proc.new { |env, headers, body|

  # Add your custom code that returns a string for company id
  '67890'
}

identify_session

Optional. A Proc that takes env, headers, body and returns a string.


moesif_options['identify_session'] = Proc.new { |env, headers, body|
    # Add your custom code that returns a string for session/API token
    'XXXXXXXXX'
}

get_metadata

Optional. get_metadata is a Proc that takes env, headers, and body as arguments and returns a Hash that is representation of a JSON object. This allows you to attach any metadata to this event.


moesif_options['get_metadata'] = Proc.new { |env, headers, body|
  # Add your custom code that returns a dictionary
  value = {
      'datacenter'  => 'westus',
      'deployment_version'  => 'v1.2.3'
  }
  value
}

mask_data

Optional. A Proc that takes event_model as an argument and returns event_model. With mask_data, you can make modifications to headers or body of the event before it is sent to Moesif.


moesif_options['mask_data'] = Proc.new { |event_model|
  # Add your custom code that returns a event_model after modifying any fields
  event_model.response.body.password = nil
  event_model
}

For details for the spec of event model, please see the moesifapi-ruby

skip

Optional. A Proc that takes env, headers, body and returns a boolean.


moesif_options['skip'] = Proc.new { |env, headers, body|
  # Add your custom code that returns true to skip logging the API call
  false
}

For details for the spec of event model, please see the Moesif Ruby API Documentation

debug

Optional. Boolean. Default false. If true, it will print out debug messages. In debug mode, the processing is not done in backend thread.

log_body

Optional. Boolean. Default true. If false, will not log request and response body to Moesif.

capture_outgoing_requests

Optional. boolean, Default false. Set to true to capture all outgoing API calls from your app to third parties like Stripe, Github or to your own dependencies while using Net::HTTP package. The options below is applied to outgoing API calls. When the request is outgoing, for options functions that take request and response as input arguments, the request and response objects passed in are Request request and Response response objects.

identify_user_outgoing

Optional. identify_user_outgoing is a Proc that takes request and response as arguments and returns a user_id string. This helps us attribute requests to unique users. Even though Moesif can automatically retrieve the user_id without this, this is highly recommended to ensure accurate attribution.


moesif_options['identify_user_outgoing'] = Proc.new { |request, response|

  # Add your custom code that returns a string for user id
  '12345'
}

identify_company_outgoing

Optional. identify_company_outgoing is a Proc that takes request and response as arguments and returns a company_id string. This helps us attribute requests to unique company.


moesif_options['identify_company_outgoing'] = Proc.new { |request, response|

  # Add your custom code that returns a string for company id
  '67890'
}

get_metadata_outgoing

Optional. get_metadata_outgoing is a Proc that takes request and response as arguments and returns a Hash that is representation of a JSON object. This allows you to attach any metadata to this event.


moesif_options['get_metadata_outgoing'] = Proc.new { |request, response|

  # Add your custom code that returns a dictionary
  value = {
      'datacenter'  => 'westus',
      'deployment_version'  => 'v1.2.3'
  }
  value
}
identify_session_outgoing

Optional. A Proc that takes request, response and returns a string.


moesif_options['identify_session_outgoing'] = Proc.new { |request, response|

    # Add your custom code that returns a string for session/API token
    'XXXXXXXXX'
}

skip_outgoing

Optional. A Proc that takes request, response and returns a boolean. If true would skip sending the particular event.


moesif_options['skip_outgoing'] = Proc.new{ |request, response|

  # Add your custom code that returns true to skip logging the API call
  false
}

mask_data_outgoing

Optional. A Proc that takes event_model as an argument and returns event_model. With mask_data_outgoing, you can make modifications to headers or body of the event before it is sent to Moesif.


moesif_options['mask_data_outgoing'] = Proc.new { |event_model|

  # Add your custom code that returns a event_model after modifying any fields
  event_model.response.body.password = nil
  event_model
}

log_body_outgoing

Optional. Boolean. Default true. If false, will not log request and response body to Moesif.

Update User

Update a Single User

Create or update a user profile in Moesif. The metadata field can be any customer demographic or other info you want to store. Only the user_id field is required. This method is a convenient helper that calls the Moesif API lib. For details, visit the Ruby API Reference.

metadata = {
  :email => 'john@acmeinc.com',
  :first_name => 'John',
  :last_name => 'Doe',
  :title => 'Software Engineer',
  :salesInfo => {
      :stage => 'Customer',
      :lifetime_value => 24000,
      :accountOwner => 'mary@contoso.com',
  }
}

campaign = MoesifApi::CampaignModel.new()
campaign.utm_source = "google"
campaign.utm_medium = "cpc"
campaign.utm_campaign = "adwords"
campaign.utm_term = "api+tooling"
campaign.utm_content = "landing"

user = MoesifApi::UserModel.new()
user.user_id = "12345"
user.company_id = "67890" # If set, associate user with a company object
user.campaign = campaign
user.metadata = metadata

update_user = MoesifRack::MoesifMiddleware.new(@app, @options).update_user(user_model)

Update Users in Batch

Similar to update_user, but used to update a list of users in one batch. Only the user_id field is required. This method is a convenient helper that calls the Moesif API lib. For details, visit the Ruby API Reference.

users = []

metadata = {
  :email => 'john@acmeinc.com',
  :first_name => 'John',
  :last_name => 'Doe',
  :title => 'Software Engineer',
  :salesInfo => {
      :stage => 'Customer',
      :lifetime_value => 24000,
      :accountOwner => 'mary@contoso.com',
  }
}

campaign = MoesifApi::CampaignModel.new()
campaign.utm_source = "google"
campaign.utm_medium = "cpc"
campaign.utm_campaign = "adwords"
campaign.utm_term = "api+tooling"
campaign.utm_content = "landing"

user = MoesifApi::UserModel.new()
user.user_id = "12345"
user.company_id = "67890" # If set, associate user with a company object
user.campaign = campaign
user.metadata = metadata

users << user

response = MoesifRack::MoesifMiddleware.new(@app, @options).update_users_batch(users)

Update Company

Update a Single Company

Create or update a company profile in Moesif. The metadata field can be any company demographic or other info you want to store. Only the company_id field is required. This method is a convenient helper that calls the Moesif API lib. For details, visit the Ruby API Reference.

metadata = {
  :org_name => 'Acme, Inc',
  :plan_name => 'Free',
  :deal_stage => 'Lead',
  :mrr => 24000,
  :demographics => {
      :alexa_ranking => 500000,
      :employee_count => 47
  }
}

campaign = MoesifApi::CampaignModel.new()
campaign.utm_source = "google"
campaign.utm_medium = "cpc"
campaign.utm_campaign = "adwords"
campaign.utm_term = "api+tooling"
campaign.utm_content = "landing"

company = MoesifApi::CompanyModel.new()
company.company_id = "67890"
company.company_domain = "acmeinc.com" # If domain is set, Moesif will enrich your profiles with publicly available info 
company.campaign = campaign
company.metadata = metadata

update_company = MoesifRack::MoesifMiddleware.new(@app, @options).update_company(company_model)

Update Companies in Batch

Similar to update_company, but used to update a list of companies in one batch. Only the company_id field is required. This method is a convenient helper that calls the Moesif API lib. For details, visit the Ruby API Reference.

companies = []

metadata = {
  :org_name => 'Acme, Inc',
  :plan_name => 'Free',
  :deal_stage => 'Lead',
  :mrr => 24000,
  :demographics => {
      :alexa_ranking => 500000,
      :employee_count => 47
  }
}

campaign = MoesifApi::CampaignModel.new()
campaign.utm_source = "google"
campaign.utm_medium = "cpc"
campaign.utm_campaign = "adwords"
campaign.utm_term = "api+tooling"
campaign.utm_content = "landing"

company = MoesifApi::CompanyModel.new()
company.company_id = "67890"
company.company_domain = "acmeinc.com" # If domain is set, Moesif will enrich your profiles with publicly available info 
company.campaign = campaign
company.metadata = metadata

companies << company
response = MoesifRack::MoesifMiddleware.new(@app, @options).update_companies_batch(companies)

How to test

  1. Manually clone the git repo
  2. From terminal/cmd navigate to the root directory of the middleware.
  3. Invoke ‘gem install moesif_rack’
  4. Add your own application id to ‘test/moesif_rack_test.rb’. You can find your Application Id from Moesif Dashboard -> Top Right Menu -> Installation
  5. Invoke ‘ruby test/moesif_rack_test.rb’
  6. Invoke ‘ruby -I test test/moesif_rack_test.rb -n test_capture_outgoing’ to test capturing outgoing API calls from your app to third parties like Stripe, Github or to your own dependencies.

Example Code

Moesif Rack Example with Rails is an example of Moesif Rack applied to a Rails application.

Moesif Rack Example is an example of Moesif Rack applied to a Rack application.

Other integrations

To view more documentation on integration options, please visit the Integration Options Documentation.