appinsights 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 01003d9d4c44a67f7f73bb0ff83ce5a4d763a4ac
-  data.tar.gz: 880be6e1ab0a7bbb7726900c7c4af58b7dee518e
+  metadata.gz: 9d20dcc9f60a001f8ace5c97f9e9cb8157c0a9de
+  data.tar.gz: 83e30a63ca45290f6089ca93a221a67b85908307
 SHA512:
-  metadata.gz: fc062486cb66e7ca600f8f278e08a7a7e08cbddf370c4fbe7d5148d396a35439adce123fccbe9261b31134a9ab888284a5e7d7eac44e7c658bf7417794d0df09
-  data.tar.gz: 49ae01dd89528edbfda574e6bd43b33ab4415ccd6ae6502aff308074c7e7cc7c1161183be3512508151fcd43cdf101949f08532b8d31dc946d1bb9b1bec5ce74
+  metadata.gz: ff7a702005292eaa2e6d2e8dbc6ff960c8cfe82c1905d2a9f642e48418d501a0fe1d58980d2a3a978c539661071c07b9975cc4ef6acee48f5645647bdd7f0137
+  data.tar.gz: 969fa848c73a60da51faec3ffb187082f5598bda75ac607cc8590757a3c9684b3a1d30a851b5f91bd50c4e42f55a990494dd23278e469602464e96d86d7ae360

data/README.md

@@ -5,3 +5,191 @@
 [![Dependency Status](https://gemnasium.com/citrusbyte/appinsights.svg)](https://gemnasium.com/citrusbyte/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.
+
+## 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.
+
+```ruby
+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:
+
+```ruby
+# 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][toml_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][ai_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:
+
+```toml
+[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:
+
+```toml
+[[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'
+
+
+
+[toml_specs]: https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.3.1.md
+[ai_sdk]: https://github.com/Microsoft/AppInsights-Ruby/tree/master/lib/application_insights/channel/contracts

data/appinsights.gemspec

@@ -1,4 +1,4 @@
-require_relative 'lib/version'
+require_relative 'lib/appinsights/version'
 
 Gem::Specification.new do |s|
   s.name        = 'appinsights'

data/lib/appinsights.rb

@@ -1,14 +1,14 @@
-require_relative 'errors'
-require_relative 'context'
-require_relative 'middlewares'
-require_relative 'config_loader'
-require_relative 'installers/base'
+require_relative 'appinsights/errors'
+require_relative 'appinsights/context'
+require_relative 'appinsights/middlewares'
+require_relative 'appinsights/config_loader'
+require_relative 'appinsights/installers/base'
 
 module AppInsights
   if defined?(Rails::VERSION)
-    require_relative 'installers/rails'
+    require_relative 'appinsights/installers/rails'
   elsif defined?(Sinatra::VERSION)
-    require_relative 'installers/sinatra'
+    require_relative 'appinsights/installers/sinatra'
   else
     require 'logger'
 

data/lib/appinsights/installers/rails.rb

@@ -0,0 +1,18 @@
+require_relative 'base'
+
+module AppInsights
+  class RailsInstaller < Rails::Railtie
+    initializer 'appinsights.start_plugin' do |_app|
+      init Rails.root
+    end
+
+    def init(root, filename = nil)
+      installer = AppInsights::BaseInstaller.new config.app_middleware,
+                                                 root,
+                                                 filename,
+                                                 Rails.logger
+
+      installer.install
+    end
+  end
+end

data/lib/{installers → appinsights/installers}/sinatra.rb

@@ -7,9 +7,9 @@ module AppInsights
     end
 
     def self.init(root, filename = nil)
-      installer = AppInsights::Base.new Sinatra::Application,
-                                        root,
-                                        filename
+      installer = AppInsights::BaseInstaller.new Sinatra::Application,
+                                                 root,
+                                                 filename
 
       installer.install
     end

data/lib/{version.rb → appinsights/version.rb}

@@ -1,3 +1,3 @@
 module AppInsights
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appinsights
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Emiliano Mancuso
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-12 00:00:00.000000000 Z
+date: 2015-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: toml-rb
@@ -68,15 +68,15 @@ files:
 - README.md
 - appinsights.gemspec
 - lib/appinsights.rb
-- lib/config_loader.rb
-- lib/context.rb
-- lib/errors.rb
-- lib/installers/base.rb
-- lib/installers/rails.rb
-- lib/installers/sinatra.rb
-- lib/middlewares.rb
-- lib/middlewares/exception_handling.rb
-- lib/version.rb
+- lib/appinsights/config_loader.rb
+- lib/appinsights/context.rb
+- lib/appinsights/errors.rb
+- lib/appinsights/installers/base.rb
+- lib/appinsights/installers/rails.rb
+- lib/appinsights/installers/sinatra.rb
+- lib/appinsights/middlewares.rb
+- lib/appinsights/middlewares/exception_handling.rb
+- lib/appinsights/version.rb
 - rakefile
 - test/base_installer_test.rb
 - test/config_loader_test.rb

data/lib/installers/rails.rb

@@ -1,16 +0,0 @@
-module AppInsights
-  class RailsInstaller < Rails::Railtie
-    initializer 'appinsights.start_plugin' do |_app|
-      init Rails.root
-    end
-
-    def init(root, filename = nil)
-      installer = AppInsights::Base.new config.app_middleware,
-                                        root,
-                                        filename,
-                                        Rails.logger
-
-      installer.install
-    end
-  end
-end