builtin/profiler/reporter.lua

   1 --Minetest
   2 --Copyright (C) 2016 T4im
   3 --
   4 --This program is free software; you can redistribute it and/or modify
   5 --it under the terms of the GNU Lesser General Public License as published by
   6 --the Free Software Foundation; either version 2.1 of the License, or
   7 --(at your option) any later version.
   8 --
   9 --This program is distributed in the hope that it will be useful,
  10 --but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 --MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 --GNU Lesser General Public License for more details.
  13 --
  14 --You should have received a copy of the GNU Lesser General Public License along
  15 --with this program; if not, write to the Free Software Foundation, Inc.,
  16 --51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  17
  18 local DIR_DELIM, LINE_DELIM = DIR_DELIM, "\n"
  19 local table, unpack, string, pairs, io, os = table, unpack, string, pairs, io, os
  20 local rep, sprintf, tonumber = string.rep, string.format, tonumber
  21 local core, settings = core, core.settings
  22 local reporter = {}
  23
  24 ---
  25 -- Shorten a string. End on an ellipsis if shortened.
  26 --
  27 local function shorten(str, length)
  28         if str and str:len() > length then
  29                 return "..." .. str:sub(-(length-3))
  30         end
  31         return str
  32 end
  33
  34 local function filter_matches(filter, text)
  35         return not filter or string.match(text, filter)
  36 end
  37
  38 local function format_number(number, fmt)
  39         number = tonumber(number)
  40         if not number then
  41                 return "N/A"
  42         end
  43         return sprintf(fmt or "%d", number)
  44 end
  45
  46 local Formatter = {
  47         new = function(self, object)
  48                 object = object or {}
  49                 object.out = {} -- output buffer
  50                 self.__index = self
  51                 return setmetatable(object, self)
  52         end,
  53         __tostring = function (self)
  54                 return table.concat(self.out, LINE_DELIM)
  55         end,
  56         print = function(self, text, ...)
  57                 if (...) then
  58                         text = sprintf(text, ...)
  59                 end
  60
  61                 if text then
  62                         -- Avoid format unicode issues.
  63                         text = text:gsub("Ms", "µs")
  64                 end
  65
  66                 table.insert(self.out, text or LINE_DELIM)
  67         end,
  68         flush = function(self)
  69                 table.insert(self.out, LINE_DELIM)
  70                 local text = table.concat(self.out, LINE_DELIM)
  71                 self.out = {}
  72                 return text
  73         end
  74 }
  75
  76 local widths = { 55, 9, 9, 9, 5, 5, 5 }
  77 local txt_row_format = sprintf(" %%-%ds | %%%ds | %%%ds | %%%ds | %%%ds | %%%ds | %%%ds", unpack(widths))
  78
  79 local HR = {}
  80 for i=1, #widths do
  81         HR[i]= rep("-", widths[i])
  82 end
  83 -- ' | ' should break less with github than '-+-', when people are pasting there
  84 HR = sprintf("-%s-", table.concat(HR, " | "))
  85
  86 local TxtFormatter = Formatter:new {
  87         format_row = function(self, modname, instrument_name, statistics)
  88                 local label
  89                 if instrument_name then
  90                         label = shorten(instrument_name, widths[1] - 5)
  91                         label = sprintf(" - %s %s", label, rep(".", widths[1] - 5 - label:len()))
  92                 else -- Print mod_stats
  93                         label = shorten(modname, widths[1] - 2) .. ":"
  94                 end
  95
  96                 self:print(txt_row_format, label,
  97                         format_number(statistics.time_min),
  98                         format_number(statistics.time_max),
  99                         format_number(statistics:get_time_avg()),
 100                         format_number(statistics.part_min, "%.1f"),
 101                         format_number(statistics.part_max, "%.1f"),
 102                         format_number(statistics:get_part_avg(), "%.1f")
 103                 )
 104         end,
 105         format = function(self, filter)
 106                 local profile = self.profile
 107                 self:print("Values below show absolute/relative times spend per server step by the instrumented function.")
 108                 self:print("A total of %d samples were taken", profile.stats_total.samples)
 109
 110                 if filter then
 111                         self:print("The output is limited to '%s'", filter)
 112                 end
 113
 114                 self:print()
 115                 self:print(
 116                         txt_row_format,
 117                         "instrumentation", "min Ms", "max Ms", "avg Ms", "min %", "max %", "avg %"
 118                 )
 119                 self:print(HR)
 120                 for modname,mod_stats in pairs(profile.stats) do
 121                         if filter_matches(filter, modname) then
 122                                 self:format_row(modname, nil, mod_stats)
 123
 124                                 if mod_stats.instruments ~= nil then
 125                                         for instrument_name, instrument_stats in pairs(mod_stats.instruments) do
 126                                                 self:format_row(nil, instrument_name, instrument_stats)
 127                                         end
 128                                 end
 129                         end
 130                 end
 131                 self:print(HR)
 132                 if not filter then
 133                         self:format_row("total", nil, profile.stats_total)
 134                 end
 135         end
 136 }
 137
 138 local CsvFormatter = Formatter:new {
 139         format_row = function(self, modname, instrument_name, statistics)
 140                 self:print(
 141                         "%q,%q,%d,%d,%d,%d,%d,%f,%f,%f",
 142                         modname, instrument_name,
 143                         statistics.samples,
 144                         statistics.time_min,
 145                         statistics.time_max,
 146                         statistics:get_time_avg(),
 147                         statistics.time_all,
 148                         statistics.part_min,
 149                         statistics.part_max,
 150                         statistics:get_part_avg()
 151                 )
 152         end,
 153         format = function(self, filter)
 154                 self:print(
 155                         "%q,%q,%q,%q,%q,%q,%q,%q,%q,%q",
 156                         "modname", "instrumentation",
 157                         "samples",
 158                         "time min µs",
 159                         "time max µs",
 160                         "time avg µs",
 161                         "time all µs",
 162                         "part min %",
 163                         "part max %",
 164                         "part avg %"
 165                 )
 166                 for modname, mod_stats in pairs(self.profile.stats) do
 167                         if filter_matches(filter, modname) then
 168                                 self:format_row(modname, "*", mod_stats)
 169
 170                                 if mod_stats.instruments ~= nil then
 171                                         for instrument_name, instrument_stats in pairs(mod_stats.instruments) do
 172                                                 self:format_row(modname, instrument_name, instrument_stats)
 173                                         end
 174                                 end
 175                         end
 176                 end
 177         end
 178 }
 179
 180 local function format_statistics(profile, format, filter)
 181         local formatter
 182         if format == "csv" then
 183                 formatter = CsvFormatter:new {
 184                         profile = profile
 185                 }
 186         else
 187                 formatter = TxtFormatter:new {
 188                         profile = profile
 189                 }
 190         end
 191         formatter:format(filter)
 192         return formatter:flush()
 193 end
 194
 195 ---
 196 -- Format the profile ready for display and
 197 -- @return string to be printed to the console
 198 --
 199 function reporter.print(profile, filter)
 200         if filter == "" then filter = nil end
 201         return format_statistics(profile, "txt", filter)
 202 end
 203
 204 ---
 205 -- Serialize the profile data and
 206 -- @return serialized data to be saved to a file
 207 --
 208 local function serialize_profile(profile, format, filter)
 209         if format == "lua" or format == "json" or format == "json_pretty" then
 210                 local stats = filter and {} or profile.stats
 211                 if filter then
 212                         for modname, mod_stats in pairs(profile.stats) do
 213                                 if filter_matches(filter, modname) then
 214                                         stats[modname] = mod_stats
 215                                 end
 216                         end
 217                 end
 218                 if format == "lua" then
 219                         return core.serialize(stats)
 220                 elseif format == "json" then
 221                         return core.write_json(stats)
 222                 elseif format == "json_pretty" then
 223                         return core.write_json(stats, true)
 224                 end
 225         end
 226         -- Fall back to textual formats.
 227         return format_statistics(profile, format, filter)
 228 end
 229
 230 local worldpath = core.get_worldpath()
 231 local function get_save_path(format, filter)
 232         local report_path = settings:get("profiler.report_path") or ""
 233         if report_path ~= "" then
 234                 core.mkdir(sprintf("%s%s%s", worldpath, DIR_DELIM, report_path))
 235         end
 236         return (sprintf(
 237                 "%s/%s/profile-%s%s.%s",
 238                 worldpath,
 239                 report_path,
 240                 os.date("%Y%m%dT%H%M%S"),
 241                 filter and ("-" .. filter) or "",
 242                 format
 243         ):gsub("[/\\]+", DIR_DELIM))-- Clean up delims
 244 end
 245
 246 ---
 247 -- Save the profile to the world path.
 248 -- @return success, log message
 249 --
 250 function reporter.save(profile, format, filter)
 251         if not format or format == "" then
 252                 format = settings:get("profiler.default_report_format") or "txt"
 253         end
 254         if filter == "" then
 255                 filter = nil
 256         end
 257
 258         local path = get_save_path(format, filter)
 259
 260         local output, io_err = io.open(path, "w")
 261         if not output then
 262                 return false, "Saving of profile failed with: " .. io_err
 263         end
 264         local content, err = serialize_profile(profile, format, filter)
 265         if not content then
 266                 output:close()
 267                 return false, "Saving of profile failed with: " .. err
 268         end
 269         output:write(content)
 270         output:close()
 271
 272         local logmessage = "Profile saved to " .. path
 273         core.log("action", logmessage)
 274         return true, logmessage
 275 end
 276
 277 return reporter