Module: Rperf::PProf

Defined in:

lib/rperf.rb

Overview

Hand-written protobuf encoder for pprof profile format. Only runs once at stop time, so performance is not critical.

Samples from C are: [[[path_str, label_str], …], weight] This encoder builds its own string table for pprof output.

Class Method Summary

• .build_tables(merged) ⇒ Object

  Assign sequential ids to unique frames.

• .encode(data) ⇒ Object
• .encode_bytes(field, data) ⇒ Object
• .encode_int64(field, value) ⇒ Object
• .encode_message(field, data) ⇒ Object
• .encode_packed_int64(field, values) ⇒ Object
• .encode_packed_uint64(field, values) ⇒ Object
• .encode_uint64(field, value) ⇒ Object
• .encode_value_type(type_idx, unit_idx) ⇒ Object
• .encode_varint(value) ⇒ Object

  — Protobuf encoding helpers —.

Class Method Details

.build_tables(merged) ⇒ Object

Assign sequential ids to unique frames. rperf emits exactly one Location and one Function per frame, sharing the same id, so a single table serves both.

# File 'lib/rperf.rb', line 1439

def build_tables(merged)
  frame_ids = {}
  next_id = 1

  merged.each do |(frames, _thread_seq, _label_set_id), _weight|
    frames.each do |frame|
      unless frame_ids.key?(frame)
        frame_ids[frame] = next_id
        next_id += 1
      end
    end
  end

  frame_ids
end

.encode(data) ⇒ Object

# File 'lib/rperf.rb', line 1297

def encode(data)
  samples_raw = data[:aggregated_samples] || []
  frequency = data[:frequency]
  interval_ns = (frequency && frequency > 0) ? 1_000_000_000 / frequency : 0
  mode = (data[:mode] || :cpu).to_sym

  # Build string table: index 0 must be ""
  string_table = [""]
  string_index = { "" => 0 }

  intern = ->(s) {
    string_index[s] ||= begin
      idx = string_table.size
      string_table << s
      idx
    end
  }

  # Convert string frames to index frames and merge identical stacks per thread/label
  merged = Hash.new(0)
  thread_seq_key = nil  # interned lazily — only when a sample carries thread_seq
  label_sets = data[:label_sets]  # Array of Hash (may be nil)
  samples_raw.each do |frames, weight, thread_seq, label_set_id|
    key = [frames.map { |path, label| [intern.(path), intern.(label)] }, thread_seq || 0, label_set_id || 0]
    merged[key] += weight
  end
  merged = merged.to_a

  # Intern label set keys/values for pprof labels
  label_key_indices = {}  # String key → string_table index
  if label_sets
    label_sets.each do |ls|
      ls.each do |k, v|
        sk = k.to_s
        label_key_indices[sk] ||= intern.(sk)
        intern.(v.to_s)  # ensure value is interned
      end
    end
  end

  # Build the frame → id table (locations and functions are 1:1)
  frame_ids = build_tables(merged)

  # Intern type label and unit
  type_label = mode == :wall ? "wall" : "cpu"
  type_idx = intern.(type_label)
  ns_idx = intern.("nanoseconds")

  # Encode Profile message
  buf = "".b

  # field 1: sample_type (repeated ValueType)
  buf << encode_message(1, encode_value_type(type_idx, ns_idx))

  # field 2: sample (repeated Sample) with thread_seq + user labels
  merged.each do |(frames, thread_seq, label_set_id), weight|
    sample_buf = "".b
    loc_ids = frames.map { |f| frame_ids[f] }
    sample_buf << encode_packed_uint64(1, loc_ids)
    sample_buf << encode_packed_int64(2, [weight])
    if thread_seq && thread_seq > 0
      label_buf = "".b
      thread_seq_key ||= intern.("thread_seq")
      label_buf << encode_int64(1, thread_seq_key)  # key
      label_buf << encode_int64(3, thread_seq)       # num
      sample_buf << encode_message(3, label_buf)
    end
    if label_sets && label_set_id && label_set_id > 0
      ls = label_sets[label_set_id]
      if ls
        ls.each do |k, v|
          label_buf = "".b
          label_buf << encode_int64(1, label_key_indices[k.to_s])  # key
          label_buf << encode_int64(2, string_index[v.to_s])       # str
          sample_buf << encode_message(3, label_buf)
        end
      end
    end
    buf << encode_message(2, sample_buf)
  end

  # field 4: location (repeated Location) — Line points at the same id
  frame_ids.each do |_frame, id|
    loc_buf = "".b
    loc_buf << encode_uint64(1, id)
    line_buf = "".b
    line_buf << encode_uint64(1, id)
    loc_buf << encode_message(4, line_buf)
    buf << encode_message(4, loc_buf)
  end

  # field 5: function (repeated Function)
  frame_ids.each do |frame, func_id|
    func_buf = "".b
    func_buf << encode_uint64(1, func_id)
    func_buf << encode_int64(2, frame[1])    # name (label_idx)
    func_buf << encode_int64(4, frame[0])    # filename (path_idx)
    buf << encode_message(5, func_buf)
  end

  # Intern comment and doc_url strings before encoding string_table
  comment_indices = [
    intern.("rperf #{Rperf::VERSION}"),
    intern.("mode: #{mode}"),
    intern.("frequency: #{frequency}Hz"),
    intern.("ruby: #{RUBY_DESCRIPTION}"),
  ]
  doc_url_idx = intern.("https://ko1.github.io/rperf/docs/help.html")

  # field 6: string_table (repeated string)
  string_table.each do |s|
    buf << encode_bytes(6, s.encode("UTF-8", invalid: :replace, undef: :replace))
  end

  # field 9: time_nanos (int64)
  if data[:start_time_ns]
    buf << encode_int64(9, data[:start_time_ns])
  end

  # field 10: duration_nanos (int64)
  if data[:duration_ns]
    buf << encode_int64(10, data[:duration_ns])
  end

  # field 11: period_type (ValueType)
  buf << encode_message(11, encode_value_type(type_idx, ns_idx))

  # field 12: period (int64)
  buf << encode_int64(12, interval_ns)

  # field 13: comment (repeated int64 = string_table index)
  comment_indices.each { |idx| buf << encode_int64(13, idx) }

  # field 15: doc_url (int64 = string_table index)
  buf << encode_int64(15, doc_url_idx)

  buf
end

.encode_bytes(field, data) ⇒ Object

# File 'lib/rperf.rb', line 1481

def encode_bytes(field, data)
  data = data.b if data.respond_to?(:b)
  encode_varint((field << 3) | 2) + encode_varint(data.bytesize) + data
end

.encode_int64(field, value) ⇒ Object

# File 'lib/rperf.rb', line 1477

def encode_int64(field, value)
  encode_varint((field << 3) | 0) + encode_varint(value < 0 ? value + (1 << 64) : value)
end

.encode_message(field, data) ⇒ Object

# File 'lib/rperf.rb', line 1486

def encode_message(field, data)
  encode_bytes(field, data)
end

.encode_packed_int64(field, values) ⇒ Object

# File 'lib/rperf.rb', line 1499

def encode_packed_int64(field, values)
  inner = values.map { |v| encode_varint(v < 0 ? v + (1 << 64) : v) }.join
  encode_bytes(field, inner)
end

.encode_packed_uint64(field, values) ⇒ Object

# File 'lib/rperf.rb', line 1494

def encode_packed_uint64(field, values)
  inner = values.map { |v| encode_varint(v) }.join
  encode_bytes(field, inner)
end

.encode_uint64(field, value) ⇒ Object

# File 'lib/rperf.rb', line 1473

def encode_uint64(field, value)
  encode_varint((field << 3) | 0) + encode_varint(value)
end

.encode_value_type(type_idx, unit_idx) ⇒ Object

# File 'lib/rperf.rb', line 1490

def encode_value_type(type_idx, unit_idx)
  encode_int64(1, type_idx) + encode_int64(2, unit_idx)
end

.encode_varint(value) ⇒ Object

— Protobuf encoding helpers —

# File 'lib/rperf.rb', line 1457

def encode_varint(value)
  value = value & 0xFFFFFFFF_FFFFFFFF if value < 0
  buf = "".b
  loop do
    byte = value & 0x7F
    value >>= 7
    if value > 0
      buf << (byte | 0x80).chr
    else
      buf << byte.chr
      break
    end
  end
  buf
end