Microsoft Application Insights for Rails, Sinatra, Cuba, etc
Ruby
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gems
.gitignore
.travis.yml
LICENSE
README.md
appinsights.gemspec
rakefile

README.md

appinsights

Gem Version Build Status Code Climate Dependency Status

Microsoft Application Insights Auto Installer for Ruby frameworks

Dependencies

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

Installation

Install the latest release using gem

$ gem install appinsights

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

$ bundle install

Automatic

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

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

Sinatra

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

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__)

Manual

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 = AppInsights::BaseInstaller.new app, root, filename, logger

# Now you have an installer ready to be executed

installer.install

# 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.
Application::Context.context
=> #<ApplicationInsights::Channel::TelemetryContext:0x007f961dbf3b18 ...>


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

# Check the Middlewares enabled
AppInsights::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.

Structure

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:

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

# Contracts configuration

  [ai.application]
    ver = '0.2.0'

  [ai.device]
    id = 'device001'
    os = 'OSX'

  [ai.user]
    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:

[[middleware]]
  name = 'AppInsights::ExceptionHandling'
  enabled = true

[[middleware]]
  name = 'ApplicationInsights::Rack::TrackRequest'
  enabled = true

  [middleware.initialize]
    instrumentation_key = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
    buffer_size = 250
    send_interval = 30

Location

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'