API v3 and Logger integration.

README.md

@@ -3,15 +3,41 @@ Get your application events and errors to Trakerr via the *Trakerr API*.
 
 You will need your API key to send events to trakerr.
 
-## Overview
-- REST API version: 2.0.0
-- Package (SDK) version: 2.0.0
-
 ## Requirements.
+Ruby 1.9.3+, git 2.0+, and curl 7.47.0+
+
+
+## 3-minute Integration Guide
+First install [git and curl](#Install-git-and-curl). Once you have that complete, issue the command:
+
+```bash
+gem "trakerr_client", :git => "git://github.com/trakerr-io/trakerr-ruby.git"
+```
+or
+
+```bash
+gem install trakerr_client
+```
+
+Then import the packages:
+```ruby
+require_relative 'trakerr_logger.rb'
+```
+
+Finally, the integration. Trakerr uses a string stream to catch the output of a logger and send it to trakerr. Trakerr afterwards writes the code to the stream, so it's possible to write that data elsewhere as required from the stream.
+```ruby
+logger = Trakerr::TrakerrLogger.new(Logger.new(STDOUT))
+```
+Simply use the logger as normal afterwards:
+```ruby
+logger.fatal('oops')
 
-Ruby 1.9.3+
-and
-git 2.0+
+#If you pass an exception into the logger, the backtrace will become more specific.
+begin
+rescue StandardError => e
+    logger.fatal(e)
+end
+```
 
 ## Installation & Usage
 ### 1) Install git and curl
@@ -32,40 +58,35 @@ For Windows, or if you aren't using a package manager, visit https://git-scm.com
 If you are on Windows, you may also need to install curl and configure your ruby to use it. Trakerr uses typhous to actually send the exception to us. Follow the instructions on the curl website for more information and Typhous's project page to finish setup.
 
 ### 2) gem install
-
 Install [bundler](http://bundler.io/) and then you can issue this command to get the freshest version:
-```sh
+```bash
 gem "trakerr_client", :git => "git://github.com/trakerr-io/trakerr-ruby.git"
 ```
 
 You can also install from ruby gems:
-```sh
+```bash
 gem install trakerr_client
 ```
 for the latest stable release.
 
-Then import the package:
-```ruby
-require 'trakerr/lib/trakerr'
-```
-
 ## Detailed Integration Guide
-
 Please follow the [installation procedure](#installation--usage) and you're set to add Trakerr to your project. All of these examples are included in test_app.rb.
 
 If you would like to generate some quick sample events, you may download test_app.rb and run it from the command line like so:
-```sh
-ruby test_app.rb <<api-key>>
+```bash
+ruby test_app.rb <api key here>
 ```
 
 ### Package dependency
 Require the package:
-
 ```ruby
 require 'trakerr/lib/trakerr'
 ```
 
-### Option 1: Sending a default error to Trakerr
+### Option 1: Use the logger
+See [above](#3-minute-Integration-Guide) to learn how to integrate with the built in ruby logger.
+
+### Option 2: Sending a default error to Trakerr
 A trivial case would involve calling `log` for a caught exception.
 ```ruby
 def main()
@@ -75,17 +96,17 @@ def main()
     rescue ZeroDivisionError => exception
         #You can leave the hash empty if you would like to use the default values.
         #We recommend that you supply a user and a session for all events,
-        #and supplying an "evntname" and "evntmessage" for non errors.
+        #and supplying an "eventname" and "eventmessage" for non errors.
         testApp.log({"user"=>"jack@trakerr.io", "session"=>"7"}, exception) 
     end
 end
 ```
 
-Along with the `"user"` and `"session"`; the hash can also take `"evntname"` and `"evntmessage"`. Note that these two will be filled in automatically for errors you rescue if you do not provide them, so we suggest giving them for non-errors.
+Along with the `"user"` and `"session"`; the hash can also take `"eventname"` and `"eventmessage"`. Note that these two will be filled in automatically for errors you rescue if you do not provide them, so we suggest giving them for non-errors.
 
 `log` may also take in a log_level and a classification (We recommend you providing this **especially** if you send a warning or below), but will otherwise default all of the AppEvent properties.
 
-### Option 2: Sending an error to Trakerr with Custom Data
+### Option 3: Sending an error to Trakerr with Custom Data
 If you want to populate the `AppEvent` fully with custom properties (log only accepts the minimum set of useful custom properties to utilize Trakerr's rich feature set), you can manually create an `AppEvent` and populate it's fields. Pass it to the `SendEvent` to then send the AppEvent to Trakerr. See the `AppEvent` API for more information on it's properties.
 
 ```ruby
@@ -103,7 +124,7 @@ def main()
 end
 ```
 
-### Option 3: Send a non-exception to Trakerr
+### Option 4: Send a non-exception to Trakerr
 Trakerr accepts events that aren't errors. To do so, pass false to the CreateAppEvent Exception field to not attach a stacktrace to the event (if you don't need it). Be sure to pass values in to the rest of the parameters since the default values will most likely not be useful for you if you don't have a stacktrace!
 ```ruby
 def main()
@@ -147,7 +168,6 @@ Name | Type | Description | Notes
 **contextDataCenterRegion** | **string** | Data center region. | Defaults to `nil`
 
 ## Documentation For Models
-
  - [AppEvent](https://github.com/trakerr-io/trakerr-python/blob/master/generated/docs/AppEvent.md)
 
 ## Author

generated/README.md

@@ -8,7 +8,7 @@ This SDK is automatically generated by the [Swagger Codegen](https://github.com/
 
 - API version: 1.0.0
 - Package version: 1.0.0
-- Build date: 2017-03-13T17:18:49.200-07:00
+- Build date: 2017-05-05T15:16:47.647-07:00
 - Build package: class io.swagger.codegen.languages.RubyClientCodegen
 
 ## Installation

generated/docs/AppEvent.md

@@ -5,7 +5,7 @@ Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **api_key** | **String** | API key generated for the application | 
 **log_level** | **String** | (optional) Logging level, one of 'debug','info','warning','error', 'fatal', defaults to 'error' | [optional] 
-**classification** | **String** | (optional) one of 'error' or a custom string for non-errors, defaults to 'error' | 
+**classification** | **String** | (optional) one of 'issue' or a custom string for non-issues, defaults to 'issue' | 
 **event_type** | **String** | type of the event or error (eg. NullPointerException) | 
 **event_message** | **String** | message containing details of the event or error | 
 **event_time** | **Integer** | (optional) event time in ms since epoch | [optional] 
@@ -24,6 +24,14 @@ Name | Type | Description | Notes
 **context_app_os_version** | **String** | (optional) OS version the application is running on | [optional] 
 **context_data_center** | **String** | (optional) Data center the application is running on or connected to | [optional] 
 **context_data_center_region** | **String** | (optional) Data center region | [optional] 
+**context_tags** | **Array<String>** |  | [optional] 
+**context_url** | **String** | (optional) The full URL when running in a browser when the event was generated. | [optional] 
+**context_operation_time_millis** | **Integer** | (optional) duration that this event took to occur in millis. Example - database call time in millis. | [optional] 
+**context_cpu_percentage** | **Integer** | (optional) CPU utilization as a percent when event occured | [optional] 
+**context_memory_percentage** | **Integer** | (optional) Memory utilization as a percent when event occured | [optional] 
+**context_cross_app_correlation_id** | **String** | (optional) Cross application correlation ID | [optional] 
+**context_device** | **String** | (optional) Device information | [optional] 
+**context_app_sku** | **String** | (optional) Application SKU | [optional] 
 **custom_properties** | [**CustomData**](CustomData.md) |  | [optional] 
 **custom_segments** | [**CustomData**](CustomData.md) |  | [optional] 
 

generated/lib/trakerr_client/models/app_event.rb

@@ -1,7 +1,7 @@
 =begin
-Trakerr API
+#Trakerr API
 
-Get your application events and errors to Trakerr via the *Trakerr API*.
+#Get your application events and errors to Trakerr via the *Trakerr API*.
 
 OpenAPI spec version: 1.0.0
 
@@ -32,7 +32,7 @@ class AppEvent
     # (optional) Logging level, one of 'debug','info','warning','error', 'fatal', defaults to 'error'
     attr_accessor :log_level
 
-    # (optional) one of 'error' or a custom string for non-errors, defaults to 'error'
+    # (optional) one of 'issue' or a custom string for non-issues, defaults to 'issue'
     attr_accessor :classification
 
     # type of the event or error (eg. NullPointerException)
@@ -88,6 +88,29 @@ class AppEvent
     # (optional) Data center region
     attr_accessor :context_data_center_region
 
+    attr_accessor :context_tags
+
+    # (optional) The full URL when running in a browser when the event was generated.
+    attr_accessor :context_url
+
+    # (optional) duration that this event took to occur in millis. Example - database call time in millis.
+    attr_accessor :context_operation_time_millis
+
+    # (optional) CPU utilization as a percent when event occured
+    attr_accessor :context_cpu_percentage
+
+    # (optional) Memory utilization as a percent when event occured
+    attr_accessor :context_memory_percentage
+
+    # (optional) Cross application correlation ID
+    attr_accessor :context_cross_app_correlation_id
+
+    # (optional) Device information
+    attr_accessor :context_device
+
+    # (optional) Application SKU
+    attr_accessor :context_app_sku
+
     attr_accessor :custom_properties
 
     attr_accessor :custom_segments
@@ -138,6 +161,14 @@ def self.attribute_map
         :'context_app_os_version' => :'contextAppOSVersion',
         :'context_data_center' => :'contextDataCenter',
         :'context_data_center_region' => :'contextDataCenterRegion',
+        :'context_tags' => :'contextTags',
+        :'context_url' => :'contextURL',
+        :'context_operation_time_millis' => :'contextOperationTimeMillis',
+        :'context_cpu_percentage' => :'contextCpuPercentage',
+        :'context_memory_percentage' => :'contextMemoryPercentage',
+        :'context_cross_app_correlation_id' => :'contextCrossAppCorrelationId',
+        :'context_device' => :'contextDevice',
+        :'context_app_sku' => :'contextAppSku',
         :'custom_properties' => :'customProperties',
         :'custom_segments' => :'customSegments'
       }
@@ -167,6 +198,14 @@ def self.swagger_types
         :'context_app_os_version' => :'String',
         :'context_data_center' => :'String',
         :'context_data_center_region' => :'String',
+        :'context_tags' => :'Array<String>',
+        :'context_url' => :'String',
+        :'context_operation_time_millis' => :'Integer',
+        :'context_cpu_percentage' => :'Integer',
+        :'context_memory_percentage' => :'Integer',
+        :'context_cross_app_correlation_id' => :'String',
+        :'context_device' => :'String',
+        :'context_app_sku' => :'String',
         :'custom_properties' => :'CustomData',
         :'custom_segments' => :'CustomData'
       }
@@ -264,6 +303,40 @@ def initialize(attributes = {})
         self.context_data_center_region = attributes[:'contextDataCenterRegion']
       end
 
+      if attributes.has_key?(:'contextTags')
+        if (value = attributes[:'contextTags']).is_a?(Array)
+          self.context_tags = value
+        end
+      end
+
+      if attributes.has_key?(:'contextURL')
+        self.context_url = attributes[:'contextURL']
+      end
+
+      if attributes.has_key?(:'contextOperationTimeMillis')
+        self.context_operation_time_millis = attributes[:'contextOperationTimeMillis']
+      end
+
+      if attributes.has_key?(:'contextCpuPercentage')
+        self.context_cpu_percentage = attributes[:'contextCpuPercentage']
+      end
+
+      if attributes.has_key?(:'contextMemoryPercentage')
+        self.context_memory_percentage = attributes[:'contextMemoryPercentage']
+      end
+
+      if attributes.has_key?(:'contextCrossAppCorrelationId')
+        self.context_cross_app_correlation_id = attributes[:'contextCrossAppCorrelationId']
+      end
+
+      if attributes.has_key?(:'contextDevice')
+        self.context_device = attributes[:'contextDevice']
+      end
+
+      if attributes.has_key?(:'contextAppSku')
+        self.context_app_sku = attributes[:'contextAppSku']
+      end
+
       if attributes.has_key?(:'customProperties')
         self.custom_properties = attributes[:'customProperties']
       end
@@ -329,6 +402,14 @@ def ==(o)
           context_app_os_version == o.context_app_os_version &&
           context_data_center == o.context_data_center &&
           context_data_center_region == o.context_data_center_region &&
+          context_tags == o.context_tags &&
+          context_url == o.context_url &&
+          context_operation_time_millis == o.context_operation_time_millis &&
+          context_cpu_percentage == o.context_cpu_percentage &&
+          context_memory_percentage == o.context_memory_percentage &&
+          context_cross_app_correlation_id == o.context_cross_app_correlation_id &&
+          context_device == o.context_device &&
+          context_app_sku == o.context_app_sku &&
           custom_properties == o.custom_properties &&
           custom_segments == o.custom_segments
     end
@@ -342,7 +423,7 @@ def eql?(o)
     # Calculates hash code according to all attributes.
     # @return [Fixnum] Hash code
     def hash
-      [api_key, log_level, classification, event_type, event_message, event_time, event_stacktrace, event_user, event_session, context_app_version, deployment_stage, context_env_name, context_env_language, context_env_version, context_env_hostname, context_app_browser, context_app_browser_version, context_app_os, context_app_os_version, context_data_center, context_data_center_region, custom_properties, custom_segments].hash
+      [api_key, log_level, classification, event_type, event_message, event_time, event_stacktrace, event_user, event_session, context_app_version, deployment_stage, context_env_name, context_env_language, context_env_version, context_env_hostname, context_app_browser, context_app_browser_version, context_app_os, context_app_os_version, context_data_center, context_data_center_region, context_tags, context_url, context_operation_time_millis, context_cpu_percentage, context_memory_percentage, context_cross_app_correlation_id, context_device, context_app_sku, custom_properties, custom_segments].hash
     end
 
     # Builds the object from hash

test_app.rb

@@ -17,7 +17,10 @@
 =end
 
 require 'rubygems'
+require 'logger'
 require_relative 'trakerr/lib/trakerr'
+require_relative 'trakerr/lib/trakerr_formatter'
+require_relative 'trakerr/lib/trakerr_writer'
 
 def main()
     argarr = ARGV
@@ -26,39 +29,61 @@ def main()
     api_key = argarr[0] if argarr.length > 0 and api_key == "<Your API key here>"
 
     testApp = Trakerr::TrakerrClient.new(api_key, "1.0", "development")
+    stream = Trakerr::TrakerrWriter.new(api_key, "2.0", "development")
+
+    rlog = Logger.new(stream)
+    #rlog = Logger.new($stdout)
+    rlog.formatter = Trakerr::TrakerrFormatter.new
+
+    begin
+        raise IOError, "Failed to open file"
+    rescue IOError => err
+        rlog.fatal err
+    end
+
+    #Since we use streams (StringIO) to hook into the ruby logger,
+    #accessing stream after it has finished logging and event is simple.
+    #Rewind the stream, and then read it to extract data to whatever device you wish for.
+    #The example in the comments below prints out to console. The formatter does change how the event is formatted
+    #and the information given as the output to be pertinant and easy to parse by the stream hook, but I could probably write a complex regex for default
+    #if the demand is there.
+    #stream.rewind
+    #log = stream.read
+    #puts log
 
     #Send exception to Trakerr with default values.
     begin
         raise ZeroDivisionError, "Oh no!"
-    rescue ZeroDivisionError => exception
+    rescue ZeroDivisionError => er
         #You can leave the hash empty if you would like to use the default values.
         #We recommend that you supply a user and a session for all events,
         #and supplying an "evntname" and "evntmessage" for non errors.
-        testApp.log({"user"=>"jack@trakerr.io", "session"=>"7"}, exception) 
+        testApp.log({"user"=>"jack@trakerr.io", "session"=>"7"}, er) 
     end
 
     #Get an AppEvent to populate the class with custom data and then send it to Trakerr.
     #Simple custom data can be send through log.
     begin
-        raise ArgumentError
-    rescue ArgumentError => e
-        appev = testApp.CreateAppEvent(e, "Error")
+        raise RegexpError, "Help!"
+    rescue RegexpError => e
+        appev = testApp.create_app_event(e, "Error")
         appev.event_user = "john@trakerr.io"
         appev.event_session = "5"
         appev.context_app_browser = "Chrome"
         appev.context_app_browser_version = "57.x"
 
-        testApp.SendEvent(appev)
+        testApp.send_event(appev)
     end
 
     #Send a non Exception to Trakerr.
-    appev2 = testApp.CreateAppEvent(false, "Info", "User failed auth", "400 err", "User error")
+    appev2 = testApp.create_app_event(false, "Info", "User failed auth", "400 err", "User error")
     appev2.event_user = "jill@trakerr.io"
     appev2.event_session = "3"
     appev2.context_app_browser = "Edge"
     appev2.context_app_browser_version = "40.15063.0.0"
+    appev2.context_operation_time_millis = 5000
 
-    testApp.SendEvent(appev2)
+    testApp.send_event(appev2)
 
 end