openc3 7.4.1 → 7.5.1

data/lib/openc3/utilities/cli_generator.rb

@@ -11,6 +11,8 @@
 # This file may also be used under the terms of a commercial license
 # if purchased from OpenC3, Inc.
 
+require 'open3'
+
 module OpenC3
   class CliGenerator
     GENERATORS = %w(plugin target microservice widget conversion processor limits_response tool tool_vue tool_angular tool_react tool_svelte command_validator)
@@ -392,9 +394,26 @@ module OpenC3
       end
       FileUtils.mkdir(plugin_name)
       Dir.chdir(plugin_name) # Change to the plugin path to make copying easier
+      # Every installed plugin's lib/ goes on sys.path, so python code shared
+      # across the plugin lives in a package named after the plugin rather than
+      # directly in lib/, where a same-named module in another plugin collides.
+      package_name = plugin_name.gsub(/[^a-z0-9]+/, '_')
 
       process_template("#{TEMPLATES_DIR}/plugin", binding) do |filename|
         filename.sub!("plugin.gemspec", "#{plugin_name}.gemspec")
+        filename.sub!("lib/PACKAGE", "lib/#{package_name}")
+        # Only python plugins get a pyproject.toml. Shipping one in every plugin
+        # would make install_phase2 take the python dependency path (and build a
+        # per-plugin venv) for plugins that have no python code at all.
+        #
+        # lib/ comes with it because pyproject.toml sets ty's extra-paths to
+        # lib/, and ty exits non-zero rather than warning when a configured path
+        # does not exist. The package's __init__.py does reach the gem, which is
+        # harmless: the gem's pyproject.toml already sets needs_dependencies.
+        if @@language != 'py'
+          next true if filename == 'pyproject.toml'
+          next true if filename == 'lib' or filename.start_with?('lib/')
+        end
         false
       end
 
@@ -409,10 +428,28 @@ module OpenC3
         end
       end
 
+      write_python_version if @@language == 'py'
+
       puts "Plugin #{plugin_name} successfully generated!"
       return plugin_name
     end
 
+    # Pin the plugin's local uv environment to the Python minor version COSMOS
+    # runs, read from the interpreter itself rather than hardcoded in the
+    # template: it differs between images (Debian vs UBI) and moves with the base
+    # image. `cli generate` runs in the cmd-tlm-api image, which sets
+    # OPENC3_PYTHON_BIN. Outside an image (e.g. the gem installed on a dev
+    # machine) there is no COSMOS Python to match, so no file is written.
+    def self.write_python_version
+      python_bin = ENV.fetch('OPENC3_PYTHON_BIN', nil)
+      return if python_bin.nil? || !File.executable?(python_bin)
+      version, status = Open3.capture2(python_bin, '-c', 'import sys; print("%d.%d" % sys.version_info[:2])')
+      return unless status.success? && version.strip =~ /\A\d+\.\d+\z/
+      File.write('.python-version', "#{version.strip}\n")
+    rescue SystemCallError
+      nil
+    end
+
     def self.generate_target(args)
       validate_language_inheriting_args!('target', args,
         example: ['cli generate target EXAMPLE --ruby', 'Creates: targets/EXAMPLE/'],
@@ -447,18 +484,33 @@ module OpenC3
         end
         gemspec_filename = Dir['*.gemspec'][0]
         gemspec = File.read(gemspec_filename)
-        gemspec.gsub!(/s\.files = Dir\.glob.*\n/) do |match|
-          <<RUBY
-# Prefer pyproject.toml over requirements.txt
-  python_dep_file = if File.exist?('pyproject.toml')
-    'pyproject.toml'
-  else
-    'requirements.txt'
-  end
-  s.files = Dir.glob("{targets,lib,public,tools,microservices}/**/*") + %w(Rakefile README.md LICENSE.md plugin.txt) + [python_dep_file]
-RUBY
+        # Older COSMOS versions wrote a singular python_dep_file block that never
+        # ships uv.lock, and a second python target nested another copy of it.
+        # Strip every copy plus its use on the s.files line so the rewrite below
+        # replaces it. A hand-edited block that no longer matches leaves some
+        # python_dep_file reference behind, so the gemspec is kept as it was.
+        legacy_block = /^ *# Prefer pyproject\.toml over requirements\.txt\n *python_dep_file = if File\.exist\?\('pyproject\.toml'\)\n *'pyproject\.toml'\n *else\n *'requirements\.txt'\n *end\n/
+        upgraded = gemspec.gsub(legacy_block, '').sub(' + [python_dep_file]', '')
+        gemspec = upgraded unless upgraded.include?('python_dep_file')
+        # Skip when a previous python target already rewrote s.files: the line it
+        # wrote matches the pattern below too, so rewriting again would nest a
+        # second dependency block. python_dep_file also covers a legacy block
+        # the upgrade above left alone. Also skip a gemspec from the
+        # python plugin template, which already ships pyproject.toml and uv.lock.
+        unless gemspec.include?('python_dep_file') || gemspec.include?('pyproject.toml')
+          gemspec.gsub!(/^ *s\.files = Dir\.glob.*\n/) do
+            <<~RUBY.gsub(/^/, '  ')
+              # Prefer pyproject.toml (plus uv.lock if committed) over requirements.txt
+              python_dep_files = if File.exist?('pyproject.toml')
+                ['pyproject.toml'] + Dir.glob('uv.lock')
+              else
+                ['requirements.txt']
+              end
+              s.files = Dir.glob("{targets,lib,public,tools,microservices}/**/*") + %w(Rakefile README.md LICENSE.md plugin.txt) + python_dep_files
+            RUBY
+          end
+          File.write(gemspec_filename, gemspec)
         end
-        File.write(gemspec_filename, gemspec)
 
         target_txt_filename = "targets/#{target_name}/target.txt"
         target_txt = File.read(target_txt_filename)
@@ -626,8 +678,8 @@ RUBY
             arguments: common_args,
             notes: common_note,
             example: [
-              "cli generate #{args[0]} 'Data Viewer'",
-              "Creates: tools/dataviewer/ (#{framework}-based)",
+              "cli generate #{args[0]} 'Mission Planner'",
+              "Creates: tools/missionplanner/ (#{framework}-based)",
             ],
             in_plugin_extra: 'For other tool types, see: cli generate tool --help',
             docs: docs_url,
@@ -650,8 +702,8 @@ RUBY
               ],
             },
             example: [
-              "cli generate tool 'Data Viewer'",
-              'Creates: tools/dataviewer/',
+              "cli generate tool 'Mission Planner'",
+              'Creates: tools/missionplanner/',
             ],
             docs: docs_url,
             exit_code: (args[1].nil? ? 1 : 0),

data/lib/openc3/utilities/config_overlay.rb

@@ -15,24 +15,27 @@ module OpenC3
   # Shared predicates describing which parts of the user-writable config overlay
   # (targets_modified) a non-admin may write.
   #
-  # The cmd_tlm overlay (targets_modified/<TARGET>/cmd_tlm/...) is loaded by
-  # System.setup_targets and processed by PacketConfig, which evaluates
-  # GENERIC_READ_CONVERSION / GENERIC_WRITE_CONVERSION blocks as code in the
-  # decom microservices. Writing it is therefore an admin operation, matching the
-  # tier COSMOS requires everywhere else code is introduced (plugin install).
-  # Only the server-side dynamic-packet mechanism (TargetModel#dynamic_update)
-  # writes that area without going through an API request.
+  # Two target subdirectories hold definitions whose GENERIC_READ_CONVERSION /
+  # GENERIC_WRITE_CONVERSION blocks are evaluated as code:
+  #   - <TARGET>/cmd_tlm/...: loaded by System.setup_targets and processed by
+  #     PacketConfig in the decom microservices. Only the server-side
+  #     dynamic-packet mechanism (TargetModel#dynamic_update) writes that area
+  #     without going through an API request.
+  #   - <TARGET>/tables/config/...: table definitions, processed by TableConfig
+  #     in cmd-tlm-api for every Table Manager operation.
+  # Writing either is therefore an admin operation, matching the tier COSMOS
+  # requires everywhere else code is introduced (plugin install).
   #
   # Every API writer that can reach the overlay must consult these predicates:
   #   - storage_controller#get_upload_presigned_request / delete (presigned S3 upload)
-  #   - tables_controller#save / save_as / generate / destroy (Table -> TargetFile)
+  #   - tables_controller#save / save_as / report / destroy (Table -> TargetFile)
   #   - scripts_controller#create / destroy (Script -> TargetFile)
   module ConfigOverlay
     # Config bucket areas a non-admin is allowed to write at all
     NON_ADMIN_AREAS = ['targets_modified', 'tmp'].freeze
 
-    # Target subdirectory whose contents are executed as code
-    CODE_AREA = 'cmd_tlm'
+    # Target subdirectories whose contents are executed as code
+    CODE_AREAS = [['cmd_tlm'], ['tables', 'config']].freeze
 
     # Split a path into segments, or nil if the path is not canonical.
     #
@@ -48,14 +51,23 @@ module OpenC3
       parts
     end
 
-    # True if the overlay-relative name targets the cmd_tlm subtree, i.e. writing
-    # it requires admin. Name is relative to targets_modified/, e.g.
-    # "<TARGET>/cmd_tlm/tlm.txt". Fails closed (true) on non-canonical names.
-    def self.cmd_tlm_overlay?(name)
+    # True if the overlay-relative name targets a code area (cmd_tlm or
+    # tables/config), i.e. writing it requires admin. Name is relative to
+    # targets_modified/, e.g. "<TARGET>/cmd_tlm/tlm.txt". Fails closed (true)
+    # on non-canonical names.
+    def self.code_overlay?(name)
       parts = canonical_parts(name)
       return true if parts.nil?
-      # parts: <TARGET> / <area> / ...
-      parts[1] == CODE_AREA
+      code_area?(parts)
+    end
+
+    # True if the target-relative name is a canonical table definition path,
+    # e.g. "<TARGET>/tables/config/table_def.txt". Table only parses definitions
+    # from here, so a definition can't be pointed at a non-admin overlay area.
+    def self.table_definition?(name)
+      parts = canonical_parts(name)
+      return false if parts.nil?
+      parts.length > 3 and parts[1, 2] == ['tables', 'config']
     end
 
     # True if the given config bucket key is an overlay path a non-admin may
@@ -68,8 +80,14 @@ module OpenC3
       # parts: <SCOPE> / <area> / <TARGET> / <subdir> / ...
       area = parts[1]
       return false unless NON_ADMIN_AREAS.include?(area)
-      return false if area == 'targets_modified' && parts[3] == CODE_AREA
+      return false if area == 'targets_modified' && code_area?(parts[2..])
       true
     end
+
+    # target_parts: <TARGET> / <subdir> / ...
+    def self.code_area?(target_parts)
+      CODE_AREAS.any? { |area| target_parts[1, area.length] == area }
+    end
+    private_class_method :code_area?
   end
 end

data/lib/openc3/utilities/default_plugins.rb

@@ -0,0 +1,33 @@
+# encoding: ascii-8bit
+
+# Copyright 2026 OpenC3, Inc.
+# All Rights Reserved.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE.md for more details.
+#
+# This file may also be used under the terms of a commercial license
+# if purchased from OpenC3, Inc.
+
+require 'yaml'
+
+module OpenC3
+  # The plugins that ship with COSMOS. The list lives in
+  # data/config/default_plugins.yaml and is shared with the Admin Plugins tab
+  # and the script API via the 'default' flag from GET /openc3-api/plugins/all
+  module DefaultPlugins
+    # Short names, i.e. without the version or the __ suffix
+    NAMES = YAML.safe_load_file(
+      File.expand_path('../../../data/config/default_plugins.yaml', __dir__)
+    ).freeze
+
+    # True if the plugin (e.g. "openc3-cosmos-tool-admin-6.0.0.gem__20260101000000")
+    # is one that ships with COSMOS
+    def self.default?(plugin_name)
+      # Strip the __ suffix and the trailing -version.gem to get the short name
+      NAMES.include?(plugin_name.split('__')[0].split('-')[0..-2].join('-'))
+    end
+  end
+end

data/lib/openc3/utilities/local_mode.rb

@@ -17,39 +17,11 @@ require 'openc3/core_ext/file'
 # require 'openc3/models/gem_model' # These are used but also create circular dependency
 # require 'openc3/models/plugin_model' # These are used but also create circular dependency
 require 'openc3/utilities/bucket'
+require 'openc3/utilities/default_plugins'
 
 module OpenC3
   module LocalMode
     OPENC3_LOCAL_MODE_PATH = ENV['OPENC3_LOCAL_MODE_PATH'] || "/plugins"
-    # When updating update local_mode.py, PluginsTab.vue, plugins.p.spec.ts
-    DEFAULT_PLUGINS = [
-      'openc3-cosmos-tool-admin',
-      'openc3-cosmos-tool-bucketexplorer',
-      'openc3-cosmos-tool-cmdsender',
-      'openc3-cosmos-tool-cmdqueue', # Enterprise only
-      'openc3-cosmos-tool-cmdhistory', # Enterprise only
-      'openc3-cosmos-tool-cmdtlmserver',
-      'openc3-cosmos-tool-dataextractor',
-      'openc3-cosmos-tool-dataviewer',
-      'openc3-cosmos-tool-docs',
-      'openc3-cosmos-tool-handbooks',
-      'openc3-cosmos-tool-iframe',
-      'openc3-cosmos-tool-limitsmonitor',
-      'openc3-cosmos-tool-packetviewer',
-      'openc3-cosmos-tool-scriptrunner',
-      'openc3-cosmos-tool-tablemanager',
-      'openc3-cosmos-tool-tlmgrapher',
-      'openc3-cosmos-tool-tlmviewer',
-      'openc3-cosmos-enterprise-tool-admin', # Enterprise only
-      'openc3-cosmos-tool-autonomic', # Enterprise only
-      'openc3-cosmos-tool-calendar', # Enterprise only
-      'openc3-cosmos-tool-grafana', # Enterprise only
-      'openc3-cosmos-tool-logexplorer', # Enterprise only
-      'openc3-cosmos-tool-notebooks', # Enterprise only
-      'openc3-cosmos-tool-systemhealth', # Enterprise only
-      'openc3-enterprise-tool-base', # Enterprise only
-      'openc3-tool-base',
-    ]
 
     # Install plugins from local plugins folder
     # Can only be used from openc3cli because calls top_level load_plugin
@@ -280,7 +252,7 @@ module OpenC3
     end
 
     def self.update_local_plugin_files(full_folder_path, plugin_file_path, plugin_hash, gem_name)
-      return if DEFAULT_PLUGINS.include?(gem_name)
+      return if DefaultPlugins::NAMES.include?(gem_name)
       puts "Updating local plugin files: #{full_folder_path}"
       FileUtils.mkdir_p(full_folder_path)
       gems = scan_plugin_dir(full_folder_path).first
@@ -378,8 +350,8 @@ module OpenC3
     end
 
     def self.put_target_file(path, io_or_string, scope:) # NOSONAR - scope: is part of the caller-facing signature
-      full_folder_path = "#{OPENC3_LOCAL_MODE_PATH}/#{path}"
-      return unless File.expand_path(full_folder_path).start_with?(OPENC3_LOCAL_MODE_PATH)
+      full_folder_path = key_path(path)
+      return unless full_folder_path and path.start_with?("#{scope}/")
       FileUtils.mkdir_p(File.dirname(full_folder_path))
       File.open(full_folder_path, 'wb') do |file|
         if String === io_or_string
@@ -392,8 +364,8 @@ module OpenC3
     end
 
     def self.open_local_file(path, scope:)
-      full_path = "#{OPENC3_LOCAL_MODE_PATH}/#{scope}/targets_modified/#{path}"
-      if File.expand_path(full_path).start_with?(OPENC3_LOCAL_MODE_PATH)
+      full_path = scope_path(scope, "targets_modified/#{path}")
+      if full_path and safe_key?(path)
         return File.open(full_path, 'rb')
       end
       nil
@@ -452,8 +424,8 @@ module OpenC3
     def self.save_tool_config(scope, tool, name, data)
       return unless ENV['OPENC3_LOCAL_MODE'] and Dir.exist?(OPENC3_LOCAL_MODE_PATH)
       json = JSON.parse(data, allow_nan: true, create_additions: true)
-      config_path = "#{OPENC3_LOCAL_MODE_PATH}/#{scope}/tool_config/#{tool}/#{name}.json"
-      return unless File.expand_path(config_path).start_with?(OPENC3_LOCAL_MODE_PATH)
+      config_path = scope_path(scope, "tool_config/#{tool}/#{name}.json")
+      return unless config_path and safe_key?("#{tool}/#{name}")
       FileUtils.mkdir_p(File.dirname(config_path))
       File.open(config_path, 'w') do |file|
         file.write(JSON.pretty_generate(json, allow_nan: true))
@@ -462,8 +434,8 @@ module OpenC3
 
     def self.delete_tool_config(scope, tool, name)
       return unless ENV['OPENC3_LOCAL_MODE'] and Dir.exist?(OPENC3_LOCAL_MODE_PATH)
-      config_path = "#{OPENC3_LOCAL_MODE_PATH}/#{scope}/tool_config/#{tool}/#{name}.json"
-      return unless File.expand_path(config_path).start_with?(OPENC3_LOCAL_MODE_PATH)
+      config_path = scope_path(scope, "tool_config/#{tool}/#{name}.json")
+      return unless config_path and safe_key?("#{tool}/#{name}")
       FileUtils.rm_f(config_path)
     end
 
@@ -508,8 +480,8 @@ module OpenC3
 
     def self.save_setting(scope, name, data)
       return unless ENV['OPENC3_LOCAL_MODE'] and Dir.exist?(OPENC3_LOCAL_MODE_PATH)
-      config_path = "#{OPENC3_LOCAL_MODE_PATH}/#{scope}/settings/#{name}.json"
-      return unless File.expand_path(config_path).start_with?(OPENC3_LOCAL_MODE_PATH)
+      config_path = scope_path(scope, "settings/#{name}.json")
+      return unless config_path and safe_key?(name)
       FileUtils.mkdir_p(File.dirname(config_path))
       # Anything can be stored as a setting. Strings are written directly since
       # they're already the serialized form. Anything else is written as JSON so
@@ -518,26 +490,86 @@ module OpenC3
       File.write(config_path, data)
     end
 
+    # Target names from OPENC3_LOCAL_ONLY_TARGETS (comma separated). These
+    # targets keep their target files only in the local mode volume and never
+    # read or write them in the bucket. Read on every call so it can't go stale.
+    def self.local_only_targets
+      ENV['OPENC3_LOCAL_ONLY_TARGETS'].to_s.split(',').map { |name| name.strip.upcase }.reject(&:empty?)
+    end
+
+    def self.local_only_target?(target_name)
+      return false if target_name.nil? or target_name.to_s.empty?
+      local_only_targets.include?(target_name.to_s.upcase)
+    end
+
+    # name is relative to targets / targets_modified, e.g. "INST/procedures/test.rb"
+    def self.local_only_name?(name)
+      local_only_target?(name.to_s.split('/')[0])
+    end
+
+    # key is a config bucket key, e.g. "DEFAULT/targets_modified/INST/procedures/test.rb"
+    def self.local_only_key?(key)
+      split_key = key.to_s.split('/')
+      return false unless ['targets', 'targets_modified'].include?(split_key[1])
+      local_only_target?(split_key[2])
+    end
+
     # Helper methods
 
+    # True if the key has no '.' / '..' segments, no empty segments, no leading
+    # slash and no backslash. Such a key always resolves under its first
+    # segment (the scope), both on disk and in the bucket (the bucket
+    # normalizes '..' segments, so a traversal key reaches other scopes there too).
+    def self.safe_key?(key)
+      return false unless String === key
+      return false if key.empty? or key.start_with?('/') or key.include?('\\') or key.include?("\0")
+      key.split('/', -1).none? { |segment| segment.empty? or segment == '.' or segment == '..' }
+    end
+
+    # True if path resolves to root or somewhere beneath it. Compares against
+    # root plus a separator so a sibling such as /plugins_old never matches.
+    def self.path_within?(path, root)
+      expanded = File.expand_path(path)
+      root = File.expand_path(root)
+      expanded == root or expanded.start_with?(root + File::SEPARATOR)
+    end
+
+    # Local file path for a scope relative path, or nil if the path would
+    # leave the scope directory
+    def self.scope_path(scope, relative_path)
+      return nil unless safe_key?(scope) and !scope.include?('/')
+      scope_root = "#{OPENC3_LOCAL_MODE_PATH}/#{scope}"
+      full_path = "#{scope_root}/#{relative_path}"
+      return nil unless path_within?(full_path, scope_root)
+      full_path
+    end
+
+    # Local file path for a bucket key, or nil if the key is not a safe key
+    def self.key_path(key)
+      return nil unless safe_key?(key)
+      full_path = "#{OPENC3_LOCAL_MODE_PATH}/#{key}"
+      return nil unless path_within?(full_path, OPENC3_LOCAL_MODE_PATH)
+      full_path
+    end
+
     def self.sync_remote_to_local(bucket, key)
-      local_path = "#{OPENC3_LOCAL_MODE_PATH}/#{key}"
-      return unless File.expand_path(local_path).start_with?(OPENC3_LOCAL_MODE_PATH)
+      local_path = key_path(key)
+      return unless local_path
       FileUtils.mkdir_p(File.dirname(local_path))
       bucket.get_object(bucket: ENV['OPENC3_CONFIG_BUCKET'], key: key, path: local_path)
     end
 
     def self.sync_local_to_remote(bucket, key)
-      local_path = "#{OPENC3_LOCAL_MODE_PATH}/#{key}"
-      return unless File.expand_path(local_path).start_with?(OPENC3_LOCAL_MODE_PATH)
+      local_path = key_path(key)
+      return unless local_path
       File.open(local_path, 'rb') do |read_file|
         bucket.put_object(bucket: ENV['OPENC3_CONFIG_BUCKET'], key: key, body: read_file)
       end
     end
 
     def self.delete_local(key)
-      local_path = "#{OPENC3_LOCAL_MODE_PATH}/#{key}"
-      return unless File.expand_path(local_path).start_with?(OPENC3_LOCAL_MODE_PATH)
+      local_path = key_path(key)
+      return unless local_path
       File.delete(local_path) if File.exist?(local_path)
       nil
     end
@@ -580,6 +612,10 @@ module OpenC3
       # Build catalogs
       local_catalog = build_local_catalog(scope: scope)
       remote_catalog = build_remote_catalog(bucket, scope: scope)
+      # Local only targets never sync in either direction. Any stale copies
+      # already in the bucket are left alone rather than pulled down or deleted.
+      local_catalog.reject! { |key, _size| local_only_key?(key) }
+      remote_catalog.reject! { |key, _size| local_only_key?(key) }
 
       # Find and Handle Differences
       local_catalog.each do |key, size|

data/lib/openc3/utilities/metric.rb

@@ -133,7 +133,23 @@ module OpenC3
     def graceful_kill
     end
 
+    # Environment variable the operator sets on every microservice it spawns to
+    # say "I am already reporting process metrics for you". Without it an
+    # in-process generator and the operator would both be writing cpu/memory for
+    # the same microservice.
+    SUPERVISED_ENV_VAR = 'OPENC3_OPERATOR_PROCESS_METRICS'.freeze
+
+    # Whether something outside this process is already reporting its process
+    # level metrics.
+    def self.supervised?
+      !ENV[SUPERVISED_ENV_VAR].nil?
+    end
+
     def self.add_update_generator(object)
+      # Generators produce process level metrics (cpu, memory). Skip them
+      # entirely when the operator is already reporting those for us.
+      return if supervised?
+
       @@update_generators << object
     end
   end

data/lib/openc3/utilities/process_stats.rb

@@ -0,0 +1,160 @@
+# encoding: ascii-8bit
+
+# Copyright 2026 OpenC3, Inc.
+# All Rights Reserved.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE.md for more details.
+#
+# This file may also be used under the terms of a commercial license
+# if purchased from OpenC3, Inc.
+
+require 'etc'
+
+# See: https://man7.org/linux/man-pages/man5/proc.5.html
+
+module OpenC3
+  # Samples CPU and memory for an arbitrary pid out of /proc/<pid>/stat.
+  #
+  # Every microservice is bootstrapped by plugin_microservice.rb, which exec()s
+  # the configured cmd. exec replaces the process image, so everything the
+  # bootstrap set up - including the Metric update thread - is gone. A
+  # microservice whose cmd is itself an OpenC3::Microservice builds a new Metric
+  # and keeps reporting, but a plugin that runs a Rails app, a Python script or
+  # any other binary never loads the OpenC3 libraries and so can never report on
+  # itself. Sampling by pid lets the operator report on behalf of those
+  # processes without requiring anything of the plugin.
+  class ProcessStats
+    # /proc/<pid>/stat field offsets, 0 based, after the comm field has been
+    # collapsed to a single token. proc(5) numbers these fields from 1.
+    UTIME_INDEX = 13
+    STIME_INDEX = 14
+    NUM_THREADS_INDEX = 19
+    STARTTIME_INDEX = 21
+    VSIZE_INDEX = 22
+    RSS_INDEX = 23
+
+    # Near universal Linux default. Only used if sysconf can't answer - a zero
+    # here would turn every CPU number into Infinity or NaN.
+    DEFAULT_USER_HZ = 100.0
+    DEFAULT_PAGESIZE = 4096
+
+    attr_reader :pid
+
+    class << self
+      # Whether this kernel exposes the procfs data we need at all. macOS and
+      # Windows don't, and neither do some hardened container runtimes.
+      def supported?
+        return @supported unless @supported.nil?
+        @supported = File.exist?('/proc/self/stat')
+      rescue Exception
+        @supported = false
+      end
+
+      def pagesize
+        @pagesize ||= sysconf(:SC_PAGESIZE, DEFAULT_PAGESIZE)
+      end
+
+      def user_hz
+        @user_hz ||= sysconf(:SC_CLK_TCK, DEFAULT_USER_HZ).to_f
+      end
+
+      # Wall time the machine booted. /proc/<pid>/stat reports starttime
+      # relative to boot, so this is what turns it into an absolute time.
+      def boot_time
+        @boot_time ||= begin
+          Time.now - File.read('/proc/uptime').split[0].to_f
+        rescue Exception
+          Time.now
+        end
+      end
+
+      private
+
+      def sysconf(name, default)
+        return default unless Etc.const_defined?(name)
+
+        value = Etc.sysconf(Etc.const_get(name))
+        (value and value > 0) ? value : default
+      rescue Exception
+        default
+      end
+    end
+
+    def initialize(pid)
+      @pid = pid
+      @start_time = nil
+      @last_sample_time = nil
+      # nil rather than 0 so a process that has genuinely burned no CPU yet
+      # still starts producing sample deltas on the next pass
+      @cpu_time = nil
+      @average_cpu_utilization = 0.0
+      @sample_cpu_utilization = 0.0
+      @virtual_memory_bytes = 0.0
+      @resident_memory_bytes = 0.0
+      @num_threads = 0
+    end
+
+    # @return [Boolean] whether a usable sample was taken
+    def sample
+      stat = read_stat()
+      return false unless stat
+
+      fields = split_stat(stat)
+      return false if fields.length <= RSS_INDEX
+
+      sample_time = Time.now
+      user_hz = self.class.user_hz
+      cpu_time = (fields[UTIME_INDEX].to_f + fields[STIME_INDEX].to_f) / user_hz
+      @start_time ||= self.class.boot_time + (fields[STARTTIME_INDEX].to_f / user_hz)
+
+      if @cpu_time and @last_sample_time
+        time_delta = sample_time - @last_sample_time
+        @sample_cpu_utilization = (cpu_time - @cpu_time) / time_delta if time_delta > 0
+      end
+      @cpu_time = cpu_time
+      @last_sample_time = sample_time
+
+      elapsed = sample_time - @start_time
+      @average_cpu_utilization = cpu_time / elapsed if elapsed > 0
+
+      @num_threads = fields[NUM_THREADS_INDEX].to_i
+      @virtual_memory_bytes = fields[VSIZE_INDEX].to_f
+      @resident_memory_bytes = fields[RSS_INDEX].to_f * self.class.pagesize
+      true
+    end
+
+    # Shaped like OpenC3::Metric's internal data hash so it can be handed
+    # straight to MetricModel.
+    def values
+      {
+        'average_cpu_utilization' => { 'value' => @average_cpu_utilization, 'type' => 'gauge', 'unit' => 'ratio' },
+        'sample_cpu_utilization' => { 'value' => @sample_cpu_utilization, 'type' => 'gauge', 'unit' => 'ratio' },
+        'virtual_memory_bytes' => { 'value' => @virtual_memory_bytes, 'type' => 'gauge', 'unit' => 'bytes' },
+        'resident_memory_bytes' => { 'value' => @resident_memory_bytes, 'type' => 'gauge', 'unit' => 'bytes' },
+        'num_threads' => { 'value' => @num_threads, 'type' => 'gauge' },
+      }
+    end
+
+    private
+
+    def read_stat
+      File.read("/proc/#{@pid}/stat")
+    rescue SystemCallError, IOError
+      # The process can exit between being listed and being read
+      nil
+    end
+
+    # The comm field is wrapped in parens and may itself contain spaces and
+    # parens, so split from the last close paren rather than trying to match it.
+    # Two placeholders stand in for pid and comm to keep the proc(5) offsets.
+    def split_stat(stat)
+      close = stat.rindex(')')
+      return [] unless close
+
+      ['0', '0'].concat(stat[(close + 1)..-1].to_s.split)
+    end
+  end
+end