nexus_semantic_logger 1.14.1 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32ad58a45b7f549b78d5a38b15319c90d4e03a254d8c59cd2924bf29f9194501
-  data.tar.gz: 8999d6c1cef19b0614050b31f193b42e07b10c5d033720890966ce56f137ed5c
+  metadata.gz: 0dcbcb0a7a4c7de68e7496b8ffb7f6d5d5e08742a981af559e48162bd149fc40
+  data.tar.gz: 4cd8249c19ce91fc5a3f2ef7c1919f91685235cf385291f8e0272ecfaf71234f
 SHA512:
-  metadata.gz: dc0dabdf1cdc35d17b22f0f6f166f84802f14d9b16c04b5da4e9ddc9ae42f2c1de9c5eca4f87d62bb6ac30235d03f792e1bed563f18f4f0a04cce230713326a0
-  data.tar.gz: 3daf0fed3524cf841917e4e43ea6abd9bc4b79ded74fbca066f4cd8b54cecbd13fbf9bf632c55b9942a36e953002a2d6942a2e5feecee3b9c2b1fa9760b1b118
+  metadata.gz: 17a71300ae2d6f1bd8c5d0175b167071b818c54ea489d5973a6a2d92cc2fa99dd8f8369015b57520ae8eaf2dfef84f17b30e28c12736637c1620d48ec435d28c
+  data.tar.gz: f93a642bc2e30c4913f65cab35cbda108a99d9b15f78fab5f715aa91d53511560d9a2189bd10d02782a90c9b810add8efec1509278bb6108fd4a1ee0b9258416

data/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+  pull_request:
+
+jobs:
+  rspec:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        gemfile: [rails_7_1, rails_7_2, rails_8_0]
+    env:
+      BUNDLE_GEMFILE: gemfiles/${{ matrix.gemfile }}.gemfile
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2.2"
+      - run: bundle install --jobs 4
+      - run: bundle exec rspec
+
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2.2"
+      - run: bundle install --jobs 4
+      - run: bundle exec rubocop
+
+  release:
+    needs: [rspec, rubocop]
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2.2"
+      - run: bundle install --jobs 4
+      - name: Build and push gem to RubyGems
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+        run: |
+          sed -i "s/0.0.0/${GITHUB_REF_NAME}/g" lib/nexus_semantic_logger/version.rb
+          gem build nexus_semantic_logger.gemspec
+          gem push nexus_semantic_logger-*.gem

data/.gitignore

@@ -1,3 +1,5 @@
 .idea/
 .vscode/
 results/
+Gemfile.lock
+gemfiles/*.gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/Appraisals

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+appraise "rails-7-1" do
+  gem "railties", "~> 7.1.0"
+end
+
+appraise "rails-7-2" do
+  gem "railties", "~> 7.2.0"
+end
+
+appraise "rails-8-0" do
+  gem "railties", "~> 8.0.0"
+end

data/Gemfile

@@ -3,6 +3,7 @@ source 'https://rubygems.org'
 
 gemspec
 
+gem 'appraisal'
 gem 'rubocop'
 gem 'rubocop-shopify', "~> 1.0.4", require: false
 

data/README.md

@@ -60,6 +60,20 @@ For example, to increment a count:
 NexusSemanticLogger.metrics.increment('nexus.users.registration.complete')
 ```
 
+### Running shell commands
+
+Use `NexusSemanticLogger.shell.capture3` as a drop-in replacement for `Open3.capture3`:
+
+```
+stdout, stderr, status = NexusSemanticLogger.shell.capture3('7z', 'x', archive_path)
+```
+
+Each call is wrapped in a Datadog APM span (`shell.exec`) and emits `nexus.shell.duration_ms`,
+`nexus.shell.peak_rss_mb` (the child's peak RSS, sampled from procfs) and `nexus.shell.executions`
+metrics tagged with `command:<binary>` and `outcome:<success|failure|signaled|exception>`, plus an
+info log line. A child killed by the kernel OOM killer shows up as `outcome:signaled` with
+`termsig: 9` and its last-observed peak RSS.
+
 # Local gem development
 
 Steps to run this gem from local sources in one the nexus 'staged build' rails components:

data/gemfiles/rails_7_1.gemfile

@@ -0,0 +1,11 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "rubocop"
+gem "rubocop-shopify", "~> 1.0.4", require: false
+gem "rspec"
+gem "railties", "~> 7.1.0"
+
+gemspec path: "../"

data/gemfiles/rails_7_2.gemfile

@@ -0,0 +1,11 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "rubocop"
+gem "rubocop-shopify", "~> 1.0.4", require: false
+gem "rspec"
+gem "railties", "~> 7.2.0"
+
+gemspec path: "../"

data/gemfiles/rails_8_0.gemfile

@@ -0,0 +1,11 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "rubocop"
+gem "rubocop-shopify", "~> 1.0.4", require: false
+gem "rspec"
+gem "railties", "~> 8.0.0"
+
+gemspec path: "../"

data/lib/nexus_semantic_logger/datadog_formatter.rb

@@ -22,7 +22,6 @@ module NexusSemanticLogger
       hash[:source] = :rails
       level = hash.delete(:level)
       hash[:status] = level
-      hash[:railsenv] = Rails.env
       hash[:service] = @service
       hash.delete(:application)
       hash.delete(:environment)

data/lib/nexus_semantic_logger/datadog_tracer.rb

@@ -18,7 +18,6 @@ module NexusSemanticLogger
           # Note that 'env' is NOT sent- that is set as the default on the agent e.g. staging, canary, production.
           # It does not necessarily align with the Rails env, and we do not want to double tag the env.
           global_tags = [
-            "railsenv:#{Rails.env}",
             "service:#{service}",
             "container_name:#{container_name}",
             "pod_name:#{pod_name}",
@@ -42,7 +41,6 @@ module NexusSemanticLogger
           # Trace tags API is Hash<String,String>, see https://www.rubydoc.info/gems/ddtrace/Datadog/Tracing
           # Should match the global tags, but as a Hash.
           c.tags = {
-            railsenv: Rails.env,
             service: service,
             container_name: container_name,
             pod_name: pod_name,

data/lib/nexus_semantic_logger/extensions/action_dispatch/debug_exceptions.rb

@@ -14,8 +14,19 @@ module ActionDispatch
       # log_rescued_responses? is a rails7 feature, but this gem is also used on rails6. Check for its existence.
       return if respond_to?('log_rescued_responses?') && !log_rescued_responses?(request) && wrapper.rescue_response?
 
-      ActiveSupport::Deprecation.silence do
-        ActionController::Base.logger.fatal(wrapper.exception)
+      # Silence deprecations emitted while logging the exception. The API changed in Rails 7.1: the
+      # ActiveSupport::Deprecation singleton was deprecated and its class-level `silence` was removed in 7.2,
+      # replaced by Rails.application.deprecators. Calling the removed singleton on >= 7.2 raises NoMethodError
+      # inside render_exception (before the exception is logged), which swallowed all exception logging and
+      # produced empty 500s. Use whichever API the Rails version provides, mirroring rails_semantic_logger.
+      if (Rails::VERSION::MAJOR == 7 && Rails::VERSION::MINOR >= 1) || Rails::VERSION::MAJOR > 7
+        Rails.application.deprecators.silence do
+          ActionController::Base.logger.fatal(wrapper.exception)
+        end
+      else
+        ActiveSupport::Deprecation.silence do
+          ActionController::Base.logger.fatal(wrapper.exception)
+        end
       end
     end
   end

data/lib/nexus_semantic_logger/traced_shell.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+require 'open3'
+require 'semantic_logger'
+
+module NexusSemanticLogger
+  # Instrumented replacement for Open3.capture3, so child processes (7z, unrar, yara, ...) are
+  # observable. Each call produces:
+  #   - a Datadog APM span ('shell.exec', resource = binary basename) tagged with the command line,
+  #     exit status, terminating signal and peak RSS
+  #   - statsd metrics: nexus.shell.duration_ms (timing), nexus.shell.peak_rss_mb (distribution)
+  #     and nexus.shell.executions (count), tagged with command:<binary> and
+  #     outcome:<success|failure|signaled|exception>
+  #   - an info log line with the same payload
+  #
+  # Peak RSS is the child's kernel-maintained high-water mark (VmHWM in /proc/<pid>/status),
+  # sampled while the child runs. Linux only; nil elsewhere. Direct child only - grandchildren
+  # are not measured. A process killed by the kernel OOM killer reports outcome:signaled with
+  # termsig 9 and the last-sampled peak RSS, which is exactly the evidence an OOM postmortem needs.
+  class TracedShell
+    include SemanticLogger::Loggable
+
+    SPAN_NAME = 'shell.exec'
+    METRIC_PREFIX = 'nexus.shell'
+    RSS_POLL_INTERVAL_SECONDS = 0.05
+    COMMAND_LOG_MAX_CHARS = 500
+
+    # Drop-in replacement for Open3.capture3.
+    # A leading env Hash and trailing spawn options are supported as with Open3; the env Hash is
+    # excluded from spans/logs since it may hold secrets.
+    # @return [Array(String, String, Process::Status)] stdout, stderr, status.
+    def capture3(*cmd, stdin_data: '', binmode: false, **opts)
+      binary = command_basename(cmd)
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      outcome = 'exception'
+      status = nil
+      peak_rss_kb = nil
+      trace(binary, cmd) do |span|
+        stdout, stderr, status, peak_rss_kb = run_capture3(cmd, stdin_data, binmode, opts)
+        outcome = outcome_for(status)
+        annotate_span(span, status, peak_rss_kb)
+        [stdout, stderr, status]
+      end
+    ensure
+      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+      record(cmd, outcome, duration_ms, status, peak_rss_kb)
+    end
+
+    private
+
+    def trace(binary, cmd, &block)
+      return yield(nil) unless defined?(Datadog::Tracing)
+
+      Datadog::Tracing.trace(SPAN_NAME, resource: binary, type: 'system') do |span|
+        span.set_tag('shell.command', command_string(cmd))
+        block.call(span)
+      end
+    end
+
+    # Open3.capture3 semantics, reimplemented over popen3 so the child pid is available to the
+    # RSS poller while it runs.
+    def run_capture3(cmd, stdin_data, binmode, opts)
+      Open3.popen3(*cmd, **opts) do |stdin, stdout, stderr, wait_thr|
+        if binmode
+          stdin.binmode
+          stdout.binmode
+          stderr.binmode
+        end
+        poller = start_rss_poller(wait_thr)
+        out_reader = Thread.new { stdout.read }
+        err_reader = Thread.new { stderr.read }
+        begin
+          stdin.write(stdin_data) if stdin_data && !stdin_data.empty?
+        rescue Errno::EPIPE
+          # Child exited without consuming stdin; Open3.capture3 ignores this too.
+        end
+        stdin.close
+        status = wait_thr.value
+        [out_reader.value, err_reader.value, status, poller&.value]
+      end
+    end
+
+    def start_rss_poller(wait_thr)
+      return nil unless procfs?
+
+      pid = wait_thr.pid
+      Thread.new do
+        peak_kb = nil
+        while wait_thr.alive?
+          sample = read_vm_hwm_kb(pid)
+          peak_kb = sample if sample && (peak_kb.nil? || sample > peak_kb)
+          sleep(RSS_POLL_INTERVAL_SECONDS)
+        end
+        peak_kb
+      end
+    end
+
+    # VmHWM is the process's peak RSS as maintained by the kernel, so each sample is itself a
+    # high-water mark; the true peak can only be missed by the process exiting within one poll.
+    def read_vm_hwm_kb(pid)
+      File.read("/proc/#{pid}/status")[/^VmHWM:\s*(\d+)\s*kB/, 1]&.to_i
+    rescue SystemCallError, IOError
+      nil
+    end
+
+    def procfs?
+      return @procfs if defined?(@procfs)
+
+      @procfs = File.exist?('/proc/self/status')
+    end
+
+    def outcome_for(status)
+      return 'success' if status.success?
+      return 'signaled' if status.signaled?
+
+      'failure'
+    end
+
+    def annotate_span(span, status, peak_rss_kb)
+      return unless span
+
+      span.set_tag('shell.exit_status', status.exitstatus) if status.exitstatus
+      span.set_tag('shell.termsig', status.termsig) if status.signaled?
+      span.set_tag('shell.peak_rss_mb', to_mb(peak_rss_kb)) if peak_rss_kb
+    end
+
+    def record(cmd, outcome, duration_ms, status, peak_rss_kb)
+      tags = ["command:#{command_basename(cmd)}", "outcome:#{outcome}"]
+      metrics = NexusSemanticLogger.metrics
+      metrics.timing("#{METRIC_PREFIX}.duration_ms", duration_ms, tags: tags)
+      metrics.increment("#{METRIC_PREFIX}.executions", tags: tags)
+      peak_rss_mb = peak_rss_kb && to_mb(peak_rss_kb)
+      metrics.distribution("#{METRIC_PREFIX}.peak_rss_mb", peak_rss_mb, tags: tags) if peak_rss_mb
+
+      payload = {
+        command: command_string(cmd),
+        outcome: outcome,
+        duration_ms: duration_ms,
+        exit_status: status&.exitstatus,
+        termsig: status&.signaled? ? status.termsig : nil,
+        peak_rss_mb: peak_rss_mb,
+      }.compact
+      logger.info('Shell command finished.', payload)
+    end
+
+    # Binary basename for span resource and metric tags; deliberately low cardinality.
+    def command_basename(cmd)
+      first = cmd.first.is_a?(Hash) ? cmd[1] : cmd.first
+      first = first.first if first.is_a?(Array) # [binary, argv0] form
+      return 'unknown' unless first.is_a?(String)
+
+      File.basename(first.split(' ').first.to_s)
+    end
+
+    def command_string(cmd)
+      parts = cmd.reject { |part| part.is_a?(Hash) }
+      parts.flatten.join(' ').slice(0, COMMAND_LOG_MAX_CHARS)
+    end
+
+    def to_mb(kb)
+      kb.fdiv(1024).round(1)
+    end
+  end
+end

data/lib/nexus_semantic_logger/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 module NexusSemanticLogger
-  # Leave this as 1.14.1 in order for CI process to replace with the tagged version.
-  VERSION = '1.14.1'
+  # Leave this as 1.15.0 in order for CI process to replace with the tagged version.
+  VERSION = '1.15.0'
 end

data/lib/nexus_semantic_logger.rb

@@ -5,12 +5,18 @@ require 'nexus_semantic_logger/datadog_formatter'
 require 'nexus_semantic_logger/datadog_singleton'
 require 'nexus_semantic_logger/datadog_tracer'
 require 'nexus_semantic_logger/logger_metrics_subscriber'
+require 'nexus_semantic_logger/traced_shell'
 
 module NexusSemanticLogger
   # Get application wide object for sending metrics.
   def self.metrics
     DatadogSingleton.instance
   end
+
+  # Get application wide object for running instrumented shell commands.
+  def self.shell
+    @shell ||= TracedShell.new
+  end
 end
 
 # Patch access to LEVELS array.

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nexus_semantic_logger
 version: !ruby/object:Gem::Version
-  version: 1.14.1
+  version: 1.15.0
 platform: ruby
 authors:
 - Johnathon Harris
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: amazing_print
@@ -107,16 +108,22 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 4.16.1
+description:
 email: john.harris@nexusmods.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".gitignore"
-- ".gitlab-ci.yml"
+- ".rspec"
 - ".rubocop.yml"
+- Appraisals
 - Gemfile
 - README.md
+- gemfiles/rails_7_1.gemfile
+- gemfiles/rails_7_2.gemfile
+- gemfiles/rails_8_0.gemfile
 - lib/nexus_semantic_logger.rb
 - lib/nexus_semantic_logger/appender_filter.rb
 - lib/nexus_semantic_logger/application.rb
@@ -126,12 +133,15 @@ files:
 - lib/nexus_semantic_logger/extensions/action_dispatch/debug_exceptions.rb
 - lib/nexus_semantic_logger/logger_metrics_subscriber.rb
 - lib/nexus_semantic_logger/sneakers_metrics.rb
+- lib/nexus_semantic_logger/traced_shell.rb
 - lib/nexus_semantic_logger/version.rb
 - lib/puma/plugin/README.md
 - lib/puma/plugin/nexus_puma_statsd.rb
 - nexus_semantic_logger.gemspec
+homepage:
 licenses: []
 metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -146,7 +156,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.4.10
+signing_key:
 specification_version: 4
 summary: semantic_logger usage for nexus
 test_files: []

data/.gitlab-ci.yml

@@ -1,36 +0,0 @@
-image: "ruby:3.2.2"
-
-stages:
-  - release
-  - test
-
-before_script:
-  - gem install bundler --no-document
-  - bundle install --jobs $(nproc)  "${FLAGS[@]}"
-
-rspec:
-  script:
-    - bundle exec rspec
-
-rubocop:
-  script:
-    - bundle exec rubocop
-
-release:
-  stage: release
-  rules:
-    - if: '$CI_COMMIT_TAG'
-  script:
-    - mkdir -p ~/.gem
-    - cp $RUBYGEMS_CREDENTIALS ~/.gem/credentials
-    - chmod 0600 ~/.gem/credentials
-    - gem update --system
-    - ruby --version
-    - gem env version
-    - sed -i "s/0.0.0/$CI_COMMIT_TAG/g" lib/nexus_semantic_logger/version.rb
-    - gem build nexus_semantic_logger.gemspec
-    - gem push nexus_semantic_logger*.gem
-  artifacts:
-    paths:
-      - nexus_semantic_logger*.gem
-    expire_in: 30 days