logister-ruby 0.2.3 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd9ec67090820ac7b825afcbfd87a6a75f26033b0153daf8ee60b44a6d6fbbf3
-  data.tar.gz: 2175055728eb9dcc9bc9ed0acf4b3640f52900bcd35933fdd92db6ebbc1dfc3a
+  metadata.gz: 63dccd6fdb12e5417bcca918c033a19e421087e188eac57f994939aa2eb4732f
+  data.tar.gz: 825d77d1304622efc28380e3e26167df40b411be97aa23219cce9d7f89944e6c
 SHA512:
-  metadata.gz: cc1412c538be57e39a12e3f7c6939d1e710aa387490575ddf9af7df8ccda96cae3faafd9256348e18208ce63ebc0922f1696ae6b6d22aaeaf279c2b555960eee
-  data.tar.gz: 92276f407d774dc3010447cba8b5f0aea0c878ad8d30ba428b46585da3afbdf1dd9f0eb11b6cc62e89afa72e6433292eab19898551c5749a378d11a66aa9e646
+  metadata.gz: 663bc90bcba5cfd300d1875536350131a5c1c2c540269168f910b648aa9a93ef98a301579389900cec0cbf135471c6078261a9a045b7be14b23987c9eef477c2
+  data.tar.gz: e0f8d74a0eff0434b7884ba945ffe96f752724c18cc3bc9b332651c02cde83e8e36a9f619e1dfe356116c6c63ef154bb79c667188cd23cf74f62b28e7d5a8361

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## v0.2.6 - 2026-05-22
+
+- Added README guidance for using Ruby reports with the Logister project Insights beta, including practical metric, transaction, log, check-in, and custom attribute examples.
+- Added a tag-based release workflow that publishes the gem to RubyGems with trusted publishing and then creates or updates the matching GitHub release.
+
+## v0.2.5 - 2026-05-21
+
+- Added metric value/unit options to `Logister.report_metric` while keeping the existing context/tags API.
+- Added per-check-in environment, release, occurred-at, trace ID, and request ID options to `Logister.report_check_in`.
+
+## v0.2.4 - 2026-05-21
+
+- Enriched every Ruby error report with shared runtime, deployment, breadcrumb, and dependency context, including manual `Logister.report_error` calls.
+- Added structured nested exception cause data to Ruby error payloads.
+
+## v0.2.3 - 2026-04-22
+
+- Refined the Ruby and Rails client for Logister event delivery.
+- Added richer reporting support for logs, transactions, check-ins, ActiveJob failures, breadcrumbs, and dependency context.
+- Improved package metadata and docs linkage for the canonical Logister docs and self-hosted backend.
+- Documented the gem as the Ruby client for the Logister backend instead of only the hosted `logister.org` service.

data/README.md

@@ -1,6 +1,34 @@
 # logister-ruby
 
-`logister-ruby` sends application errors and custom metrics to `logister.org`.
+`logister-ruby` is the Ruby and Rails client for sending errors, logs, metrics, transactions, and check-ins to Logister.
+
+Install it from RubyGems as `logister-ruby`.
+
+## Table Of Contents
+
+- [What this gem is for](#what-this-gem-is-for)
+- [Self-hosted backend](#self-hosted-backend)
+- [Install From RubyGems](#install-from-rubygems)
+- [Configuration](#configuration)
+- [Reliability options](#reliability-options)
+- [Filtering and redaction](#filtering-and-redaction)
+- [Rails auto-reporting](#rails-auto-reporting)
+- [Database load metrics (ActiveRecord)](#database-load-metrics-activerecord)
+- [Breadcrumbs and dependencies](#breadcrumbs-and-dependencies)
+- [ActiveJob error context](#activejob-error-context)
+- [Manual reporting](#manual-reporting)
+- [Using project Insights beta](#using-project-insights-beta)
+- [Documentation](#documentation)
+- [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.
+
+- Main Logister app: https://github.com/taimoorq/logister
+- Ruby integration docs: https://docs.logister.org/integrations/ruby/
+- Product docs: https://docs.logister.org/
+- RubyGems package: https://rubygems.org/gems/logister-ruby
 
 ## Self-hosted backend
 
@@ -8,12 +36,26 @@ Use the open source Logister app repository to self-host the ingestion UI/API ba
 
 - App source: https://github.com/taimoorq/logister
 
-## Install
+## Install From RubyGems
+
+With Bundler in a Rails or Ruby app:
 
 ```ruby
 gem "logister-ruby"
 ```
 
+Then install:
+
+```bash
+bundle install
+```
+
+Or install the gem directly from RubyGems:
+
+```bash
+gem install logister-ruby
+```
+
 Then generate an initializer in Rails:
 
 ```bash
@@ -47,6 +89,8 @@ Logister.configure do |config|
 end
 ```
 
+If you are using a self-hosted Logister install, point `config.endpoint` at your own Logister host instead of `logister.org`.
+
 ## Reliability options
 
 ```ruby
@@ -76,7 +120,8 @@ end
 ## Rails auto-reporting
 
 If Rails is present, the gem installs middleware that reports unhandled exceptions automatically.
-It also attaches richer context (trace IDs, route/response/performance info, breadcrumbs, dependency calls, and user metadata when available).
+It also attaches richer context such as trace IDs, route/response/performance info, breadcrumbs, dependency calls, and user metadata when available.
+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.
 
 ## Database load metrics (ActiveRecord)
 
@@ -130,6 +175,8 @@ Logister.report_error(StandardError.new("Something failed"), tags: { area: "chec
 
 Logister.report_metric(
   message: "checkout.completed",
+  value: 1,
+  unit: "count",
   level: "info",
   context: { duration_ms: 123 },
   tags: { region: "us-east-1" }
@@ -151,18 +198,115 @@ Logister.report_log(
 Logister.report_check_in(
   slug: "nightly-reconcile",
   status: "ok",
-  expected_interval_seconds: 900
+  expected_interval_seconds: 900,
+  duration_ms: 248.3,
+  trace_id: "trace-123",
+  request_id: "req-123"
 )
 ```
 
+## Using project Insights beta
+
+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.
+
+Use `config.environment`, `config.release`, and top-level scalar `context` values for the dimensions you want to filter by:
+
+```ruby
+Logister.configure do |config|
+  config.environment = Rails.env
+  config.release = ENV["RELEASE_SHA"]
+  config.service = "billing-web"
+end
+
+Logister.report_metric(
+  message: "queue.depth",
+  value: Sidekiq::Queue.new("billing").size,
+  unit: "jobs",
+  context: {
+    service: "billing-worker",
+    queue: "billing",
+    region: "us-east-1",
+    tenant_tier: "enterprise"
+  }
+)
+
+Logister.report_transaction(
+  name: "POST /checkout",
+  duration_ms: 184.7,
+  status: 200,
+  context: {
+    service: "billing-web",
+    route: "POST /checkout",
+    feature_flag: "new_checkout",
+    tenant_tier: "enterprise"
+  }
+)
+
+Logister.report_log(
+  message: "payment provider retry",
+  level: "warn",
+  context: {
+    service: "billing-worker",
+    provider: "stripe",
+    queue: "billing"
+  }
+)
+
+Logister.report_check_in(
+  slug: "nightly-reconcile",
+  status: "ok",
+  expected_interval_seconds: 3600,
+  duration_ms: 842.7,
+  context: {
+    service: "billing-worker",
+    queue: "reconcile"
+  }
+)
+```
+
+Practical Insights recipes:
+
+- Release validation: send `release`, then filter the Insights tab to the new release and compare errors, transaction P95, database query timing, and custom metrics.
+- Queue monitoring: report metrics such as `queue.depth`, `queue.latency`, and `jobs.retry_count` with a stable `queue` context key.
+- Performance triage: send transaction events with `route`, `service`, and `tenant_tier` so slow routes can be filtered beside errors and logs.
+- Instrumentation audit: open Insights after deploy and confirm errors, logs, metrics, transactions, and check-ins all appear in the recent stream.
+
+Keep dashboard dimensions stable and low-cardinality. Good custom attribute keys include `service`, `region`, `queue`, `route`, `tenant_tier`, `provider`, and `feature_flag`. Avoid raw IDs, emails, request bodies, SQL text, and per-user values as top-level Insights dimensions.
+
+## 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/
+- [Contributing](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Security Policy](SECURITY.md)
+- [Pull Request Template](.github/PULL_REQUEST_TEMPLATE.md)
+
 ## Release
 
-Use Bundler's built-in release flow:
+This repo runs CI on commits and pull requests. Version tags run the release workflow so RubyGems and GitHub Releases stay aligned:
 
 ```bash
 # 1) bump version in lib/logister/version.rb
-# 2) commit changes
-bundle exec rake release
+# 2) update CHANGELOG.md
+# 3) commit changes
+# 4) push a matching tag, for example:
+git tag -a v0.2.6 -m "Release logister-ruby v0.2.6"
+git push origin main v0.2.6
 ```
 
-`rake release` will build the gem, create a git tag, push commits/tags, and push to RubyGems.
+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`.
+
+Before tag releases can publish the gem, configure a RubyGems trusted publisher for:
+
+- GitHub owner: `taimoorq`
+- Repository: `logister-ruby`
+- 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:
+
+```bash
+bundle exec rake release
+```

data/lib/logister/reporter.rb

@@ -3,6 +3,8 @@
 require 'digest'
 require 'time'
 require 'set'
+require_relative 'context_helpers'
+require_relative 'context_store'
 
 module Logister
   class Reporter
@@ -41,7 +43,7 @@ module Logister
       return false if ignored_exception?(exception)
       return false if ignored_path?(context)
 
-      merged_context = context.dup
+      merged_context = default_error_context.merge(context)
       user = current_user_context
       merged_context[:user] = user if user
 
@@ -51,11 +53,7 @@ module Logister
         message:     "#{exception.class}: #{exception.message}",
         fingerprint: fingerprint || default_fingerprint(exception),
         context:     merged_context.merge(
-          exception: {
-            class:     exception.class.to_s,
-            message:   exception.message.to_s,
-            backtrace: Array(exception.backtrace).first(50)
-          },
+          exception: exception_context(exception),
           tags: tags
         )
       )
@@ -66,16 +64,29 @@ module Logister
       @client.publish(payload)
     end
 
-    def report_metric(message:, level: 'info', context: {}, tags: {}, fingerprint: nil)
+    def report_metric(message:, value: nil, unit: nil, level: 'info', context: {}, tags: {}, fingerprint: nil)
       return false if ignored_environment?
       return false if ignored_path?(context)
 
+      metric_context = context.merge(tags: tags)
+      if value
+        metric_context = metric_context.merge(
+          metric: {
+            name: message,
+            value: value,
+            unit: unit
+          }.compact,
+          value: value,
+          unit: unit
+        ).compact
+      end
+
       payload = build_payload(
         event_type:  'metric',
         level:       level,
         message:     message,
         fingerprint: fingerprint || metric_fingerprint(message),
-        context:     context.merge(tags: tags)
+        context:     metric_context
       )
 
       payload = apply_before_notify(payload)
@@ -125,7 +136,19 @@ module Logister
       @client.publish(payload)
     end
 
-    def report_check_in(slug:, status: 'ok', expected_interval_seconds: 300, duration_ms: nil, context: {}, level: nil)
+    def report_check_in(
+      slug:,
+      status: 'ok',
+      expected_interval_seconds: 300,
+      duration_ms: nil,
+      context: {},
+      level: nil,
+      environment: nil,
+      release: nil,
+      occurred_at: nil,
+      trace_id: nil,
+      request_id: nil
+    )
       return false if ignored_environment?
 
       payload = build_payload(
@@ -137,9 +160,14 @@ module Logister
           check_in_slug: slug,
           check_in_status: status,
           expected_interval_seconds: expected_interval_seconds,
-          duration_ms: duration_ms
+          duration_ms: duration_ms,
+          environment: environment,
+          release: release,
+          trace_id: trace_id,
+          request_id: request_id
         ).compact
       )
+      payload[:occurred_at] = normalize_timestamp(occurred_at) if occurred_at
 
       payload = apply_before_notify(payload)
       return false unless payload
@@ -185,6 +213,31 @@ module Logister
       Thread.current[:logister_user]
     end
 
+    def default_error_context
+      Logister::ContextHelpers.compact_deep(
+        {
+          breadcrumbs: Logister::ContextStore.breadcrumbs.presence,
+          dependencyCalls: Logister::ContextStore.dependencies.presence
+        }
+          .merge(Logister::ContextHelpers.runtime_context)
+          .merge(Logister::ContextHelpers.deployment_context)
+      )
+    rescue StandardError => e
+      @configuration.logger.warn("logister default error context failed: #{e.class} #{e.message}")
+      {}
+    end
+
+    def exception_context(exception, depth = 0)
+      return nil unless exception
+
+      {
+        class:     exception.class.to_s,
+        message:   exception.message.to_s,
+        backtrace: Array(exception.backtrace).first(50),
+        cause:     depth < 5 ? exception_context(exception.cause, depth + 1) : nil
+      }.compact
+    end
+
     def build_payload(event_type:, level:, message:, fingerprint:, context:)
       {
         event_type:  event_type,
@@ -199,6 +252,10 @@ module Logister
       }
     end
 
+    def normalize_timestamp(timestamp)
+      timestamp.respond_to?(:utc) ? timestamp.utc.iso8601 : timestamp.to_s
+    end
+
     def apply_before_notify(payload)
       hook = @configuration.before_notify
       return payload unless hook.respond_to?(:call)

data/lib/logister/version.rb

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

data/logister-ruby.gemspec

@@ -6,21 +6,25 @@ Gem::Specification.new do |spec|
   spec.authors = ['Logister']
   spec.email = ['support@logister.org']
 
-  spec.summary = 'Send Rails errors and metrics to logister.org'
-  spec.description = 'Client gem for reporting errors and custom metrics from Ruby and Rails apps to logister.org'
+  spec.summary = 'Ruby and Rails client for sending events to Logister'
+  spec.description = 'Ruby and Rails client for reporting errors, logs, metrics, transactions, and check-ins to the Logister backend, including self-hosted installs.'
   spec.homepage = 'https://github.com/taimoorq/logister-ruby'
   spec.license = 'MIT'
   spec.required_ruby_version = '>= 3.1.0'
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/taimoorq/logister-ruby'
+  spec.metadata['documentation_uri'] = 'https://docs.logister.org/integrations/ruby/'
+  spec.metadata['changelog_uri'] = 'https://github.com/taimoorq/logister-ruby/blob/main/CHANGELOG.md'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/taimoorq/logister-ruby/issues'
 
   spec.files = Dir.chdir(__dir__) do
-    Dir.glob('lib/**/*') + ['README.md', 'LICENSE', 'logister-ruby.gemspec']
+    Dir.glob('lib/**/*') + ['README.md', 'CHANGELOG.md', 'LICENSE', 'logister-ruby.gemspec']
   end
 
   spec.require_paths = ['lib']
 
   spec.add_dependency 'activesupport', '>= 6.1'
+  spec.add_development_dependency 'actionpack', '>= 6.1'
   spec.add_development_dependency 'rake', '>= 13.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: logister-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.6
 platform: ruby
 authors:
 - Logister
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -37,14 +51,15 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '13.0'
-description: Client gem for reporting errors and custom metrics from Ruby and Rails
-  apps to logister.org
+description: Ruby and Rails client for reporting errors, logs, metrics, transactions,
+  and check-ins to the Logister backend, including self-hosted installs.
 email:
 - support@logister.org
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/generators/logister/install_generator.rb
@@ -69,6 +84,9 @@ licenses:
 metadata:
   homepage_uri: https://github.com/taimoorq/logister-ruby
   source_code_uri: https://github.com/taimoorq/logister-ruby
+  documentation_uri: https://docs.logister.org/integrations/ruby/
+  changelog_uri: https://github.com/taimoorq/logister-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/taimoorq/logister-ruby/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -83,7 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
-summary: Send Rails errors and metrics to logister.org
+summary: Ruby and Rails client for sending events to Logister
 test_files: []