nexus_semantic_logger 1.14.2 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f3b89f4f80f8f27b69fa3acdf26a8ee5bedd3879fdcae28e18c43c9a6150b55
-  data.tar.gz: 4778cc57aa7c007c324d53b665f7bea976fc9ac8ab31767e69d96df4d36eee37
+  metadata.gz: 0dcbcb0a7a4c7de68e7496b8ffb7f6d5d5e08742a981af559e48162bd149fc40
+  data.tar.gz: 4cd8249c19ce91fc5a3f2ef7c1919f91685235cf385291f8e0272ecfaf71234f
 SHA512:
-  metadata.gz: da93370c79b39887353e2397ee5c9919d554f9e9a51d3c66673020f75e15d437231b807bfcfd60662751f87e77888427eb51a78b8df9253fdc40b191ac37aa9e
-  data.tar.gz: 6bcc8e29ca2f7907c3d27ec4941bc98e86b03948fbc665bc640505e528317b82d96e9501765e9d915f943b3d9b48d8a565f791e11eb52f1e2c3d00cfd7cd1211
+  metadata.gz: 17a71300ae2d6f1bd8c5d0175b167071b818c54ea489d5973a6a2d92cc2fa99dd8f8369015b57520ae8eaf2dfef84f17b30e28c12736637c1620d48ec435d28c
+  data.tar.gz: f93a642bc2e30c4913f65cab35cbda108a99d9b15f78fab5f715aa91d53511560d9a2189bd10d02782a90c9b810add8efec1509278bb6108fd4a1ee0b9258416

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/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/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.2 in order for CI process to replace with the tagged version.
-  VERSION = '1.14.2'
+  # 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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nexus_semantic_logger
 version: !ruby/object:Gem::Version
-  version: 1.14.2
+  version: 1.15.0
 platform: ruby
 authors:
 - Johnathon Harris
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 2026-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: amazing_print
@@ -133,6 +133,7 @@ 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