feat(sessions): Implement automatic session tracking (#1715)

* SessionFlusher spawning new thread with 60s periodic flush

* Hub start_session/end_session api, add session object to scope

* Start implementing Session class WIP

* Expose session_flusher on top level

* Test commit

* Test commit

* Test commit

* auto_session_tracking config (default true); with_session_tracking hub
method

* Wrap rack middleware in with_session_tracking

* Simplify session class/remove mode switches since only doing aggregates
for now

* Fix missing require, end_session in ensure

* Simplify session updates on exception

* Simpler hub logic

* Record aggregates

* Envelope abstraction for sessions (WEBBACKEND-85)

* Move session update in capture_event to hub due to scope dup

* Need to make envelope outside background worker

* Remove useless require

* Specs for SessionFlusher

* Rake middleware sessions specs

* Remove rate-limit change because will do it separately

* Some docs + cleanup

* ref(envelopes): Add send_envelope and move rate limiting filtering to items level

* Git can't merge

* Add session category to rate limits

* Wrong item_type..

* Add session to #is_rate_limited? spec

* Move session update from capture_event to capture_exception

* Code style

* Add spec for only one thread

* Remove aggregates_payload

* Rewrite #flush test

* Partial changelog

* Wrong changelog..

* Add screenshot

* Changelog fix

Author: sl0thentr0py

CHANGELOG.md

@@ -5,6 +5,26 @@
 - Log Redis command arguments when sending PII is enabled [#1726](https://github.com/getsentry/sentry-ruby/pull/1726)
 - Add request env to sampling context [#1749](https://github.com/getsentry/sentry-ruby/pull/1749)
 
+- Automatic session tracking [#1715](https://github.com/getsentry/sentry-ruby/pull/1715)
+
+  **Example**:
+  
+  ![image](https://user-images.githubusercontent.com/6536764/157057827-2893527e-7973-4901-a070-bd78a720574a.png)
+
+
+  The SDK now supports [automatic session tracking / release health](https://docs.sentry.io/product/releases/health/) by default in Rack based applications.  
+  Aggregate statistics on successful / errored requests are collected and sent to the server every minute.  
+  To use this feature, make sure the SDK can detect your app's release. Or you have set it with:
+
+  ```ruby
+  Sentry.init do |config|
+    config.release = 'release-foo-v1'
+  end
+  ```
+
+  To disable this feature, set `config.auto_session_tracking` to `false`.
+
+
 ### Bug Fixes
 
 - Require set library [#1753](https://github.com/getsentry/sentry-ruby/pull/1753)

sentry-ruby/lib/sentry-ruby.rb

@@ -17,6 +17,7 @@
 require "sentry/transaction"
 require "sentry/hub"
 require "sentry/background_worker"
+require "sentry/session_flusher"
 
 [
   "sentry/rake",
@@ -61,6 +62,10 @@ def exception_locals_tp
     #   @return [BackgroundWorker]
     attr_accessor :background_worker
 
+    # @!attribute [r] session_flusher
+    #   @return [SessionFlusher]
+    attr_reader :session_flusher
+
     ##### Patch Registration #####
 
     # @!visibility private
@@ -189,11 +194,18 @@ def init(&block)
       @main_hub = hub
       @background_worker = Sentry::BackgroundWorker.new(config)
 
+      @session_flusher = if config.auto_session_tracking
+                           Sentry::SessionFlusher.new(config, client)
+                         else
+                           nil
+                         end
+
       if config.capture_exception_frame_locals
         exception_locals_tp.enable
       end
 
       at_exit do
+        @session_flusher&.kill
         @background_worker.shutdown
       end
     end
@@ -310,6 +322,26 @@ def with_scope(&block)
       get_current_hub.with_scope(&block)
     end
 
+    # Wrap a given block with session tracking.
+    # Aggregate sessions in minutely buckets will be recorded
+    # around this block and flushed every minute.
+    #
+    # @example
+    #   Sentry.with_session_tracking do
+    #     a = 1 + 1 # new session recorded with :exited status
+    #   end
+    #
+    #   Sentry.with_session_tracking do
+    #     1 / 0
+    #   rescue => e
+    #     Sentry.capture_exception(e) # new session recorded with :errored status
+    #   end
+    # @return [void]
+    def with_session_tracking(&block)
+      return yield unless initialized?
+      get_current_hub.with_session_tracking(&block)
+    end
+
     # Takes an exception and reports it to Sentry via the currently active hub.
     #
     # @yieldparam scope [Scope]

sentry-ruby/lib/sentry/configuration.rb

@@ -207,6 +207,10 @@ class Configuration
     # @return [Boolean]
     attr_accessor :send_client_reports
 
+    # Track sessions in request/response cycles automatically
+    # @return [Boolean]
+    attr_accessor :auto_session_tracking
+
     # these are not config options
     # @!visibility private
     attr_reader :errors, :gem_specs
@@ -261,6 +265,7 @@ def initialize
       self.send_default_pii = false
       self.skip_rake_integration = false
       self.send_client_reports = true
+      self.auto_session_tracking = true
       self.trusted_proxies = []
       self.dsn = ENV['SENTRY_DSN']
       self.server_name = server_name_from_env

sentry-ruby/lib/sentry/hub.rb

@@ -2,6 +2,7 @@
 
 require "sentry/scope"
 require "sentry/client"
+require "sentry/session"
 
 module Sentry
   class Hub
@@ -104,6 +105,8 @@ def capture_exception(exception, **options, &block)
 
       return unless event
 
+      current_scope.session&.update_from_exception(event.exception)
+
       capture_event(event, **options, &block).tap do
         # mark the exception as captured so we can use this information to avoid duplicated capturing
         exception.instance_variable_set(Sentry::CAPTURED_SIGNATURE, true)
@@ -143,7 +146,6 @@ def capture_event(event, **options, &block)
 
       event = current_client.capture_event(event, scope, hint)
 
-
       if event && configuration.debug
         configuration.log_debug(event.to_json_compatible)
       end
@@ -175,6 +177,30 @@ def with_background_worker_disabled(&block)
       configuration.background_worker_threads = original_background_worker_threads
     end
 
+    def start_session
+      return unless current_scope
+      current_scope.set_session(Session.new)
+    end
+
+    def end_session
+      return unless current_scope
+      session = current_scope.session
+      current_scope.set_session(nil)
+
+      return unless session
+      session.close
+      Sentry.session_flusher.add_session(session)
+    end
+
+    def with_session_tracking(&block)
+      return yield unless configuration.auto_session_tracking
+
+      start_session
+      yield
+    ensure
+      end_session
+    end
+
     private
 
     def current_layer

sentry-ruby/lib/sentry/rack/capture_exceptions.rb

@@ -14,30 +14,32 @@ def call(env)
         Sentry.clone_hub_to_current_thread
 
         Sentry.with_scope do |scope|
-          scope.clear_breadcrumbs
-          scope.set_transaction_name(env["PATH_INFO"]) if env["PATH_INFO"]
-          scope.set_rack_env(env)
-
-          transaction = start_transaction(env, scope)
-          scope.set_span(transaction) if transaction
-
-          begin
-            response = @app.call(env)
-          rescue Sentry::Error
-            finish_transaction(transaction, 500)
-            raise # Don't capture Sentry errors
-          rescue Exception => e
-            capture_exception(e)
-            finish_transaction(transaction, 500)
-            raise
+          Sentry.with_session_tracking do
+            scope.clear_breadcrumbs
+            scope.set_transaction_name(env["PATH_INFO"]) if env["PATH_INFO"]
+            scope.set_rack_env(env)
+
+            transaction = start_transaction(env, scope)
+            scope.set_span(transaction) if transaction
+
+            begin
+              response = @app.call(env)
+            rescue Sentry::Error
+              finish_transaction(transaction, 500)
+              raise # Don't capture Sentry errors
+            rescue Exception => e
+              capture_exception(e)
+              finish_transaction(transaction, 500)
+              raise
+            end
+
+            exception = collect_exception(env)
+            capture_exception(exception) if exception
+
+            finish_transaction(transaction, response[0])
+
+            response
           end
-
-          exception = collect_exception(env)
-          capture_exception(exception) if exception
-
-          finish_transaction(transaction, response[0])
-
-          response
         end
       end
 

sentry-ruby/lib/sentry/scope.rb

@@ -7,7 +7,7 @@ module Sentry
   class Scope
     include ArgumentCheckingHelper
 
-    ATTRIBUTES = [:transaction_names, :contexts, :extra, :tags, :user, :level, :breadcrumbs, :fingerprint, :event_processors, :rack_env, :span]
+    ATTRIBUTES = [:transaction_names, :contexts, :extra, :tags, :user, :level, :breadcrumbs, :fingerprint, :event_processors, :rack_env, :span, :session]
 
     attr_reader(*ATTRIBUTES)
 
@@ -76,6 +76,7 @@ def dup
       copy.transaction_names = transaction_names.deep_dup
       copy.fingerprint = fingerprint.deep_dup
       copy.span = span.deep_dup
+      copy.session = session.deep_dup
       copy
     end
 
@@ -198,6 +199,13 @@ def set_transaction_name(transaction_name)
       @transaction_names << transaction_name
     end
 
+    # Sets the currently active session on the scope.
+    # @param session [Session, nil]
+    # @return [void]
+    def set_session(session)
+      @session = session
+    end
+
     # Returns current transaction name.
     # The "transaction" here does not refer to `Transaction` objects.
     # @return [String, nil]
@@ -251,6 +259,7 @@ def set_default_value
       @event_processors = []
       @rack_env = {}
       @span = nil
+      @session = nil
       set_new_breadcrumb_buffer
     end
 

sentry-ruby/lib/sentry/session.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Sentry
+  class Session
+    attr_reader :started, :status
+
+    # TODO-neel add :crashed after adding handled mechanism
+    STATUSES = %i(ok errored exited)
+    AGGREGATE_STATUSES = %i(errored exited)
+
+    def initialize
+      @started = Sentry.utc_now
+      @status = :ok
+    end
+
+    # TODO-neel add :crashed after adding handled mechanism
+    def update_from_exception(_exception = nil)
+      @status = :errored
+    end
+
+    def close
+      @status = :exited if @status == :ok
+    end
+
+    # truncate seconds from the timestamp since we only care about
+    # minute level granularity for aggregation
+    def aggregation_key
+      Time.utc(started.year, started.month, started.day, started.hour, started.min)
+    end
+
+    def deep_dup
+      dup
+    end
+  end
+end

sentry-ruby/lib/sentry/session_flusher.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Sentry
+  class SessionFlusher
+    include LoggingHelper
+
+    FLUSH_INTERVAL = 60
+
+    def initialize(configuration, client)
+      @thread = nil
+      @client = client
+      @pending_aggregates = {}
+      @release = configuration.release
+      @environment = configuration.environment
+      @logger = configuration.logger
+
+      log_debug("[Sessions] Sessions won't be captured without a valid release") unless @release
+    end
+
+    def flush
+      return if @pending_aggregates.empty?
+      envelope = pending_envelope
+
+      Sentry.background_worker.perform do
+        @client.transport.send_envelope(envelope)
+      end
+
+      @pending_aggregates = {}
+    end
+
+    def add_session(session)
+      return unless @release
+
+      ensure_thread
+
+      return unless Session::AGGREGATE_STATUSES.include?(session.status)
+      @pending_aggregates[session.aggregation_key] ||= init_aggregates(session.aggregation_key)
+      @pending_aggregates[session.aggregation_key][session.status] += 1
+    end
+
+    def kill
+      @thread&.kill
+    end
+
+    private
+
+    def init_aggregates(aggregation_key)
+      aggregates = { started: aggregation_key.iso8601 }
+      Session::AGGREGATE_STATUSES.each { |k| aggregates[k] = 0 }
+      aggregates
+    end
+
+    def pending_envelope
+      envelope = Envelope.new
+
+      header = { type: 'sessions' }
+      payload = { attrs: attrs, aggregates: @pending_aggregates.values }
+
+      envelope.add_item(header, payload)
+      envelope
+    end
+
+    def attrs
+      { release: @release, environment: @environment }
+    end
+
+    def ensure_thread
+      return if @thread&.alive?
+
+      @thread = Thread.new do
+        loop do
+          sleep(FLUSH_INTERVAL)
+          flush
+        end
+      end
+    end
+
+  end
+end

sentry-ruby/lib/sentry/transport.rb

@@ -67,6 +67,8 @@ def is_rate_limited?(item_type)
         case item_type
         when "transaction"
           @rate_limits["transaction"]
+        when "sessions"
+          @rate_limits["session"]
         else
           @rate_limits["error"]
         end
@@ -125,7 +127,6 @@ def envelope_from_event(event)
       client_report_headers, client_report_payload = fetch_pending_client_report
       envelope.add_item(client_report_headers, client_report_payload) if client_report_headers
 
-
       envelope
     end