logister-ruby 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63dccd6fdb12e5417bcca918c033a19e421087e188eac57f994939aa2eb4732f
-  data.tar.gz: 825d77d1304622efc28380e3e26167df40b411be97aa23219cce9d7f89944e6c
+  metadata.gz: 533fd3675cc1afc26e61d5bb20220cdd2e3d2fd643d51f0492f6c377eaa1c532
+  data.tar.gz: fae0c653ea921eb9d394f7c03c337a60141acd265d6ae54cd166b06b9e1ed219
 SHA512:
-  metadata.gz: 663bc90bcba5cfd300d1875536350131a5c1c2c540269168f910b648aa9a93ef98a301579389900cec0cbf135471c6078261a9a045b7be14b23987c9eef477c2
-  data.tar.gz: e0f8d74a0eff0434b7884ba945ffe96f752724c18cc3bc9b332651c02cde83e8e36a9f619e1dfe356116c6c63ef154bb79c667188cd23cf74f62b28e7d5a8361
+  metadata.gz: 94689cef817604ea72eba2c9413335588561c19d986e6a4f8dd880777bea84dbf03b40318e0ad1c8ad7fb7c5a6b87430c9509786dcdf31c9f9005b4cefc1756b
+  data.tar.gz: 1fcdca232672d5af22036584285737e9a75ea6d5d5c3d7269452ee645185d820e407c14ac5c330a5a58514a7c996d274666c2619dff3923f84c6ee1fcb4f5f2d

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v0.2.8 - 2026-06-18
+
+- Added first-class source context configuration (`repository`, `commit_sha`, and `branch`) with `LOGISTER_*` and GitHub Actions environment variable support.
+- Added `Logister.record_deployment` for posting release-to-commit deployment records to Logister.
+
+## v0.2.7 - 2026-05-22
+
+- Added `Logister.report_span` and opt-in Rails request span capture for request load waterfall charts.
+
 ## 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.

data/README.md

@@ -1,12 +1,13 @@
 # logister-ruby
 
-`logister-ruby` is the Ruby and Rails client for sending errors, logs, metrics, transactions, and check-ins to Logister.
+`logister-ruby` is the Ruby and Rails client for sending errors, logs, metrics, transactions, spans, 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)
+- [Package Links](#package-links)
 - [Self-hosted backend](#self-hosted-backend)
 - [Install From RubyGems](#install-from-rubygems)
 - [Configuration](#configuration)
@@ -30,6 +31,13 @@ Use this gem when you want a Ruby or Rails app to send telemetry into the Logist
 - Product docs: https://docs.logister.org/
 - RubyGems package: https://rubygems.org/gems/logister-ruby
 
+## Package Links
+
+- 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/
+
 ## Self-hosted backend
 
 Use the open source Logister app repository to self-host the ingestion UI/API backend:
@@ -78,6 +86,7 @@ Logister.configure do |config|
   config.max_dependencies = 20
   config.capture_sql_breadcrumbs = true
   config.sql_breadcrumb_min_duration_ms = 25.0
+  config.capture_request_spans = true
 
   config.feature_flags_resolver = lambda do |request:, user:, **|
     { new_checkout: user&.respond_to?(:beta?) && user.beta? }
@@ -121,6 +130,7 @@ end
 
 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.
 
 ## Database load metrics (ActiveRecord)
@@ -189,6 +199,16 @@ Logister.report_transaction(
   context: { trace_id: "trace-123", request_id: "req-123" }
 )
 
+Logister.report_span(
+  name: "render checkout",
+  duration_ms: 82.1,
+  trace_id: "trace-123",
+  parent_span_id: "span-root",
+  kind: "render",
+  status: "ok",
+  context: { route: "POST /checkout" }
+)
+
 Logister.report_log(
   message: "payment provider timeout",
   level: "warn",
@@ -269,10 +289,37 @@ 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.
+- Instrumentation audit: open Insights after deploy and confirm errors, logs, metrics, transactions, spans, 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.
 
+## GitHub source context and deployments
+
+When a Logister project is connected to a GitHub repository, set source context once so error frames and releases can resolve to the exact commit:
+
+```ruby
+Logister.configure do |config|
+  config.repository = ENV["LOGISTER_REPOSITORY"] || ENV["GITHUB_REPOSITORY"]
+  config.commit_sha = ENV["LOGISTER_COMMIT_SHA"] || ENV["GITHUB_SHA"]
+  config.branch = ENV["LOGISTER_BRANCH"] || ENV["GITHUB_REF_NAME"]
+end
+```
+
+CI/CD can also record the release-to-commit mapping directly:
+
+```ruby
+Logister.record_deployment(
+  release: "checkout@2026.06.18",
+  environment: "production",
+  repository: "acme/checkout",
+  commit_sha: "4f8c2d1a9b7e6c5d4a3b2c1d0e9f8a7b6c5d4e3f",
+  branch: "main",
+  workflow_run_url: "https://github.com/acme/checkout/actions/runs/123"
+)
+```
+
+`config.deployment_endpoint` defaults to the configured ingest endpoint with `/ingest_events` replaced by `/deployments`. Set `LOGISTER_DEPLOYMENT_ENDPOINT` when your deployment endpoint cannot be derived from `LOGISTER_ENDPOINT`.
+
 ## Documentation
 
 - Ruby integration docs: https://docs.logister.org/integrations/ruby/
@@ -285,15 +332,15 @@ Keep dashboard dimensions stable and low-cardinality. Good custom attribute keys
 
 ## Release
 
-This repo runs CI on commits and pull requests. Version tags run the release workflow so RubyGems and GitHub Releases stay aligned:
+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:
 
 ```bash
 # 1) bump version in lib/logister/version.rb
 # 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
+# 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
 ```
 
 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`.

data/lib/logister/client.rb

@@ -17,9 +17,11 @@ module Logister
 
       # Cache values that are static for the lifetime of this client so we
       # don't allocate on every send_request call.
-      @uri         = URI.parse(@configuration.endpoint).freeze
-      @use_ssl     = @uri.scheme == 'https'
-      @auth_header = "Bearer #{@configuration.api_key}".freeze
+      @uri            = URI.parse(@configuration.endpoint).freeze
+      @deployment_uri = URI.parse(@configuration.deployment_endpoint).freeze
+      @use_ssl        = @uri.scheme == 'https'
+      @deployment_use_ssl = @deployment_uri.scheme == 'https'
+      @auth_header    = "Bearer #{@configuration.api_key}".freeze
     end
 
     def publish(payload)
@@ -31,6 +33,12 @@ module Logister
       enqueue(payload)
     end
 
+    def publish_deployment(payload)
+      return false unless ready?
+
+      publish_deployment_sync(payload)
+    end
+
     def flush(timeout: 2)
       return true unless @configuration.async
 
@@ -112,6 +120,22 @@ module Logister
       end
     end
 
+    def publish_deployment_sync(payload)
+      attempts = 0
+      begin
+        attempts += 1
+        send_deployment_request(payload)
+      rescue StandardError => e
+        if attempts <= @configuration.max_retries
+          sleep(@configuration.retry_base_interval * (2**(attempts - 1)))
+          retry
+        end
+
+        @configuration.logger.warn("logister deployment publish failed: #{e.class} #{e.message}")
+        false
+      end
+    end
+
     def send_request(payload)
       request = Net::HTTP::Post.new(@uri)
       request['Content-Type']  = CONTENT_TYPE
@@ -131,6 +155,25 @@ module Logister
       raise "HTTP #{response.code}"
     end
 
+    def send_deployment_request(payload)
+      request = Net::HTTP::Post.new(@deployment_uri)
+      request['Content-Type']  = CONTENT_TYPE
+      request['Authorization'] = @auth_header
+      request.body             = { deployment: payload }.to_json
+
+      response = Net::HTTP.start(
+        @deployment_uri.host,
+        @deployment_uri.port,
+        use_ssl:      @deployment_use_ssl,
+        open_timeout: @configuration.timeout_seconds,
+        read_timeout: @configuration.timeout_seconds
+      ) { |http| http.request(request) }
+
+      return true if response.is_a?(Net::HTTPSuccess)
+
+      raise "HTTP #{response.code}"
+    end
+
     def monotonic_now
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end

data/lib/logister/configuration.rb

@@ -2,20 +2,26 @@ require 'logger'
 
 module Logister
   class Configuration
-    attr_accessor :api_key, :endpoint, :environment, :service, :release, :enabled, :timeout_seconds, :logger,
+    attr_accessor :api_key, :endpoint, :environment, :service, :release,
+                  :repository, :commit_sha, :branch, :enabled, :timeout_seconds, :logger,
                   :ignore_exceptions, :ignore_environments, :ignore_paths, :before_notify,
                   :async, :queue_size, :max_retries, :retry_base_interval,
                   :capture_db_metrics, :db_metric_min_duration_ms, :db_metric_sample_rate,
                   :feature_flags_resolver, :dependency_resolver, :anonymize_ip,
-                  :max_breadcrumbs, :max_dependencies,
+                  :max_breadcrumbs, :max_dependencies, :capture_request_spans,
                   :capture_sql_breadcrumbs, :sql_breadcrumb_min_duration_ms
+    attr_writer :deployment_endpoint
 
     def initialize
       @api_key = ENV['LOGISTER_API_KEY']
       @endpoint = ENV.fetch('LOGISTER_ENDPOINT', 'https://logister.org/api/v1/ingest_events')
+      @deployment_endpoint = env_value('LOGISTER_DEPLOYMENT_ENDPOINT')
       @environment = ENV.fetch('RAILS_ENV', ENV.fetch('RACK_ENV', 'development'))
       @service = ENV.fetch('LOGISTER_SERVICE', 'ruby-app')
       @release = ENV['LOGISTER_RELEASE']
+      @repository = env_value('LOGISTER_REPOSITORY') || env_value('GITHUB_REPOSITORY')
+      @commit_sha = env_value('LOGISTER_COMMIT_SHA') || env_value('GITHUB_SHA')
+      @branch = env_value('LOGISTER_BRANCH') || env_value('GITHUB_REF_NAME')
       @enabled = true
       @timeout_seconds = 2
       @logger = Logger.new($stdout)
@@ -40,8 +46,20 @@ module Logister
       @anonymize_ip = false
       @max_breadcrumbs = 40
       @max_dependencies = 20
+      @capture_request_spans = false
       @capture_sql_breadcrumbs = true
       @sql_breadcrumb_min_duration_ms = 25.0
     end
+
+    def deployment_endpoint
+      @deployment_endpoint || endpoint.to_s.sub(%r{/ingest_events\z}, '/deployments')
+    end
+
+    private
+
+    def env_value(name)
+      value = ENV[name].to_s.strip
+      value.empty? ? nil : value
+    end
   end
 end

data/lib/logister/context_helpers.rb

@@ -24,12 +24,18 @@ module Logister
       environment = config&.respond_to?(:environment) ? config.environment.to_s.presence : nil
       service = config&.respond_to?(:service) ? config.service.to_s.presence : nil
       release = config&.respond_to?(:release) ? config.release.to_s.presence : nil
+      repository = config&.respond_to?(:repository) ? config.repository.to_s.presence : nil
+      commit_sha = config&.respond_to?(:commit_sha) ? config.commit_sha.to_s.presence : nil
+      branch = config&.respond_to?(:branch) ? config.branch.to_s.presence : nil
 
       {
         deployment: {
           environment: environment || ENV["RAILS_ENV"].to_s.presence || ENV["RACK_ENV"].to_s.presence || "development",
           service: service || ENV["LOGISTER_SERVICE"].to_s.presence || "ruby-app",
           release: release || ENV["LOGISTER_RELEASE"].to_s.presence,
+          repository: repository || ENV["LOGISTER_REPOSITORY"].to_s.presence || ENV["GITHUB_REPOSITORY"].to_s.presence,
+          commit_sha: commit_sha || ENV["LOGISTER_COMMIT_SHA"].to_s.presence || ENV["GITHUB_SHA"].to_s.presence,
+          branch: branch || ENV["LOGISTER_BRANCH"].to_s.presence || ENV["GITHUB_REF_NAME"].to_s.presence,
           region: ENV["FLY_REGION"].to_s.presence || ENV["RAILS_REGION"].to_s.presence || ENV["AWS_REGION"].to_s.presence,
           hostname: Socket.gethostname.to_s.presence,
           processPid: Process.pid

data/lib/logister/railtie.rb

@@ -30,6 +30,7 @@ module Logister
         copy_setting(app, config, :anonymize_ip)
         copy_setting(app, config, :max_breadcrumbs)
         copy_setting(app, config, :max_dependencies)
+        copy_setting(app, config, :capture_request_spans)
         copy_setting(app, config, :capture_sql_breadcrumbs)
         copy_setting(app, config, :sql_breadcrumb_min_duration_ms)
       end

data/lib/logister/reporter.rb

@@ -3,6 +3,7 @@
 require 'digest'
 require 'time'
 require 'set'
+require 'securerandom'
 require_relative 'context_helpers'
 require_relative 'context_store'
 
@@ -17,8 +18,11 @@ module Logister
       @static_context = {
         environment: @configuration.environment,
         service:     @configuration.service,
-        release:     @configuration.release
-      }.freeze
+        release:     @configuration.release,
+        repository:  @configuration.repository,
+        commit_sha:  @configuration.commit_sha,
+        branch:      @configuration.branch
+      }.compact.freeze
 
       # Normalise ignore_environments once into a frozen Set of Strings so
       # ignored_environment? never allocates a mapped Array.
@@ -118,6 +122,65 @@ module Logister
       @client.publish(payload)
     end
 
+    def report_span(
+      name:,
+      duration_ms:,
+      trace_id: nil,
+      request_id: nil,
+      span_id: nil,
+      parent_span_id: nil,
+      kind: 'internal',
+      status: nil,
+      started_at: nil,
+      ended_at: nil,
+      context: {},
+      tags: {},
+      fingerprint: nil
+    )
+      return false if ignored_environment?
+      return false if ignored_path?(context)
+
+      started_at ||= Time.now.utc - (duration_ms.to_f / 1000.0)
+      span_id ||= SecureRandom.hex(8)
+      trace_id ||= span_id
+
+      payload = build_payload(
+        event_type: 'span',
+        level: status.to_s == 'error' ? 'error' : 'info',
+        message: name,
+        fingerprint: fingerprint || metric_fingerprint("span:#{kind}:#{name}"),
+        context: context.merge(
+          name: name,
+          trace_id: trace_id,
+          request_id: request_id,
+          span_id: span_id,
+          parent_span_id: parent_span_id,
+          span_kind: kind,
+          kind: kind,
+          status: status,
+          duration_ms: duration_ms,
+          started_at: normalize_timestamp(started_at),
+          ended_at: ended_at && normalize_timestamp(ended_at),
+          tags: tags
+        ).compact
+      )
+
+      payload[:started_at] = normalize_timestamp(started_at)
+      payload[:ended_at] = normalize_timestamp(ended_at) if ended_at
+      payload[:duration_ms] = duration_ms
+      payload[:trace_id] = trace_id
+      payload[:request_id] = request_id if request_id
+      payload[:span_id] = span_id
+      payload[:parent_span_id] = parent_span_id if parent_span_id
+      payload[:kind] = kind
+      payload[:status] = status if status
+
+      payload = apply_before_notify(payload)
+      return false unless payload
+
+      @client.publish(payload)
+    end
+
     def report_log(message:, level: 'info', context: {}, tags: {}, fingerprint: nil)
       return false if ignored_environment?
       return false if ignored_path?(context)
@@ -175,6 +238,40 @@ module Logister
       @client.publish(payload)
     end
 
+    def record_deployment(
+      release: nil,
+      environment: nil,
+      repository: nil,
+      commit_sha: nil,
+      branch: nil,
+      deployed_at: nil,
+      pull_request_number: nil,
+      pull_request_url: nil,
+      release_tag: nil,
+      release_url: nil,
+      compare_url: nil,
+      workflow_run_url: nil,
+      deployment_url: nil
+    )
+      payload = {
+        release: release || @configuration.release,
+        environment: environment || @configuration.environment,
+        repository: repository || @configuration.repository,
+        commit_sha: commit_sha || @configuration.commit_sha,
+        branch: branch || @configuration.branch,
+        deployed_at: deployed_at && normalize_timestamp(deployed_at),
+        pull_request_number: pull_request_number,
+        pull_request_url: pull_request_url,
+        release_tag: release_tag,
+        release_url: release_url,
+        compare_url: compare_url,
+        workflow_run_url: workflow_run_url,
+        deployment_url: deployment_url
+      }.compact
+
+      @client.publish_deployment(payload)
+    end
+
     # Store user info for the current thread so it is automatically attached to
     # every error reported during this request.
     #

data/lib/logister/request_subscriber.rb

@@ -53,10 +53,41 @@ module Logister
             viewRuntimeMs: numeric(payload[:view_runtime])
           }.compact
         )
+
+        report_request_span(payload, request_id) if capture_request_spans?
       rescue StandardError => e
         logger.warn("logister request subscriber (process_action) failed: #{e.class} #{e.message}")
       end
 
+      def report_request_span(payload, request_id)
+        duration_ms = numeric(payload[:duration])
+        return unless duration_ms&.positive?
+
+        route = "#{payload[:controller]}##{payload[:action]}"
+        started_at = Time.now.utc - (duration_ms / 1000.0)
+
+        Logister.report_span(
+          name: route,
+          kind: "server",
+          status: payload[:status].to_i >= 500 ? "error" : "ok",
+          trace_id: request_id,
+          request_id: request_id,
+          duration_ms: duration_ms,
+          started_at: started_at,
+          context: {
+            route: route,
+            request_id: request_id,
+            method: payload[:method],
+            path: payload[:path],
+            status: payload[:status],
+            timing_breakdown: {
+              db: numeric(payload[:db_runtime]),
+              render: numeric(payload[:view_runtime])
+            }.compact
+          }
+        )
+      end
+
       def handle_sql_breadcrumb(started, finished, payload)
         config = configuration
         return unless config&.capture_sql_breadcrumbs
@@ -94,6 +125,12 @@ module Logister
         nil
       end
 
+      def capture_request_spans?
+        configuration&.capture_request_spans
+      rescue StandardError
+        false
+      end
+
       def logger
         configuration&.logger || Logger.new($stdout)
       rescue StandardError

data/lib/logister/version.rb

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

data/lib/logister.rb

@@ -35,6 +35,10 @@ module Logister
       reporter.report_transaction(**kwargs)
     end
 
+    def report_span(**kwargs)
+      reporter.report_span(**kwargs)
+    end
+
     def report_log(**kwargs)
       reporter.report_log(**kwargs)
     end
@@ -43,6 +47,10 @@ module Logister
       reporter.report_check_in(**kwargs)
     end
 
+    def record_deployment(**kwargs)
+      reporter.record_deployment(**kwargs)
+    end
+
     def flush(timeout: 2)
       reporter.flush(timeout: timeout)
     end

data/logister-ruby.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.email = ['support@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.description = 'Ruby and Rails client for reporting errors, logs, metrics, transactions, spans, 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'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: logister-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.8
 platform: ruby
 authors:
 - Logister
@@ -52,7 +52,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '13.0'
 description: Ruby and Rails client for reporting errors, logs, metrics, transactions,
-  and check-ins to the Logister backend, including self-hosted installs.
+  spans, and check-ins to the Logister backend, including self-hosted installs.
 email:
 - support@logister.org
 executables: []