tracetool 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 24b271eb9816bfe2c8c9cf44af633851dfd06497
+  data.tar.gz: f1c65ec08ac3aeedc355ec8160d8507cf1e1b73e
+SHA512:
+  metadata.gz: a2008ddb93477871d23e215cd4b7771e15b51942782f3e0a05b292d73e2c3e8b169f95fb4d2b3ce4a1c3c8bf7f007aeda8d68cf529a171999cb21ad9fdb187a2
+  data.tar.gz: 4509d9dd674ef506f88930e178a851da1af1167fe2985d490ecf0a5c3c083bc64d1c3b3f9699753b9492054875dda78a073b1600adc1040790aac82ff353b0ed

data/bin/tracetool

@@ -0,0 +1,2 @@
+#!/usr/bin/env ruby
+require_relative '../lib/tracetool'

data/lib/tracetool/android/java.rb

@@ -0,0 +1,46 @@
+require_relative '../utils/parser'
+
+module Tracetool
+  module Android
+    # Parses java stack traces
+    class JavaTraceParser < Tracetool::BaseTraceParser
+      # Describes java stack entry
+      STACK_ENTRY_PATTERN = /^(\s+at (?<call_description>.+))|((?<error>.+?): (?<message>.+))$/
+      # Describes java method call
+      CALL_PATTERN = /(?<class>.+)\.(?<method>[^\(]+)\((((?<file>.+\.java):(?<line>\d+))|(?<location>.+))\)$/
+
+      def initialize(files)
+        super(STACK_ENTRY_PATTERN, CALL_PATTERN, files, true)
+      end
+    end
+    # Processes java traces
+    class JavaTraceScanner
+      RX_FIRST_EXCEPTION_LINE = /^.+$/
+      RX_OTHER_EXCEPTION_LINE = /at [^(]+\(([^:]+:\d+)|(Native Method)\)$/
+
+      def initialize(string)
+        @trace = string
+      end
+
+      def process(_ctx)
+        @trace
+      end
+
+      class << self
+        def match(string)
+          # Split into lines
+          first, *rest = string.split("\n")
+
+          return if rest.nil? || rest.empty?
+          return unless RX_FIRST_EXCEPTION_LINE.match(first)
+
+          rest.all? { |line| RX_OTHER_EXCEPTION_LINE.match(line) }
+        end
+
+        def [](string)
+          new(string) if match(string)
+        end
+      end
+    end
+  end
+end

data/lib/tracetool/android/native.rb

@@ -0,0 +1,156 @@
+require_relative '../utils/parser'
+
+module Tracetool
+  module Android
+    # Android traces scanner and mapper
+    class NativeTraceParser < Tracetool::BaseTraceParser
+      # Describes android stack entry
+      STACK_ENTRY_PATTERN =
+        %r{Stack frame #(?<frame>\d+)  (?<address>\w+ [a-f\d]+)  (?<lib>[/\w\d\.-]+)( )?(: (?<call_description>.+))?$}
+      # Describes android native method call (class::method and source file with line number)
+      CALL_PATTERN = /(Routine )?(?<method>.+) ((in)|(at)) (?<file>.+):(?<line>\d+)/
+
+      def initialize(files)
+        super(STACK_ENTRY_PATTERN, CALL_PATTERN, files, true)
+      end
+    end
+
+    # Methods for stack trace string normalization
+    module NativeTraceEnhancer
+      # Default header for android backtrace
+      NATIVE_DUMP_HEADER = <<-BACKTRACE.strip_indent
+      *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
+      Build fingerprint: UNKNOWN
+      pid: 0, tid: 0
+      signal 0 (UNKNOWN)
+      backtrace:
+      BACKTRACE
+
+      # Converts packed stack trace into ndk-stack compatible format
+      # @param [String] trace packed stack trace
+      # @return well formed stack trace
+      def unpack(trace)
+        dump_body = prepare(trace).map.with_index { |line, index| convert_line(line, index) }
+        add_header(dump_body.join("\n"))
+      end
+
+      # Add dummy header for stack trace body
+      def add_header(string)
+        NATIVE_DUMP_HEADER + sanitize(string)
+      end
+
+      private
+
+      def prepare(trace)
+        trace.gsub('>>><<<', '')[/<<<(.+)>>>/, 1].split(';')
+      end
+
+      def convert_line(line, index)
+        frame = index
+        addr = line[/^(-?\d+) (.*)$/, 1]
+        lib = line[/^(-?\d+) (.*)$/, 2].strip
+        '    #%02i  pc %08x  %s'.format(frame, addr, lib)
+      end
+
+      # If needed here we'll drop all unneeded leading characters from each
+      # stack trace line. This may be needed to add NATIVE_DUMP_HEADER
+      # correctly
+      def sanitize(string)
+        string
+      end
+    end
+
+    # Processes native traces
+    class NativeTraceScanner
+      # Initial sequence of asterisks which marks begining of trace body
+      TRACE_DELIMETER = '*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***'.freeze
+      RX_INITIAL_ASTERISKS = /#{TRACE_DELIMETER.gsub('*', '\*')}/
+      # Contains address line like
+      #
+      # ```
+      # pc 00000000004321ec libfoo.so
+      # ```
+      RX_PC_ADDRESS = /pc \d+/
+
+      # Format of packed trace.
+      # Consists of one or more trace blocks.
+      # * Each block starts with `<<<` and ends with `>>>`.
+      # * Each block contains one or more lines
+      # * Lines delimited with ;
+      # * Line consists of
+      # ** pointer address `/\d+/`
+      # ** library (so) name `/[^ ]+/`
+      # ** symbol name `/[^ ]+/`, if present
+      # ** symbol offset `/\d+/`
+      #
+      # Last two entries can be missing.
+      RX_PACKED_FORMAT = /^(<<<(\d+ [^ ]+ ([^ ]+ \d+)?;)+>>>)+$/
+
+      # @param [String] string well formed native android stack trace
+      # @see https://developer.android.com/ndk/guides/ndk-stack.html
+      def initialize(string)
+        @trace = string
+      end
+
+      # @param [OpenStruct] ctx context object containing `symbols` field with
+      #   path to symbols dir
+      # @return [String] desymbolicated stack trace
+      def process(ctx)
+        symbols = File.join(ctx.symbols, 'local')
+        symbols = if ctx.arch
+                    File.join(symbols, ctx.arch)
+                  else
+                    Dir[File.join(symbols, '*')].first || symbols
+                  end
+        Pipe['ndk-stack', '-sym', symbols] << @trace
+      end
+
+      class << self
+        # Add methods for trace normalization
+        include Tracetool::Android::NativeTraceEnhancer
+        # Tells if provided string is a ndk trace
+        # @return truthy or falsey value
+        def match(string)
+          return false if string.empty?
+          packed?(string) || with_header?(string) || without_header?(string)
+        end
+
+        def packed?(string)
+          RX_PACKED_FORMAT.match(string)
+        end
+
+        def without_header?(string)
+          lines = string.split("\n")
+          return true if address_lines?(lines)
+
+          first, *rest = lines
+          first.include?('backtrace:') && address_lines?(rest)
+        end
+
+        def address_lines?(lines)
+          lines.all? do |line|
+            RX_PC_ADDRESS.match(line)
+          end
+        end
+
+        def with_header?(string)
+          RX_INITIAL_ASTERISKS.match(string)
+        end
+
+        # With given potential stack trace string
+        # create scanner if possible
+        # @param [String] string trace
+        # @return [NativeTraceScanner] or nil
+        def [](string)
+          if packed? string
+            new(unpack(string))
+          elsif with_header? string
+            new(string)
+          elsif without_header? string
+            new(add_header(string))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tracetool/android.rb

@@ -0,0 +1,30 @@
+require_relative 'android/java'
+require_relative 'android/native'
+
+# Tracetool root module
+module Tracetool
+  # Android trace scan variant
+  module Android
+    # Desymbolicates android traces
+    class AndroidTraceScanner
+      # List of scanners
+      SCANNERS = [JavaTraceScanner, NativeTraceScanner].freeze
+
+      # Launches process of trace desymbolication
+      # @param [String] trace trace body
+      def process(trace, context)
+        # Find scanner which maches trace format
+        scanner = SCANNERS.map { |s| s[trace] }.compact.first
+        raise(ArgumentError, "#{trace}\n not android trace?") unless scanner
+        scanner.process(context)
+      end
+    end
+
+    class << self
+      # Desymbolicate android stack trace
+      def scan(string, opts = {})
+        AndroidTraceScanner.new .process(string, OpenStruct.new(opts))
+      end
+    end
+  end
+end

data/lib/tracetool/ios/parser.rb

@@ -0,0 +1,18 @@
+require_relative '../utils/parser'
+
+module Tracetool
+  module IOS
+    # IOS traces scanner and source mapper
+    class IOSTraceParser < Tracetool::BaseTraceParser
+      # Describes IOS stack entry
+      STACK_ENTRY_PATTERN = /^(?<frame>\d+) (?<binary>[^ ]+) (?<call_description>.+)$/
+      # Describes source block
+      SOURCE_PATTERN =
+        /^((-?\[(?<class>[^ ]+) (?<method>.+)\])|(?<method>.+)) \(in (?<module>.+)\) \((?<file>.+):(?<line>\d+)\)$/
+
+      def initialize(files)
+        super(STACK_ENTRY_PATTERN, SOURCE_PATTERN, files, true)
+      end
+    end
+  end
+end

data/lib/tracetool/ios/scanner.rb

@@ -0,0 +1,78 @@
+module Tracetool
+  module IOS
+    # Converts context to atos arguments
+    class AtosContext
+      # If no arch specified will use `arm64`
+      DEFAULT_ARCH = 'arm64'.freeze
+
+      # List of required argument names
+      REQUIRED_ARGUMENTS = %i[load_address xarchive module_name].freeze
+
+      #
+      def initialize(ctx)
+        check_arguments(ctx)
+        @load_address = ctx.load_address
+        @binary_path = module_binary(ctx.xarchive, ctx.module_name)
+        @arch = ctx.arch || 'arm64'
+      end
+
+      def to_args
+        %w[-o -l -arch].zip([@binary_path, @load_address, @arch]).flatten
+      end
+
+      private
+
+      def module_binary(xarchive, module_name)
+        File.join(xarchive, 'dSYMs', "#{module_name}.app.dSYM", 'Contents', 'Resources', 'DWARF', module_name)
+      end
+
+      def check_arguments(ctx)
+        REQUIRED_ARGUMENTS.each do |a|
+          ctx[a] || raise(ArgumentError, "Missing `#{a}` value")
+        end
+      end
+    end
+
+    # launches atos
+    class IOSTraceScanner
+      # Stack trace line consists of numerous whitespace separated
+      # columns. First three always are:
+      #
+      # * frame #
+      # * binary name
+      # * address
+      # @param [String] trace string containing stack trace
+      # @return [Array] containing (%binary_name%, %address%) pairs
+      def parse(trace)
+        trace.split("\n").map do |line|
+          line.split(' ')[1..2] # Fetch binary name and address
+        end
+      end
+
+      def process(trace, context)
+        trace = parse(trace)
+        desym = run_atos(context, trace.map(&:last))
+        # Add useful columns to unpacked trace
+        mix(trace, desym.split("\n")).join("\n")
+      end
+
+      def run_atos(context, trace)
+        Pipe['atos', *AtosContext.new(context).to_args] << trace
+      end
+
+      private
+
+      def mix(trace, symbolicated)
+        trace.zip(symbolicated).map.with_index do |pair, i|
+          t, desym = pair
+          line = []
+          line << i
+          line << t.first
+          line << desym
+
+          line.join(' ')
+        end
+      end
+    end
+  end
+end

data/lib/tracetool/ios.rb

@@ -0,0 +1,11 @@
+require_relative 'ios/scanner'
+require_relative 'ios/parser'
+
+module Tracetool
+  # IOS trace unpacking routines
+  module IOS
+    def self.scan(string, opts)
+      IOSTraceScanner.new.process(string, OpenStruct.new(opts))
+    end
+  end
+end

data/lib/tracetool/utils/cli.rb

@@ -0,0 +1,118 @@
+require 'optparse'
+require 'optparse/time'
+require 'ostruct'
+
+module Tracetool
+  # Tracetool cli args parser
+  class ParseArgs
+    # List of supported abis
+    ARCH_LIST = %i[armeabi-v7a armeabi x86 arm64 x86_64].freeze
+    #
+    # Return a structure describing the options.
+    #
+    def self.parse(args)
+      # The options specified on the command line will be collected in *options*.
+      # We set default values here.
+      opt_parser = ParseArgs.new(OpenStruct.new(sym_dir: Dir.pwd))
+      options = opt_parser.parse(args)
+      check(options)
+      check_ios(options)
+      options
+    rescue OptionParser::MissingArgument => x
+      puts ["Error occurred: #{x.message}", '', opt_parser.help].join("\n")
+      exit 2
+    end
+
+    def self.check_ios(options)
+      return unless options.platform == :ios
+      {
+        'address' => options.address,
+        'modulename' =>  options.modulename
+      }.each { |arg, check| raise(OptionParser::MissingArgument, arg) unless check }
+    end
+
+    def self.check(options)
+      {
+        'platform' => options.platform,
+        'arch' => options.arch
+      }.each { |arg, check| raise(OptionParser::MissingArgument, arg) unless check }
+    end
+
+    def initialize(defaults)
+      @options = defaults
+      @opt_parser = OptionParser.new do |opts|
+        opt_banner(opts)
+        opts.separator ''
+        opt_common(opts)
+        opts.separator ''
+        opt_ios(opts)
+        opts.separator ''
+        opt_default(opts)
+      end
+    end
+
+    def parse(args)
+      @opt_parser.parse!(args)
+      @options
+    end
+
+    def help
+      @opt_parser.help
+    end
+
+    def opt_banner(opts)
+      opts.banner = 'Usage: tracetool OPTION... [FILE]...'
+      opts.separator ''
+      opts.separator 'Examples:'
+      opts.separator "\techo '<<<...>>>' | tracetool --arch armeabi-v7a --platform android  --symbols %build_dir%"
+      opts.separator "\ttracetool --platform ios --arch arm64 --address 0x100038000 --module ZombieCastaways dump"
+    end
+
+    def opt_common(opts)
+      opts.separator 'Common options:'
+      # Specify arch
+      opts.on('--arch ARCH', ARCH_LIST, "Specify arch #{ARCH_LIST.join(', ')}") do |arch|
+        @options.arch = arch
+      end
+
+      # Specify platform
+      opts.on('--platform PLATORM', %i[android ios], 'Specify platform (android, ios)') do |platform|
+        @options.platform = platform
+      end
+
+      # Symbols dir
+      opts.on('--symbols [SYMBOLS]', 'Symbols dir. Using current working dir if not specified') do |dir|
+        @options.sym_dir = dir
+      end
+    end
+
+    def opt_ios(opts)
+      opts.separator 'IOS specific options'
+      # Addres
+      opts.on('--address ADDRESS', 'Baseline address for ios builds') do |address|
+        @options.address = address
+      end
+
+      # Modulename -- execution entry point
+      opts.on('--module MODULENAME', 'Entry point for ios builds') do |modulename|
+        @options.modulename = modulename
+      end
+    end
+
+    def opt_default(opts)
+      opts.separator 'Base options:'
+      # No argument, shows at tail.  This will print an options summary.
+      # Try it and see!
+      opts.on_tail('-h', '--help', 'Show this message') do
+        puts opts
+        exit
+      end
+
+      # Another typical switch to print the version.
+      opts.on_tail('--version', 'Show version') do
+        puts 'tracetool ' + Tracetool::Version.to_s
+        exit
+      end
+    end
+  end
+end

data/lib/tracetool/utils/env.rb

@@ -0,0 +1,34 @@
+module Tracetool
+  # Utility methods for working with environment
+  module Env
+    class << self
+      # Finds executable in path
+      def which(cmd)
+        exts = ENV['PATHEXT'] ? ENV['PATHEXT'].split(';') : ['']
+        candidates = ENV['PATH'].split(File::PATH_SEPARATOR).flat_map do |path|
+          exts.map { |ext| File.join(path, "#{cmd}#{ext}") }
+        end
+
+        candidates.find { |exe| File.executable?(exe) && !File.directory?(exe) }
+      end
+
+      # Raises exception if can't find executable in path
+      # @raise [ArgumentError] if executable not found
+      def ensure_command(cmd)
+        raise(ArgumentError, "#{cmd} not found in PATH") unless which(cmd)
+      end
+
+      # Checks if `ndk-stack` can be found in path
+      # @raise [ArgumentError] if can't find ndk-stack
+      def ensure_ndk_stack
+        ensure_command('ndk-stack')
+      end
+
+      # Checks if `atos` can be found in path
+      # @raise [ArgumentError] if can't find atos
+      def ensure_atos
+        ensure_command('atos')
+      end
+    end
+  end
+end

data/lib/tracetool/utils/parser.rb

@@ -0,0 +1,104 @@
+module Tracetool
+  # Base trace parser logic
+  class BaseTraceParser
+    attr_reader :entry_pattern, :call_pattern
+
+    def initialize(entry_pattern, call_pattern, build_files, convert_numbers = false)
+      @build_files = build_files
+      @entry_pattern = entry_pattern
+      @call_pattern = call_pattern
+      @convert_numbers = convert_numbers
+    end
+
+    # Parse crash dump
+    # Each line should be parsed in Hash which SHOULD or MAY contains following
+    # entries:
+    #
+    # * SHOULD contain `orig` entry -- original trace entry
+    # * MAY contain following entries IF original entry matched pattern:
+    # ** `frame` - stack frame index
+    # ** `lib` - shared library name (android) or module name (ios)
+    # ** `call_description` - original call block
+    # ** MAY contain `call` entry if `call_description` was recognized:
+    # *** `method` - namespaced method name (with class and its namespace)
+    # *** `file` - file path relative to `symbols dir`
+    # *** `line` - line number in specified file
+    def parse(lines)
+      lines
+        .split("\n")
+        .select { |line| line_filter(line) }
+        .map { |line| scan_call(scan_line(line)) }
+    end
+
+    private
+
+    # Will drop other lines from unpacked result
+    def line_filter(line)
+      entry_pattern.match(line)
+    end
+
+    # Find basic entry elements:
+    # * frame
+    # * address
+    # * library
+    # * call description
+    def scan_line(line)
+      e = { orig: line }
+      entry_pattern.match(line) do |m|
+        e.update(extract_groups(m))
+      end
+      e
+    end
+
+    # Parse call description to extract:
+    # * method
+    # * file
+    # * line number
+    def scan_call(e)
+      if e[:call_description]
+        call_pattern.match(e[:call_description]) do |m|
+          call = extract_groups(m)
+          # Update file entry with expanded path
+          call[:file] = find_file(call[:file]) if call[:file]
+
+          e[:call] = call
+        end
+      end
+
+      e
+    end
+
+    # Find file with specified file name in symbols dir
+    # Can return multiple files if name was ambigous
+    def find_file(file)
+      # Find all matching files
+      # remove build_dir from path
+      # remove leading '/'
+      glob = File.join('**', File.basename(file))
+      files = @build_files.select { |f| File.fnmatch(glob, f) }
+
+      # If has only option return first
+      return files.first if files.size == 1
+      # Return original file if files empty
+      return file if files.empty?
+
+      # If got ambiguous files return all
+      files
+    end
+
+    def extract_groups(match)
+      groups = match
+               .names
+               .map { |name| [name.to_sym, match[name]] }
+               .flat_map { |name, value| [name, try_convert(value)] }
+      Hash[*groups]
+    end
+
+    def try_convert(value)
+      return value unless @convert_numbers
+      return value.to_i if /^\d+$/ =~ value
+
+      value
+    end
+  end
+end

data/lib/tracetool/utils/pipe.rb

@@ -0,0 +1,32 @@
+require 'open3'
+module Tracetool
+  # helper module for launching commands
+  module Pipe
+    # Executes shell command
+    class Executor
+      def initialize(cmd, *args)
+        @cmd = cmd
+        @args = args
+      end
+
+      def cmd
+        [@cmd, @args].flatten
+      end
+
+      def <<(args)
+        args = args.join("\n") if args.is_a? Array
+        IO.popen(cmd, 'r+') do |io|
+          io.write(args)
+          io.close_write
+          io.read.chomp
+        end
+      end
+    end
+
+    class << self
+      def[](cmd, *args)
+        Executor.new(cmd, args)
+      end
+    end
+  end
+end

data/lib/tracetool.rb

@@ -0,0 +1,29 @@
+require 'ostruct'
+require 'powerpack/string'
+
+require_relative 'version'
+
+require_relative 'tracetool/android'
+require_relative 'tracetool/ios'
+require_relative 'tracetool/utils/cli'
+require_relative 'tracetool/utils/env'
+require_relative 'tracetool/utils/pipe'
+
+opts = Tracetool::ParseArgs.parse(ARGV)
+
+case opts.platform
+when :android
+  stack = ARGF.read
+  puts Tracetool::Android.scan(stack,
+                               symbols: opts.sym_dir,
+                               arch: opts.arch.to_s)
+when :ios
+  stack = ARGF.read
+  puts Tracetool::IOS.scan(stack,
+                           arch: opts.arch.to_s,
+                           xarchive: opts.sym_dir,
+                           module_name: opts.modulename,
+                           load_address: opts.address)
+else
+  raise "Unknown(#{opts.platform})"
+end

data/lib/version.rb

@@ -0,0 +1,13 @@
+module Tracetool
+  # Version constant
+  module Version
+    VERSION = [0, 3, 0].freeze
+
+    class << self
+      # @return [String] version string
+      def to_s
+        VERSION.join('.')
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: tracetool
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- ilya.arkhanhelsky
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-11-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: powerpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+description: Helper for unpacking Android and iOS traces
+email: ilya.arkhanhelsky@vizor-games.com
+executables:
+- tracetool
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/tracetool
+- lib/tracetool.rb
+- lib/tracetool/android.rb
+- lib/tracetool/android/java.rb
+- lib/tracetool/android/native.rb
+- lib/tracetool/ios.rb
+- lib/tracetool/ios/parser.rb
+- lib/tracetool/ios/scanner.rb
+- lib/tracetool/utils/cli.rb
+- lib/tracetool/utils/env.rb
+- lib/tracetool/utils/parser.rb
+- lib/tracetool/utils/pipe.rb
+- lib/version.rb
+homepage: https://github.com/vizor-games/tracetool
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.13
+signing_key: 
+specification_version: 4
+summary: Tracetool
+test_files: []