logister-ruby 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29c7ec6cb1f296ce54ef6081b360d8d3db79781fa70a6d4357ce746602e2ee97
-  data.tar.gz: 076efade8b179ad87615b28271fd3679ebae34f6b41d9cc8cfbcadc347b1f3d0
+  metadata.gz: 7d1ca80fe29bc17af3e645e1a07ac8f4d68bd5c7f60b01d238ef9e875e8d60c3
+  data.tar.gz: 73418842ba1d3a221374a87313e2147b70473a85fb6509132a1213832a1c79c3
 SHA512:
-  metadata.gz: fdd41ab4607104b7b2f53a6233a4b9d600411796ee6b2c709ba8743f08a65565159f3d0eaae366621f01a4c0d0f6b4f0ef9934c99728d493e1303c2f0b9a9726
-  data.tar.gz: c3b81b538e0d434d8bcf681c786e3787b42d130992a40e95f8be367902096bdf84508259ac0a54d313cd5063aefd9438fe192bb9851954694ee7011063edfb97
+  metadata.gz: 4f99665d9daa0761f7a761470c07174b8f181791caa1639a40324650b615f84932a440e9f037133221047389b64e1ffa1747c7c6dc3e661c2626e4f9978aac38
+  data.tar.gz: 767b7c876a8d8a05ed0dbbf106de09ccd474d2b1796ff5ec82e6194f9da27e1aa4abdd765f17fd3c20c71a0478ba10460250829f5e056415c98da495a8049dc1

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.3.1 - 2026-07-26
+
+- Added `Logister.suppress_reporting` and `Logister.reporting_suppressed?` for recursion-safe telemetry processing, including early exits in automatic SQL and request subscribers.
+
 ## v0.3.0 - 2026-07-25
 
 - Raised the supported runtime floor to Ruby 3.3 and refreshed the development runtime to Ruby 4.0.6, which includes current interpreter security fixes.

data/README.md

@@ -1,11 +1,47 @@
 # logister-ruby
 
-`logister-ruby` is the Ruby and Rails client for sending errors, logs, metrics, transactions, spans, and check-ins to Logister.
+`logister-ruby` sends Ruby and Rails errors, logs, metrics, transactions, spans, and scheduled-job check-ins to Logister. Rails apps also get automatic reporting for unhandled requests and failed Active Job executions.
 
 Install it from RubyGems as `logister-ruby`.
 
+Requires Ruby 3.3 or newer and Active Support 8.x.
+
+## Quick start
+
+Before you start, create a project in Logister and generate a project API key under **Project settings → API keys**.
+
+Add the gem and generate a Rails initializer:
+
+```bash
+bundle add logister-ruby
+bin/rails generate logister:install
+```
+
+Store configuration in environment variables:
+
+```bash
+export LOGISTER_API_KEY="<project-api-key>"
+export LOGISTER_ENDPOINT="https://logister.example.com/api/v1/ingest_events"
+export LOGISTER_SERVICE="checkout-web"
+export LOGISTER_RELEASE="$(git rev-parse --short HEAD)"
+```
+
+Start Rails, then send a safe test event from `bin/rails console`:
+
+```ruby
+Logister.report_error(
+  RuntimeError.new("README test error"),
+  context: { component: "checkout" },
+  fingerprint: "readme-test-error"
+)
+Logister.flush
+```
+
+Open the project inbox and confirm that **README test error** appears. A `401` response usually means the API key or endpoint is wrong; see the [Ruby integration guide](https://logister.org/docs/integrations/ruby/) for troubleshooting.
+
 ## Table Of Contents
 
+- [Quick start](#quick-start)
 - [What this gem is for](#what-this-gem-is-for)
 - [Package Links](#package-links)
 - [Self-hosted backend](#self-hosted-backend)
@@ -18,17 +54,19 @@ Install it from RubyGems as `logister-ruby`.
 - [Breadcrumbs and dependencies](#breadcrumbs-and-dependencies)
 - [ActiveJob error context](#activejob-error-context)
 - [Manual reporting](#manual-reporting)
-- [Using project Insights beta](#using-project-insights-beta)
+- [Using project Insights](#using-project-insights)
+- [GitHub source context and deployments](#github-source-context-and-deployments)
 - [Documentation](#documentation)
+- [Development](#development)
 - [Release](#release)
 
 ## What this gem is for
 
-Use this gem when you want a Ruby or Rails app to send telemetry into the Logister backend.
+Use this gem when a Ruby process should send telemetry to a hosted or self-hosted Logister server. It is an ingest client, not the Logister server itself.
 
 - Main Logister app: https://github.com/taimoorq/logister
-- Ruby integration docs: https://docs.logister.org/integrations/ruby/
-- Product docs: https://docs.logister.org/
+- Ruby integration docs: https://logister.org/docs/integrations/ruby/
+- Product docs: https://logister.org/docs/
 - RubyGems package: https://rubygems.org/gems/logister-ruby
 
 ## Package Links
@@ -36,7 +74,7 @@ Use this gem when you want a Ruby or Rails app to send telemetry into the Logist
 - RubyGems package: https://rubygems.org/gems/logister-ruby
 - GitHub releases: https://github.com/taimoorq/logister-ruby/releases
 - Source repository: https://github.com/taimoorq/logister-ruby
-- Integration docs: https://docs.logister.org/integrations/ruby/
+- Integration docs: https://logister.org/docs/integrations/ruby/
 
 ## Self-hosted backend
 
@@ -100,6 +138,8 @@ end
 
 If you are using a self-hosted Logister install, point `config.endpoint` at your own Logister host instead of `logister.org`.
 
+Keep `LOGISTER_API_KEY` in your deployment secret store. Project API keys are write-only ingest credentials, but exposing one still lets another party submit unwanted telemetry to the project.
+
 ## Reliability options
 
 ```ruby
@@ -126,12 +166,21 @@ Logister.configure do |config|
 end
 ```
 
+Use scoped suppression around work that handles or forwards telemetry. Every manual reporter and automatic Rails subscriber returns without publishing while the scope is active, and nested scopes restore the previous state even when the block raises:
+
+```ruby
+Logister.suppress_reporting do
+  TelemetryMirror.call(event)
+end
+```
+
+This is especially important when a Rails application reports into a Logister project hosted by that same application. Keep suppression narrow so failures outside the telemetry-processing boundary remain observable.
+
 ## Rails auto-reporting
 
-If Rails is present, the gem installs middleware that reports unhandled exceptions automatically.
-It also attaches richer context such as trace IDs, route/response/performance info, breadcrumbs, dependency calls, and user metadata when available.
-Set `config.capture_request_spans = true` to emit root `server` spans for request load waterfall charts while keeping existing transaction events.
-Manual `Logister.report_error` calls use the same shared enrichment path, so Ruby apps get runtime, deployment, breadcrumb, dependency, user, and nested exception cause context even when an error is reported outside the Rails middleware.
+If Rails is present, the gem installs middleware that reports unhandled exceptions automatically. It attaches trace IDs, route and response data, performance context, breadcrumbs, dependency calls, and user metadata when available.
+
+Set `config.capture_request_spans = true` to emit root `server` spans for request-load waterfall charts while keeping the existing transaction events. Manual `Logister.report_error` calls use the same enrichment path, including runtime, deployment, breadcrumb, dependency, user, and nested-exception context.
 
 ## Database load metrics (ActiveRecord)
 
@@ -225,7 +274,7 @@ Logister.report_check_in(
 )
 ```
 
-## Using project Insights beta
+## Using project Insights
 
 The Logister project Insights tab combines Inbox, Activity, and Performance signals into live dashboard views. Ruby apps get the most useful Insights experience when every event carries stable deployment context plus a few low-cardinality custom attributes.
 
@@ -322,28 +371,33 @@ Logister.record_deployment(
 
 ## Documentation
 
-- Ruby integration docs: https://docs.logister.org/integrations/ruby/
-- Insights beta guide: https://docs.logister.org/product/#insights-beta
-- Main Logister docs: https://docs.logister.org/
+- Ruby integration docs: https://logister.org/docs/integrations/ruby/
+- Insights guide: https://logister.org/docs/product/#insights
+- Main Logister docs: https://logister.org/docs/
 - [Contributing](CONTRIBUTING.md)
 - [Code of Conduct](CODE_OF_CONDUCT.md)
 - [Security Policy](SECURITY.md)
 - [Pull Request Template](.github/PULL_REQUEST_TEMPLATE.md)
 
+## Development
+
+```bash
+bundle install
+bundle-audit check --update
+bundle exec rake test
+bundle exec rake build
+```
+
 ## Release
 
-This repo runs CI on commits and pull requests. After CI passes on `main`, the release-from-main workflow creates the matching version tag. Version tags run the release workflow so RubyGems and GitHub Releases stay aligned:
+`lib/logister/version.rb` is the package version source of truth. Update it and `CHANGELOG.md` together. After CI passes on `main`, the release-from-main workflow creates a matching `vX.Y.Z` tag and dispatches the release workflow.
 
 ```bash
-# 1) bump version in lib/logister/version.rb
-# 2) update CHANGELOG.md
-# 3) commit changes
-# 4) merge to main, or push a matching tag manually:
-git tag -a v0.2.8 -m "Release logister-ruby v0.2.8"
-git push origin main v0.2.8
+git tag -a vX.Y.Z -m "Release logister-ruby vX.Y.Z"
+git push origin vX.Y.Z
 ```
 
-The `.github/workflows/release.yml` workflow verifies the tag matches `Logister::VERSION`, runs tests, builds the gem, publishes to RubyGems with trusted publishing, and then creates or updates the matching GitHub release from `CHANGELOG.md`.
+The release workflow verifies tag/version parity, audits and tests the package, builds the gem, publishes to RubyGems with trusted publishing, and only then creates the GitHub Release. RubyGems versions are immutable; corrections need a new patch version.
 
 Before tag releases can publish the gem, configure a RubyGems trusted publisher for:
 
@@ -352,8 +406,9 @@ Before tag releases can publish the gem, configure a RubyGems trusted publisher
 - Workflow file: `.github/workflows/release.yml`
 - Environment: leave blank unless you also add a GitHub release environment to the workflow
 
-Manual publishing is still possible with Bundler's built-in release flow when needed:
+Verify both release surfaces before calling a release complete:
 
 ```bash
-bundle exec rake release
+curl -fsSL https://rubygems.org/api/v2/rubygems/logister-ruby/versions/X.Y.Z.json | jq '{number,ruby_version,sha}'
+gh release view vX.Y.Z
 ```

data/lib/logister/reporter.rb

@@ -44,6 +44,7 @@ module Logister
     end
 
     def report_error(exception, context: {}, tags: {}, level: 'error', fingerprint: nil)
+      return false if Logister.reporting_suppressed?
       return false if ignored_exception?(exception)
       return false if ignored_path?(context)
 
@@ -69,6 +70,7 @@ module Logister
     end
 
     def report_metric(message:, value: nil, unit: nil, level: 'info', context: {}, tags: {}, fingerprint: nil)
+      return false if Logister.reporting_suppressed?
       return false if ignored_environment?
       return false if ignored_path?(context)
 
@@ -100,6 +102,7 @@ module Logister
     end
 
     def report_transaction(name:, duration_ms:, level: 'info', context: {}, tags: {}, fingerprint: nil, status: nil)
+      return false if Logister.reporting_suppressed?
       return false if ignored_environment?
       return false if ignored_path?(context)
 
@@ -137,6 +140,7 @@ module Logister
       tags: {},
       fingerprint: nil
     )
+      return false if Logister.reporting_suppressed?
       return false if ignored_environment?
       return false if ignored_path?(context)
 
@@ -182,6 +186,7 @@ module Logister
     end
 
     def report_log(message:, level: 'info', context: {}, tags: {}, fingerprint: nil)
+      return false if Logister.reporting_suppressed?
       return false if ignored_environment?
       return false if ignored_path?(context)
 
@@ -212,6 +217,7 @@ module Logister
       trace_id: nil,
       request_id: nil
     )
+      return false if Logister.reporting_suppressed?
       return false if ignored_environment?
 
       payload = build_payload(
@@ -253,6 +259,8 @@ module Logister
       workflow_run_url: nil,
       deployment_url: nil
     )
+      return false if Logister.reporting_suppressed?
+
       payload = {
         release: release || @configuration.release,
         environment: environment || @configuration.environment,

data/lib/logister/reporting_scope.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Logister
+  module ReportingScope
+    STATE_KEY = :__logister_reporting_suppressed
+
+    module_function
+
+    def suppress
+      previous = state
+      self.state = true
+      yield
+    ensure
+      self.state = previous
+    end
+
+    def suppressed?
+      state == true
+    end
+
+    def state
+      if defined?(ActiveSupport::IsolatedExecutionState)
+        ActiveSupport::IsolatedExecutionState[STATE_KEY]
+      else
+        Thread.current[STATE_KEY]
+      end
+    end
+    private_class_method :state
+
+    def state=(value)
+      if defined?(ActiveSupport::IsolatedExecutionState)
+        ActiveSupport::IsolatedExecutionState[STATE_KEY] = value
+      else
+        Thread.current[STATE_KEY] = value
+      end
+    end
+    private_class_method :state=
+  end
+end

data/lib/logister/request_subscriber.rb

@@ -22,6 +22,7 @@ module Logister
       private
 
       def handle_process_action(payload)
+        return if Logister.reporting_suppressed?
         return unless payload.is_a?(Hash)
 
         request_id = payload[:request_id].to_s.presence
@@ -89,6 +90,8 @@ module Logister
       end
 
       def handle_sql_breadcrumb(started, finished, payload)
+        return if Logister.reporting_suppressed?
+
         config = configuration
         return unless config&.capture_sql_breadcrumbs
         return unless payload.is_a?(Hash)

data/lib/logister/sql_subscriber.rb

@@ -29,6 +29,8 @@ module Logister
       private
 
       def handle_sql_event(started, finished, payload)
+        return if Logister.reporting_suppressed?
+
         config = Logister.configuration
 
         # Short-circuit as cheaply as possible when metrics are disabled so

data/lib/logister/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Logister
-  VERSION = '0.3.0'
+  VERSION = '0.3.1'
 end

data/lib/logister.rb

@@ -1,5 +1,6 @@
 require_relative 'logister/version'
 require_relative 'logister/configuration'
+require_relative 'logister/reporting_scope'
 require_relative 'logister/client'
 require_relative 'logister/reporter'
 require_relative 'logister/context_helpers'
@@ -23,6 +24,14 @@ module Logister
       @reporter ||= Reporter.new(configuration)
     end
 
+    def suppress_reporting(&block)
+      ReportingScope.suppress(&block)
+    end
+
+    def reporting_suppressed?
+      ReportingScope.suppressed?
+    end
+
     def report_error(exception, **kwargs)
       reporter.report_error(exception, **kwargs)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: logister-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Logister
@@ -86,6 +86,7 @@ files:
 - lib/logister/middleware.rb
 - lib/logister/railtie.rb
 - lib/logister/reporter.rb
+- lib/logister/reporting_scope.rb
 - lib/logister/request_subscriber.rb
 - lib/logister/sql_subscriber.rb
 - lib/logister/version.rb