appinsights
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.
- Application Insights Context settings
- 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'
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.
- Check out more of our open-source software at Theorem.
- Learn more about our work.
- Hire us to work on your project.
- Want to join the team?
Theorem and the Theorem logo are trademarks or registered trademarks of Theorem, LLC.