vivarium 0.5.2 → 0.6.0

data/lib/vivarium/api_server.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "fiddle"
+require "securerandom"
 require "socket"
 
 module Vivarium
@@ -43,21 +45,44 @@ module Vivarium
 
   # Wraps the daemon's live BPF target maps so the API can (un)register PIDs.
   class Registry
-    def initialize(config_root_targets, config_spawned_targets)
+    # struct otel_ctx_t { trace_id{u64 hi; u64 lo}; u64 span_id; u64 parent_span_id; }
+    OTEL_CTX_PACK_FMT = "Q<Q<Q<Q<"
+
+    def initialize(config_root_targets, config_spawned_targets, otel_ctx = nil)
       @config_root_targets = config_root_targets
       @config_spawned_targets = config_spawned_targets
+      @otel_ctx = otel_ctx
     end
 
+    # Registering a root target marks the start of a trace: issue a fresh
+    # 128-bit trace_id and a root span_id (no parent) into the otel_ctx map,
+    # keyed by the root pid (== the main thread's tid).
     def register(pid)
       @config_root_targets[pid] = 1
+      return unless @otel_ctx
+
+      hi = SecureRandom.random_number(1 << 64)
+      lo = SecureRandom.random_number(1 << 64)
+      span = SecureRandom.random_number(1 << 64)
+      write_otel_ctx(pid, hi, lo, span, 0)
     end
 
     def unregister(pid)
       @config_root_targets.delete(pid)
       @config_spawned_targets.clear
+      @otel_ctx&.clear
     rescue KeyError
       nil
     end
+
+    private
+
+    def write_otel_ctx(tid, trace_hi, trace_lo, span_id, parent_span_id)
+      size = @otel_ctx.leafsize
+      ptr = Fiddle::Pointer.malloc(size)
+      ptr[0, size] = [trace_hi, trace_lo, span_id, parent_span_id].pack(OTEL_CTX_PACK_FMT)
+      @otel_ctx[tid] = ptr
+    end
   end
 
   # Minimal HTTP/1.1 server over a Unix domain socket exposing the daemon control API.

data/lib/vivarium/cli.rb

@@ -18,18 +18,36 @@ module Vivarium
         opts.on("--socket PATH", "vivariumd Unix domain socket path") { |v| options[:socket_path] = v }
         opts.on("-o", "--output PATH", "Log output file (default: stdout)") { |v| options[:dest] = File.open(v, "a") }
         opts.on("--save-raw PATH", "load: save raw events to PATH instead of rendering") { |v| options[:save_raw] = v }
-        opts.on("--all", "report: show all events (ignore default filter)") { options[:show_all] = true }
+        opts.on("--otel-out PATH", "load: write OTLP/JSON spans to PATH instead of rendering") { |v| options[:otel_out] = v }
+        opts.on("--otel-endpoint URL", "load: stream OTLP/JSON spans to an OTLP/HTTP collector (or OTEL_EXPORTER_OTLP_ENDPOINT)") do |v|
+          options[:otel_endpoint] = v
+        end
+        opts.on("-a", "--all", "report: show all events (ignore default filter)") { options[:show_all] = true }
         opts.on("--filter JSON", "report: filter as a JSON object (overrides --event/default)") { |v| options[:filter_json] = v }
-        opts.on("--event NAMES", "report: comma-separated event names to include") do |v|
+        opts.on("-e", "--event NAMES", "report: comma-separated event names to include") do |v|
           options[:event_names] = v.split(",").map(&:strip).reject(&:empty?)
         end
-        opts.on("--max-span-depth N", Integer, "report: collapse method spans deeper than N (events kept)") do |v|
+        opts.on("-d", "--max-span-depth N", Integer, "report: collapse method spans deeper than N (events kept)") do |v|
           options[:max_span_depth] = v
         end
+        opts.on("-u", "--dedup-values", "load/report: show repeated path_open/mmap_exec/dlopen/env_caccess values only once") do
+          options[:dedup_values] = true
+        end
+        opts.on("--dump-otel", "report: dump per-event otel fields (trace/span/uid/gid/comm) instead of the tree") do
+          options[:dump_otel] = true
+        end
+      end
+      # order! stops at the first non-option (the subcommand), so parse once to
+      # collect options before the command, then again to collect options placed
+      # after it (e.g. `vivarium report --dedup-values FILE`).
+      begin
+        parser.order!(argv)
+        command = argv.shift
+        parser.order!(argv) if command
+      rescue OptionParser::ParseError => e
+        abort "#{e.message}\n\n#{parser.help}"
       end
-      parser.order!(argv)
 
-      command = argv.shift
       case command
       when "load"
         run_load!(argv, options)
@@ -45,8 +63,19 @@ module Vivarium
       abort "Usage: vivarium load <script>" unless script
       abort "File not found: #{script}" unless File.exist?(script)
 
+      filter = Vivarium::DEFAULT_FILTER
+      filter = filter.merge(dedup_values: true) if options[:dedup_values]
+
+      endpoint = options[:otel_endpoint] || ENV["OTEL_EXPORTER_OTLP_ENDPOINT"]
+      otel_out = options[:otel_out]
+      if endpoint && otel_out
+        warn "[vivarium] --otel-endpoint takes precedence; ignoring --otel-out"
+        otel_out = nil
+      end
+
       Vivarium.observe(socket_path: options[:socket_path], dest: options[:dest],
-                       filter: Vivarium::DEFAULT_FILTER, save_raw: options[:save_raw]) do
+                       filter: filter, save_raw: options[:save_raw],
+                       otel_out: otel_out, otel_endpoint: endpoint) do
         Kernel.load(File.expand_path(script))
       end
     end
@@ -63,10 +92,19 @@ module Vivarium
           abort "Invalid vivarium-raw file #{raw}: #{e.message}"
         end
       meta = data[:meta]
+
+      if options[:dump_otel]
+        dump_otel(data[:events], options[:dest])
+        return
+      end
+
       filter = resolve_report_filter(options)
       if options[:max_span_depth]
         filter = (filter || {}).merge(max_span_depth: options[:max_span_depth])
       end
+      if options[:dedup_values]
+        filter = (filter || {}).merge(dedup_values: true)
+      end
 
       Vivarium::TreeRenderer.new(
         events: data[:events],
@@ -81,6 +119,63 @@ module Vivarium
       ).render
     end
 
+    # Flat per-event dump of the OTel-oriented fields, sorted by ktime, with
+    # method-call span nesting resolved by compute_otel_rows. An alternative to
+    # the tree view for inspecting trace_id/span_id propagation.
+    def self.dump_otel(events, dest)
+      header = format("%-18s %-7s %-7s %-6s %-6s %-16s %-32s %-16s %-16s %-5s %s",
+                      "ktime_ns", "pid", "tid", "uid", "gid", "comm",
+                      "trace_id", "span_id", "parent_span", "depth", "event")
+      dest.puts header
+      compute_otel_rows(events).each do |e, span, parent, depth|
+        trace = format("%016x%016x", e.trace_hi.to_i, e.trace_lo.to_i)
+        dest.puts format("%-18d %-7d %-7d %-6d %-6d %-16s %-32s %016x %016x %-5d %s",
+                         e.ktime_ns, e.pid, e.tid, e.uid.to_i, e.gid.to_i, e.comm.to_s,
+                         trace, span, parent, depth, e.event_name)
+      end
+    end
+
+    # Resolve each event's effective OTel span by replaying span_start/span_stop
+    # into a per-tid stack of method-call spans on top of the BPF-provided
+    # thread/process span. Returns [event, span_id, parent_span_id, depth] per
+    # event. A method span's id is hashed from (trace_id, tid, span-start ktime):
+    # non-zero, unique within the trace, and stable across re-runs. When no method
+    # span is active, the thread span and its parent_span_id form the base frame.
+    # The stack is per-tid so spawned children nest independently.
+    def self.compute_otel_rows(events)
+      sorted = events.sort_by { |e| [e.ktime_ns, e.pid, e.tid] }
+      stacks = Hash.new { |h, k| h[k] = [] } # tid => [method_span_id, ...]
+      parent_of = {}                         # method_span_id => parent span_id
+
+      sorted.map do |e|
+        thread_span = e.span_id.to_i
+        stack = stacks[e.tid]
+
+        case e.event_name
+        when "span_start"
+          parent = stack.empty? ? thread_span : stack.last
+          span = Vivarium.synth_span_id(e.trace_hi.to_i, e.trace_lo.to_i, e.tid, e.ktime_ns)
+          parent_of[span] = parent
+          stack.push(span)
+          [e, span, parent, stack.size]
+        when "span_stop"
+          if stack.empty?
+            [e, thread_span, e.parent_span_id.to_i, 0]
+          else
+            span = stack.pop
+            [e, span, parent_of[span] || thread_span, stack.size + 1]
+          end
+        else
+          if stack.empty?
+            [e, thread_span, e.parent_span_id.to_i, 0]
+          else
+            span = stack.last
+            [e, span, parent_of[span] || thread_span, stack.size]
+          end
+        end
+      end
+    end
+
     # Resolve the report display filter by precedence:
     #   --all  >  --filter JSON  >  --event NAMES  >  DEFAULT_FILTER
     def self.resolve_report_filter(options)

data/lib/vivarium/correlator.rb

@@ -14,13 +14,15 @@ module Vivarium
     SAVE_RAW_PROGRESS_INTERVAL = 1000
 
     def initialize(socket_path: Vivarium.socket_path, observer_pid:, main_tid:,
-                   filter: nil, dest: $stdout, save_raw: nil)
+                   filter: nil, dest: $stdout, save_raw: nil, otel_out: nil, otel_endpoint: nil)
       @socket_path = socket_path
       @observer_pid = observer_pid
       @main_tid = main_tid
       @filter = filter
       @dest = dest
       @save_raw = save_raw
+      @otel_out = otel_out
+      @otel_endpoint = otel_endpoint
 
       @client = DaemonClient.new(socket_path: socket_path)
       @events = []
@@ -35,6 +37,7 @@ module Vivarium
 
       @session_start_iso = Time.now.utc.iso8601(3)
       @session_start_ktime = Vivarium.monotonic_ktime_ns
+      start_stream_exporter if @otel_endpoint
       @sock = @client.open_event_stream
       @thread = Thread.new { run }
       @started = true
@@ -51,6 +54,14 @@ module Vivarium
       @session_stop_iso = Time.now.utc.iso8601(3)
       @session_stop_ktime = Vivarium.monotonic_ktime_ns
 
+      if @stream
+        @stream.finalize(stop_ktime: @session_stop_ktime)
+        @stream_exporter.shutdown
+        warn "[vivarium] otel: streamed spans -> #{@otel_endpoint}"
+        @stopped = true
+        return
+      end
+
       events_snapshot = @events_mutex.synchronize { @events.dup }
       @stopped = true
 
@@ -71,6 +82,14 @@ module Vivarium
         return
       end
 
+      if @otel_out
+        File.open(@otel_out, "w") do |io|
+          Vivarium::OtelExporter.dump(io, events: events_snapshot, meta: meta)
+        end
+        warn "[vivarium] otel_out: wrote OTLP spans -> #{@otel_out}"
+        return
+      end
+
       TreeRenderer.new(events: events_snapshot, **meta, filter: @filter, dest: @dest).render
     end
 
@@ -113,8 +132,27 @@ module Vivarium
       buffer
     end
 
+    def start_stream_exporter
+      @stream_exporter = Vivarium::OtelHttpExporter.new(endpoint: @otel_endpoint).start
+      @stream = Vivarium::OtelSpanStreamer.new(
+        exporter: @stream_exporter,
+        session_start_iso: @session_start_iso,
+        session_start_ktime: @session_start_ktime,
+        observer_pid: @observer_pid,
+        main_tid: @main_tid
+      )
+    end
+
     def capture_event(bytes)
       ev = Vivarium::RawStore.unpack_record(bytes)
+
+      # Streaming mode converts events to spans live and does not buffer them,
+      # so a resident observation does not grow memory without bound.
+      if @stream
+        @stream.on_event(ev)
+        return
+      end
+
       count = @events_mutex.synchronize { @events << ev; @events.size }
       report_save_progress(count)
     rescue StandardError => e

data/lib/vivarium/display_filter.rb

@@ -5,7 +5,7 @@ require "set"
 module Vivarium
   class DisplayFilter
     attr_reader :include_events, :exclude_events, :include_severities, :include_pids, :include_tids,
-                :max_span_depth
+                :max_span_depth, :dedup_values
 
     def self.compile(raw)
       return new if raw.nil?
@@ -30,6 +30,7 @@ module Vivarium
       @include_span_names = normalize_string_set(fetch_key(:include_span_names, :span_names))
       @span_pattern = normalize_pattern(fetch_key(:span, :span_pattern))
       @max_span_depth = normalize_integer(fetch_key(:max_span_depth, :max_depth))
+      @dedup_values = normalize_bool(fetch_key(:dedup_values, :dedup))
 
       payload_value = fetch_key(:payload)
       @payload_pattern = normalize_pattern(fetch_key(:payload_pattern))
@@ -46,7 +47,7 @@ module Vivarium
     end
 
     def needs_payload?
-      !@payload_pattern.nil? || !@payload_patterns_by_event.empty?
+      !@payload_pattern.nil? || !@payload_patterns_by_event.empty? || @dedup_values
     end
 
     def allow_span_name?(span_name)
@@ -139,6 +140,16 @@ module Vivarium
       nil
     end
 
+    def normalize_bool(value)
+      case value
+      when true then true
+      when false, nil then false
+      when String then %w[1 true yes on].include?(value.strip.downcase)
+      when Numeric then !value.zero?
+      else true
+      end
+    end
+
     def normalize_pattern(value)
       case value
       when nil

data/lib/vivarium/otel_exporter.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Vivarium
+  # Converts a captured event stream into an OTLP/JSON ResourceSpans document.
+  #
+  # Two span layers are emitted (see plan): a base thread/process span per tid
+  # (identified by the BPF-issued span_id) and method-call spans reconstructed
+  # from span_start/span_stop. Every other event becomes an OTel span event on
+  # the innermost active span. Method span ids come from Vivarium.synth_span_id
+  # so they match the report --dump-otel view.
+  module OtelExporter
+    SPAN_KIND_INTERNAL = 1
+    SERVICE_NAME = "vivarium"
+    INTERNAL_COMM_MATCH = [/otel_stream\.rb/, /correlator\.rb/].freeze
+    CONTROL_EVENT_NAMES = %w[proc_exit].freeze
+
+    module_function
+
+    # io: a writable IO. Writes a single-line OTLP/JSON document.
+    def dump(io, events:, meta:)
+      io.write(JSON.generate(build_document(events: events, meta: meta)))
+    end
+
+    def build_document(events:, meta:)
+      wrap_document(build_spans(events: events, meta: meta))
+    end
+
+    # Wraps a list of OTLP span hashes in the ResourceSpans envelope. Shared by
+    # the batch file exporter and the streaming HTTP exporter so both emit the
+    # same resource/scope.
+    def wrap_document(spans)
+      {
+        resourceSpans: [
+          {
+            resource: { attributes: [str_attr("service.name", SERVICE_NAME)] },
+            scopeSpans: [
+              {
+                scope: { name: SERVICE_NAME, version: Vivarium::VERSION },
+                spans: spans
+              }
+            ]
+          }
+        ]
+      }
+    end
+
+    # Returns an array of OTLP span hashes.
+    def build_spans(events:, meta:)
+      sorted = events.sort_by { |e| [e.ktime_ns, e.pid, e.tid] }
+      start_ktime = meta[:session_start_ktime].to_i
+      stop_ktime = meta[:session_stop_ktime].to_i
+      start_unix = iso_to_unix_ns(meta[:session_start_iso])
+      main_tid = meta[:main_tid]
+      to_unix = ->(k) { (start_unix + (k.to_i - start_ktime)).to_s }
+
+      thread_spans = {}        # tid => mutable span record
+      method_spans = []        # all method span records
+      stacks = Hash.new { |h, k| h[k] = [] } # tid => [method span record, ...]
+
+      sorted.each do |ev|
+        next if internal_comm?(ev.comm)
+        next if control_event?(ev.event_name)
+
+        ts = (thread_spans[ev.tid] ||= new_thread_span(ev, main_tid))
+        ts[:comm] = ev.comm.to_s unless ev.comm.to_s.empty?
+        ts[:min_k] = ev.ktime_ns if ev.ktime_ns < ts[:min_k]
+        ts[:max_k] = ev.ktime_ns if ev.ktime_ns > ts[:max_k]
+        stack = stacks[ev.tid]
+
+        case ev.event_name
+        when "span_start"
+          name, file, lineno = read_span_payload(ev.payload)
+          parent = stack.empty? ? ts[:span_id] : stack.last[:span_id]
+          rec = {
+            tid: ev.tid, pid: ev.pid,
+            span_id: Vivarium.synth_span_id(ev.trace_hi.to_i, ev.trace_lo.to_i, ev.tid, ev.ktime_ns),
+            trace_hi: ev.trace_hi.to_i, trace_lo: ev.trace_lo.to_i,
+            parent: parent, name: (name.nil? || name.empty? ? "<anonymous>" : name),
+            file: file, lineno: lineno, start_k: ev.ktime_ns, stop_k: nil, events: []
+          }
+          method_spans << rec
+          stack.push(rec)
+        when "span_stop"
+          rec = stack.pop
+          rec[:stop_k] = ev.ktime_ns if rec
+        else
+          host = stack.empty? ? ts : stack.last
+          host[:events] << build_span_event(ev, to_unix)
+        end
+      end
+
+      method_spans.each { |rec| rec[:stop_k] ||= stop_ktime }
+
+      out = []
+      thread_spans.each_value { |ts| out << thread_span_hash(ts, start_ktime, stop_ktime, to_unix) }
+      method_spans.each { |rec| out << method_span_hash(rec, to_unix) }
+      out
+    end
+
+    # --- span record construction -------------------------------------------
+
+    def new_thread_span(ev, main_tid)
+      span_id = ev.span_id.to_i
+      span_id = Vivarium.synth_span_id(ev.trace_hi.to_i, ev.trace_lo.to_i, ev.tid, ev.ktime_ns) if span_id.zero?
+      {
+        tid: ev.tid, pid: ev.pid, span_id: span_id,
+        trace_hi: ev.trace_hi.to_i, trace_lo: ev.trace_lo.to_i,
+        parent: ev.parent_span_id.to_i, comm: ev.comm.to_s,
+        root: ev.tid == main_tid,
+        min_k: ev.ktime_ns, max_k: ev.ktime_ns, events: []
+      }
+    end
+
+    def thread_span_hash(ts, start_ktime, stop_ktime, to_unix)
+      start_k = ts[:root] ? start_ktime : ts[:min_k]
+      stop_k = ts[:root] ? stop_ktime : ts[:max_k]
+      name = ts[:comm].empty? ? "tid=#{ts[:tid]}" : ts[:comm]
+      span_hash(
+        trace_hi: ts[:trace_hi], trace_lo: ts[:trace_lo],
+        span_id: ts[:span_id], parent: ts[:parent], name: name,
+        start_k: start_k, stop_k: stop_k, to_unix: to_unix,
+        attributes: [
+          int_attr("thread.id", ts[:tid]),
+          int_attr("process.pid", ts[:pid]),
+          str_attr("process.command", ts[:comm])
+        ],
+        events: ts[:events] || []
+      )
+    end
+
+    def method_span_hash(rec, to_unix)
+      attrs = [int_attr("thread.id", rec[:tid]), int_attr("process.pid", rec[:pid])]
+      attrs << str_attr("code.filepath", rec[:file]) if rec[:file] && !rec[:file].empty?
+      attrs << int_attr("code.lineno", rec[:lineno]) if rec[:lineno] && rec[:lineno] > 0
+      span_hash(
+        trace_hi: rec[:trace_hi], trace_lo: rec[:trace_lo],
+        span_id: rec[:span_id], parent: rec[:parent], name: rec[:name],
+        start_k: rec[:start_k], stop_k: rec[:stop_k], to_unix: to_unix,
+        attributes: attrs, events: rec[:events]
+      )
+    end
+
+    def span_hash(trace_hi:, trace_lo:, span_id:, parent:, name:, start_k:, stop_k:, to_unix:, attributes:, events:)
+      hash = {
+        traceId: hex32(trace_hi, trace_lo),
+        spanId: hex16(span_id),
+        name: name,
+        kind: SPAN_KIND_INTERNAL,
+        startTimeUnixNano: to_unix.call(start_k),
+        endTimeUnixNano: to_unix.call(stop_k),
+        attributes: attributes
+      }
+      hash[:parentSpanId] = hex16(parent) unless parent.to_i.zero?
+      hash[:events] = events unless events.empty?
+      hash
+    end
+
+    def build_span_event(ev, to_unix)
+      { timeUnixNano: to_unix.call(ev.ktime_ns), name: ev.event_name, attributes: event_attributes(ev) }
+    end
+
+    # OTLP attribute list describing an event (target/severity/uid/gid/comm/...).
+    # Reused for both span events and standalone single-event spans (streaming).
+    def event_attributes(ev)
+      target =
+        begin
+          Vivarium.render_event_payload(ev).to_s.gsub(/\s+/, " ").strip
+        rescue StandardError
+          ""
+        end
+      attrs = [
+        int_attr("thread.id", ev.tid),
+        int_attr("process.pid", ev.pid),
+        int_attr("user.id", ev.uid),
+        int_attr("group.id", ev.gid),
+        str_attr("severity", Vivarium.event_severity(ev.event_name))
+      ]
+      attrs << str_attr("process.command", ev.comm.to_s) unless ev.comm.to_s.empty?
+      attrs << str_attr("target", target) unless target.empty?
+      attrs
+    end
+
+    # --- helpers -------------------------------------------------------------
+
+    def internal_comm?(comm)
+      value = comm.to_s
+      INTERNAL_COMM_MATCH.any? { |regex| value.match?(regex) }
+    end
+
+    def control_event?(event_name)
+      CONTROL_EVENT_NAMES.include?(event_name.to_s)
+    end
+
+    def read_span_payload(payload)
+      bytes = payload.to_s.b
+      return [nil, nil, -1] if bytes.empty?
+
+      name = Vivarium.c_string(bytes[0, Vivarium::SPAN_METHOD_SIZE])
+      file = Vivarium.c_string(bytes[Vivarium::SPAN_METHOD_SIZE, Vivarium::SPAN_FILE_SIZE])
+      lineno = bytes.bytesize > Vivarium::SPAN_LINENO_OFFSET ? bytes[Vivarium::SPAN_LINENO_OFFSET, 8].unpack1("q<") : -1
+      [name, file, lineno]
+    end
+
+    def iso_to_unix_ns(iso)
+      return 0 if iso.nil? || iso.to_s.empty?
+
+      (Time.iso8601(iso).to_r * 1_000_000_000).to_i
+    rescue ArgumentError
+      0
+    end
+
+    def hex32(hi, lo)
+      format("%016x%016x", hi.to_i & Vivarium::U64_MASK, lo.to_i & Vivarium::U64_MASK)
+    end
+
+    def hex16(value)
+      format("%016x", value.to_i & Vivarium::U64_MASK)
+    end
+
+    def str_attr(key, value)
+      { key: key, value: { stringValue: value.to_s } }
+    end
+
+    def int_attr(key, value)
+      { key: key, value: { intValue: value.to_i.to_s } }
+    end
+  end
+end