tg_error_notifier 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 785aa28f5a62476e0f827430090ff0dad300edd8277b54672b88f3b89a7ee730
-  data.tar.gz: 680dea5d7f8440e07b41e5df415483e35a0aed5b8adbf0b5f9169302c1306422
+  metadata.gz: eb51823201c7e9fef5a9a3d3f1ddb9ca52390d75cf256c1488f3b3f72ebc6d2b
+  data.tar.gz: d778ac6a5c07212e617729878ad8dc9d05d338377d9788f57a44577b9d739804
 SHA512:
-  metadata.gz: 001f1b8fb2fb679ea77acb1d1761f6fe67f3736b08be8be1fa5c9541e45818b137a37b9c39ea4ce7d59ede8cc654bdd9689be76959a4364253add6fccb4b0535
-  data.tar.gz: 58ccd0356a6699a0fafff07bd90d461a8a3654db0d00813faa5a3fc7b826593f737924756127fa809d7bf1be65eb1420460b7731cb9cf46349d19160f10291cc
+  metadata.gz: c943e6433257b3d68fb0d4630156e3073084dfa82d90ef51c38d5db4b518f840abd2e211d0aacf893ed8734d70e893cb8872969ffbe284324893b54946882610
+  data.tar.gz: 3f05a5989f3d5731eef6114b2e8acb3247ea97af1ee43d7ccc98d163f6496b5f22c55b6fed9fac1e31c5c3431dfe82919bb42c715f342c3b610552a4f6ed7849

data/README.md

@@ -70,6 +70,42 @@ Examples:
 - Ensure bot has permission to send messages.
 - Put value into `TELEGRAM_ERRORS_CHAT_ID` and run a smoke test.
 
+## Error grouping
+
+Group identical errors to avoid flooding. When the same exception repeats within a time window, only the first message is sent — subsequent occurrences are suppressed and reported as a count in the next message.
+
+```ruby
+TgErrorNotifier.configure do |config|
+  config.grouping_enabled = true
+  config.grouping_window = 60 # seconds (default)
+end
+```
+
+Errors are grouped by exception class + normalized message (IDs and UUIDs are replaced with placeholders for better deduplication).
+
+## Forum topics (threads)
+
+Automatically create a Telegram Forum topic (thread) per unique error type. Each error gets its own topic in a supergroup with Forum Topics enabled.
+
+```ruby
+TgErrorNotifier.configure do |config|
+  config.topics_enabled = true
+  config.topic_icon_color = 0xFB6F5F # red (default), optional
+end
+```
+
+**Requirements:** The chat must be a supergroup with Forum Topics enabled. The bot must have `can_manage_topics` admin permission.
+
+You can combine both features — errors will be grouped within their respective topics:
+
+```ruby
+TgErrorNotifier.configure do |config|
+  config.grouping_enabled = true
+  config.grouping_window = 60
+  config.topics_enabled = true
+end
+```
+
 ## Manual notification
 ```ruby
 begin

data/lib/tg_error_notifier/configuration.rb

@@ -19,7 +19,11 @@ module TgErrorNotifier
       :proxy_addr,
       :proxy_port,
       :proxy_user,
-      :proxy_pass
+      :proxy_pass,
+      :grouping_enabled,
+      :grouping_window,
+      :topics_enabled,
+      :topic_icon_color
 
     def initialize
       @enabled = true
@@ -44,6 +48,10 @@ module TgErrorNotifier
       @proxy_port = nil
       @proxy_user = nil
       @proxy_pass = nil
+      @grouping_enabled = false
+      @grouping_window = 60
+      @topics_enabled = false
+      @topic_icon_color = nil
     end
 
     def proxy?

data/lib/tg_error_notifier/grouper.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module TgErrorNotifier
+  class Grouper
+    Entry = Struct.new(:count, :first_at, :last_sent_at, :thread_id, keyword_init: true)
+
+    CLEANUP_INTERVAL = 100
+
+    def initialize(window:)
+      @window = window
+      @mutex = Mutex.new
+      @entries = {}
+      @call_count = 0
+    end
+
+    # Returns:
+    #   { action: :send, count: N, thread_id: id_or_nil }
+    #   { action: :suppress }
+    def process(key:, thread_id: nil)
+      now = Time.now
+
+      @mutex.synchronize do
+        @call_count += 1
+        lazy_cleanup!(now) if (@call_count % CLEANUP_INTERVAL).zero?
+
+        entry = @entries[key]
+
+        if entry.nil?
+          @entries[key] = Entry.new(count: 0, first_at: now, last_sent_at: now, thread_id: thread_id)
+          return { action: :send, count: 0, thread_id: thread_id }
+        end
+
+        entry.thread_id = thread_id if entry.thread_id.nil? && thread_id
+
+        elapsed = now - entry.last_sent_at
+
+        if elapsed >= @window
+          accumulated = entry.count
+          entry.count = 0
+          entry.last_sent_at = now
+          { action: :send, count: accumulated, thread_id: entry.thread_id }
+        else
+          entry.count += 1
+          { action: :suppress }
+        end
+      end
+    end
+
+    def grouping_key(exception)
+      "#{exception.class.name}:#{normalize_message(exception.message)}"
+    end
+
+    private
+
+    def normalize_message(message)
+      msg = message.to_s
+      msg = msg.gsub(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i, "<UUID>")
+      msg = msg.gsub(/\b\d{4,}\b/, "<ID>")
+      msg = msg.gsub(/#<\w+:0x[0-9a-f]+>/i, "#<Object>")
+      msg.strip
+    end
+
+    def lazy_cleanup!(now)
+      cutoff = now - 3600
+      @entries.delete_if { |_, e| e.last_sent_at < cutoff }
+    end
+  end
+end

data/lib/tg_error_notifier/notifier.rb

@@ -23,21 +23,54 @@ module TgErrorNotifier
         return { sent: false, status: :skipped, reason: "ignored_exception" }
       end
 
-      payload = build_payload(exception: exception, source: source, context: context)
+      key = nil
+      thread_id = nil
+      suppressed_count = 0
+
+      if config.topics_enabled || config.grouping_enabled
+        key = grouper.grouping_key(exception)
+      end
+
+      if config.topics_enabled
+        thread_id = topic_manager.thread_id_for(key, exception)
+      end
+
+      if config.grouping_enabled
+        result = grouper.process(key: key, thread_id: thread_id)
+        if result[:action] == :suppress
+          return { sent: false, status: :suppressed }
+        end
+        suppressed_count = result[:count]
+        thread_id = result[:thread_id] || thread_id
+      end
+
+      payload = build_payload(
+        exception: exception,
+        source: source,
+        context: context,
+        thread_id: thread_id,
+        suppressed_count: suppressed_count
+      )
       send_payload(payload)
     rescue StandardError => e
       log("notify failed: #{e.class}: #{e.message}")
       { sent: false, status: :failed, reason: e.class.name, error: e.message }
     end
 
-    def notify_message(message:, level:, source:, context: {})
+    def notify_message(message:, level:, source:, context: {}, thread_id: nil)
       enabled_check = enabled_status
       unless enabled_check[:enabled]
         log("skipped: #{enabled_check[:reason]}")
         return { sent: false, status: :skipped, reason: enabled_check[:reason] }
       end
 
-      payload = build_message_payload(message: message, level: level, source: source, context: context)
+      payload = build_message_payload(
+        message: message,
+        level: level,
+        source: source,
+        context: context,
+        thread_id: thread_id
+      )
       send_payload(payload)
     rescue StandardError => e
       log("notify_message failed: #{e.class}: #{e.message}")
@@ -48,6 +81,14 @@ module TgErrorNotifier
 
     attr_reader :config
 
+    def grouper
+      @grouper ||= Grouper.new(window: config.grouping_window)
+    end
+
+    def topic_manager
+      @topic_manager ||= TopicManager.new(config)
+    end
+
     def enabled_status
       return { enabled: false, reason: "disabled" } unless resolve(config.enabled)
       if config.ignored_environments.include?(resolve(config.environment).to_s)
@@ -93,14 +134,21 @@ module TgErrorNotifier
       { sent: false, status: :failed, reason: "telegram_api_error", code: response.code.to_i, body: response.body.to_s }
     end
 
-    def build_payload(exception:, source:, context: {})
-      text = [
+    def build_payload(exception:, source:, context: {}, thread_id: nil, suppressed_count: 0)
+      parts = [
         "<b>🚨 #{escape(resolve(config.app_name).to_s)}: #{escape(resolve(config.environment).to_s)}</b>",
         "<b>Source:</b> #{escape(source.to_s)}",
         "<b>Exception:</b> <code>#{escape(exception.class.name)}</code>",
-        "<b>Message:</b> #{escape(exception.message.to_s)}",
-        context_block(context)
-      ].compact.join("\n")
+        "<b>Message:</b> #{escape(exception.message.to_s)}"
+      ]
+
+      if suppressed_count > 0
+        parts << "<b>🔁 +#{suppressed_count} more in last #{config.grouping_window}s</b>"
+      end
+
+      parts << context_block(context)
+
+      text = parts.compact.join("\n")
 
       if config.include_backtrace && exception.backtrace
         lines = exception.backtrace.first(config.max_backtrace_lines)
@@ -108,12 +156,14 @@ module TgErrorNotifier
         text = "#{text}\n<b>Backtrace:</b>\n<pre>#{bt}</pre>"
       end
 
-      {
+      payload = {
         chat_id: resolve(config.chat_id),
         text: truncate(text),
         parse_mode: "HTML",
         disable_web_page_preview: true
       }
+      payload[:message_thread_id] = thread_id if thread_id
+      payload
     end
 
     def context_block(context)
@@ -123,7 +173,7 @@ module TgErrorNotifier
       formatted.join("\n")
     end
 
-    def build_message_payload(message:, level:, source:, context: {})
+    def build_message_payload(message:, level:, source:, context: {}, thread_id: nil)
       text = [
         "<b>ℹ️ #{escape(resolve(config.app_name).to_s)}: #{escape(resolve(config.environment).to_s)}</b>",
         "<b>Source:</b> #{escape(source.to_s)}",
@@ -132,12 +182,14 @@ module TgErrorNotifier
         context_block(context)
       ].compact.join("\n")
 
-      {
+      payload = {
         chat_id: resolve(config.chat_id),
         text: truncate(text),
         parse_mode: "HTML",
         disable_web_page_preview: true
       }
+      payload[:message_thread_id] = thread_id if thread_id
+      payload
     end
 
     def truncate(text)

data/lib/tg_error_notifier/railtie.rb

@@ -22,6 +22,10 @@ module TgErrorNotifier
         config.logger = options.logger unless options.logger.nil?
         config.include_backtrace = options.include_backtrace unless options.include_backtrace.nil?
         config.active_job_enabled = options.active_job_enabled unless options.active_job_enabled.nil?
+        config.grouping_enabled = options.grouping_enabled unless options.grouping_enabled.nil?
+        config.grouping_window = options.grouping_window unless options.grouping_window.nil?
+        config.topics_enabled = options.topics_enabled unless options.topics_enabled.nil?
+        config.topic_icon_color = options.topic_icon_color unless options.topic_icon_color.nil?
       end
     end
 

data/lib/tg_error_notifier/topic_manager.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module TgErrorNotifier
+  class TopicManager
+    ICON_COLOR_RED = 0xFB6F5F
+    MAX_TOPIC_NAME = 128
+
+    def initialize(config)
+      @config = config
+      @mutex = Mutex.new
+      @topics = {} # grouping_key => message_thread_id
+    end
+
+    def thread_id_for(key, exception)
+      @mutex.synchronize do
+        return @topics[key] if @topics.key?(key)
+      end
+
+      thread_id = create_topic(topic_name(exception))
+
+      if thread_id
+        @mutex.synchronize { @topics[key] = thread_id }
+      end
+
+      thread_id
+    end
+
+    private
+
+    def topic_name(exception)
+      name = "#{exception.class.name}: #{exception.message}"
+      name = name.gsub(/\s+/, " ").strip
+      name.length > MAX_TOPIC_NAME ? "#{name[0...MAX_TOPIC_NAME - 1]}…" : name
+    end
+
+    def create_topic(name)
+      token = resolve(@config.bot_token)
+      chat_id = resolve(@config.chat_id)
+      uri = URI("#{resolve(@config.api_base)}/bot#{token}/createForumTopic")
+
+      payload = {
+        chat_id: chat_id,
+        name: name,
+        icon_color: @config.topic_icon_color || ICON_COLOR_RED
+      }
+
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request.body = payload.to_json
+
+      http = build_http(uri)
+      response = http.request(request)
+
+      if response.is_a?(Net::HTTPSuccess)
+        data = JSON.parse(response.body)
+        data.dig("result", "message_thread_id")
+      else
+        log("createForumTopic failed: HTTP #{response.code} #{response.body}")
+        nil
+      end
+    rescue StandardError => e
+      log("createForumTopic error: #{e.class}: #{e.message}")
+      nil
+    end
+
+    def build_http(uri)
+      http = if @config.proxy?
+        Net::HTTP.new(uri.host, uri.port, resolve(@config.proxy_addr), resolve(@config.proxy_port).to_i, resolve(@config.proxy_user), resolve(@config.proxy_pass))
+      else
+        Net::HTTP.new(uri.host, uri.port)
+      end
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.read_timeout
+      http
+    end
+
+    def resolve(value)
+      value.respond_to?(:call) ? value.call : value
+    end
+
+    def log(message)
+      return unless @config.logger
+      @config.logger.error("[TgErrorNotifier::TopicManager] #{message}")
+    end
+  end
+end

data/lib/tg_error_notifier/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TgErrorNotifier
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/tg_error_notifier.rb

@@ -3,6 +3,8 @@
 require "rails"
 require_relative "tg_error_notifier/version"
 require_relative "tg_error_notifier/configuration"
+require_relative "tg_error_notifier/grouper"
+require_relative "tg_error_notifier/topic_manager"
 require_relative "tg_error_notifier/notifier"
 require_relative "tg_error_notifier/middleware"
 require_relative "tg_error_notifier/subscriber"
@@ -32,6 +34,11 @@ module TgErrorNotifier
       notifier.notify_message(message: message, level: level, source: source, context: context)
     end
 
+    def reset!
+      @configuration = nil
+      @notifier = nil
+    end
+
     private
 
     def notifier

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tg_error_notifier
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Sergei Ustinov
@@ -35,10 +35,12 @@ files:
 - README.md
 - lib/tg_error_notifier.rb
 - lib/tg_error_notifier/configuration.rb
+- lib/tg_error_notifier/grouper.rb
 - lib/tg_error_notifier/middleware.rb
 - lib/tg_error_notifier/notifier.rb
 - lib/tg_error_notifier/railtie.rb
 - lib/tg_error_notifier/subscriber.rb
+- lib/tg_error_notifier/topic_manager.rb
 - lib/tg_error_notifier/version.rb
 homepage: https://github.com/sergeyustinov/TgErrorNotifier
 licenses: