Skip to content
Microsoft Application Insights for Rails, Sinatra, Cuba, etc
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs/images Add Theorem Readme footer Jan 24, 2020
test Test base installer Feb 12, 2015
.gems Update dependencies Feb 26, 2015
LICENSE Add Theorem Readme footer Jan 24, 2020
appinsights.gemspec Update gemspec with Theorem migration Jan 24, 2020
rakefile Add a rakefile Feb 11, 2015


Gem Version Build Status Code Climate

Microsoft Application Insights Auto Installer for Ruby frameworks


appinsights requires:

  • Ruby 2.0 or later
  • application_insights to connect with Microsoft Application Insights
  • toml-rb to read the config file

Install dependencies using dep is easy as run:

$ dep install


Install the latest release using gem

$ gem install appinsights

Or just add gem 'appinsights' in your Gemfile and then run:

$ bundle install


This is the recommended installation and it will be automatically fired if your application uses one of the supported frameworks:

  • Rails
  • Sinatra

In case the automatic installation is not available (non-supported framework, missing config file, etc.) you can always install the Application Insights Instruments using the Manual installation


rails automatically loads the gem if it is listed on the Gemfile. There is nothing else to do.


sinatra, like other rack based frameworks, needs to require the library.

Add the following line in your sinatra application file:

require 'appinsights'

NOTE: Ensure that sinatra was required first.


cuba is similar to sinatra but it requires one more line to configure it. Since a cuba application does not keep the root path of the application we have to specify it to read the config file and complete the installation. Given this is a common framework, there is a one-step-installation line:

require 'appinsights'

# Accepts the root path of the application and an optional file name
AppInsights::CubaInstaller.init File.dirname(__FILE__)


Choosing a Manual configuration is for those who have an application using a non-supported framework or the ones who wants to have total control of the application.

The only requisite for your application is to support usage of rack middlewares.

require 'appinsights'

# app - Application where we will attach the middlewares
# root - Root directory of the application
# filename (optional) - Relative path of the config file
# logger (optional) - Logger object to log errors and info.

installer = app, root, filename, logger

# Now you have an installer ready to be executed


# This will load the configuration file and add the middlewares enabled on the
# config file.

In case you want to check the configs or which middlewares were enabled using ruby code, here is some useful lines of code:

# Check the Context settings.
=> #<ApplicationInsights::Channel::TelemetryContext:0x007f961dbf3b18 ...>

# Check the Middlewares settings
=> [{"name"=>"AppInsights::ExceptionHandling", "enabled"=>true}, ... ]

# Check the Middlewares enabled
=> [[AppInsights::ExceptionHandling, {}], ... ]

Configuration file

appinsights uses TOML, a minimal configuration file format that's easy to read. If you are not familiar with TOML, please read the specs.


There are two big structures inside the configuration file.

  1. Application Insights Context settings
  2. Middlewares

1. Application Insights Context settings

All this settings must be grouped by 'ai' table. This settings are defined for every contract on the SDK

The only exception and the most important setting is the instrumentation_key that must be defined under the 'ai' table.

Lets see an example:

  instrumentation_key = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
  custom = 4
  properties = 'belong to the context'

# Contracts configuration

    ver = '0.2.0'

    id = 'device001'
    os = 'OSX'

    id = 'a_user_id'
    accountId = '1234567890'

2. Middlewares

This is the other important structure on the configuration file. Here we will define which middleware we want to use and enable or disable it. We defined appinsights to be as flexible as possible, so we can configure middlewares defined in other libraries but they were defined in our scope.

Of course that you can add extra parameters for your personal usage but there are two required parameters for every middleware definition:

  • name - Complete constant name of the middleware
  • enabled - boolean

And given there are some middleware which needs extra parameters at the initialization process, you can define a hash with the attributes and we will preserve the order of the attributes defined.

If you are a little confused, here is a valid example for both scenarios:

  name = 'AppInsights::ExceptionHandling'
  enabled = true

  name = 'ApplicationInsights::Rack::TrackRequest'
  enabled = true

    instrumentation_key = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
    buffer_size = 250
    send_interval = 30


By default appinsights will search for the configuration file, starting at the root of the project

  • ./config/application_insights.toml
  • ./application_insights.toml

You can also use a custom file name and path before start the application. Set the environment variable AI_CONFIG_RPATH with the relative path of the file

$ export AI_CONFIG_RPATH='./settings/appinsights_settings.toml'

About Theorem


This software is lovingly maintained and funded by Theorem. From whiteboarding new concepts to long-term support, Theorem works with startups and large multi-national enterprises to develop new applications, software, services, and platforms to achieve the best results and deliver Full Stack Innovation™

At Theorem we believe in and support open-source software.

Theorem and the Theorem logo are trademarks or registered trademarks of Theorem, LLC.

You can’t perform that action at this time.