一文读懂 pretty_backtrace 的 10 个配置项从值截断长度到有效行数全解析【免费下载链接】pretty_backtracePretty your exception backtrace.项目地址: https://gitcode.com/gh_mirrors/pr/pretty_backtrace调试 Ruby 程序时又长又乱的异常堆栈常常让人头疼。pretty_backtrace 是一款专为 Ruby 开发者打造的异常堆栈美化工具它能在堆栈中自动附加局部变量名与对应值让报错信息一目了然。本文带你一文读懂 pretty_backtrace 的 10 个配置项从值截断长度到有效行数手把手教你调出最适合自己的调试体验。所有配置都定义在核心文件lib/pretty_backtrace.rb中改动一处即可立刻生效。什么是 pretty_backtrace让异常堆栈从杂乱变清晰在默认情况下Ruby 抛出的异常只显示文件名:行号:in 方法名变量值需要你手动打日志才能看到。而 pretty_backtrace 借助debug_inspector底层能力在每一层堆栈帧后自动追加局部变量名和值效果对比非常直观# 启用前只能看到调用位置 test.rb:10:in recursive: bottom of recursive (RuntimeError) # 启用后每一层都附带了 n 和 str 的实时值 test.rb:10:in recursive (n 0, str Hi 0!! Hi 0!! Hi 0...): bottom of recursive (RuntimeError) from test.rb:9:in recursive (n 1, str Hi 1!! Hi 1!! Hi 1...)它的配置方式非常灵活既可以通过PrettyBacktrace::CONFIG哈希直接修改也可以使用内置的 setter 方法。接下来我们逐项拆解它的全部配置能力。一分钟快速上手安装并启用 pretty_backtrace在 Gemfile 中加入一行依赖然后执行bundle即可gem pretty_backtrace启用方式有两种显式调用或者直接 require 自动启用文件require pretty_backtrace PrettyBacktrace.enable # 更省事require 即自动启用 require pretty_backtrace/enablelib/pretty_backtrace/enable.rb内部其实就是一行PrettyBacktrace.enable所以按需选择即可。启用后无需任何额外配置就能看到美化后的堆栈。10 个配置项速览默认值与作用一目了然配置项默认值作用truncate_length20单行模式下局部变量值的截断长度multi_linefalse是否开启多行模式multi_line_truncate_length60多行模式下变量值的截断长度multi_line_indent10多行模式附加信息的缩进宽度effective_lines0显示的有效堆栈行数0 表示无限file_contentstrue是否显示对应源码上下文file_contents_lines2源码上下文的行数disabled_exception_classes空哈希需要忽略的异常类集合enable/disable启用全局开关按块临时生效setter 快捷方法—三种常用配置的快捷写法配置项 1truncate_length——单行模式下的值截断长度这是最常见的需求当局部变量的值特别长比如拼接过的大字符串时全量输出会刷屏。truncate_length默认值为 20超过该长度的值会被截断并追加省略号PrettyBacktrace::CONFIG[:truncate_length] 50调大它可以看到更完整的变量值调小则让堆栈更紧凑适合在日志量大的生产环境使用。配置项 2multi_line——多行模式开关默认的单行模式适合快速扫读而multi_line true会切换为多行模式每个堆栈帧独占多行同时展示[FILE]源码块和[LOCAL VARIABLES]变量块甚至用-精确指向出错的那一行代码PrettyBacktrace.multi_line true多行模式是深度排查问题时最强大的武器代价是输出体积明显变大。配置项 3multi_line_truncate_length——多行模式的值截断长度进入多行模式后变量值的截断长度独立于单行模式默认值为 60。也就是说多行模式允许展示更长的值避免关键信息过早被截掉PrettyBacktrace::CONFIG[:multi_line_truncate_length] 120如果你的变量里含有超长 SQL 或 JSON把它调大非常实用。配置项 4multi_line_indent——多行模式的缩进宽度多行模式下[FILE]与[LOCAL VARIABLES]块默认缩进 10 个空格让附加信息与堆栈主体区分开来。若你希望层级更明显或更紧凑可以调整它PrettyBacktrace::CONFIG[:multi_line_indent] 4缩进越小输出的横向宽度越小在窄终端中阅读更友好。配置项 5effective_lines——控制有效行数0 表示无限默认情况下pretty_backtrace 会处理完整堆栈。但递归或深层调用会生成大量堆栈帧全部美化既耗时又刷屏。effective_lines可以限制参与美化的堆栈行数默认值 0 表示无限# 只美化最近 5 层堆栈 PrettyBacktrace.effective_lines 5这在排查递归爆栈问题时格外好用——你通常只关心最靠近异常发生的几层。配置项 6file_contents——是否显示源码上下文在多行模式下每个堆栈帧默认会附上出错位置附近的源码片段方便对照代码。若你只想看变量值、不想要源码可以关闭它PrettyBacktrace::CONFIG[:file_contents] false需要说明的是该开关只对多行模式生效且要求源码文件确实存在于磁盘上。配置项 7file_contents_lines——源码上下文行数源码片段默认取出错行前后各 2 行即上下各file_contents_lines行。如果你希望看到更完整的上下文可以适当增大PrettyBacktrace::CONFIG[:file_contents_lines] 5注意该配置与truncate_length类似只在多行模式下有意义。配置项 8disabled_exception_classes——忽略指定异常类有些异常比如业务上频繁抛出的自定义异常你并不想看到美化堆栈disabled_exception_classes就是为此设计的。它内部通过kind_of?判断异常类型PrettyBacktrace::CONFIG[:disabled_exception_classes] { BusinessError true }命中该集合的异常会保持原始堆栈避免干扰也顺带省去不必要的性能开销。配置项 9enable 与 disable——全局开关的两种用法除了进程级启用enable还支持块语法实现局部生效只有块内抛出的异常会被美化块外不受影响PrettyBacktrace.enable do # 这里的异常堆栈会被美化 end PrettyBacktrace.disable do # 这里的异常堆栈保持原样 end这对于只对特定代码段做精细调试、又不想影响全局输出的场景非常合适。配置项 10setter 快捷方法——三种高频配置的简便写法lib/pretty_backtrace.rb的末尾为最高频的三个配置提供了 setter 方法比直接操作CONFIG哈希更简洁PrettyBacktrace.multi_line true PrettyBacktrace.file_contents false PrettyBacktrace.effective_lines 10它们分别等价于修改CONFIG[:multi_line]、CONFIG[:file_contents]和CONFIG[:effective_lines]属于语法糖选你顺手的方式即可。配置项最佳实践按场景快速选择使用场景推荐配置组合日常开发快速定位保持默认单行模式即可排查递归爆栈effective_lines 5只美化最近几层深挖复杂 Bugmulti_line true配合file_contents_lines 5生产环境精简日志truncate_length 30必要时关掉file_contents忽略已知业务异常配置disabled_exception_classes总结从值截断长度到有效行数配置全部掌握pretty_backtrace 的全部配置都集中在lib/pretty_backtrace.rb中总计 8 个哈希配置项加上enable、disable与 setter 快捷方法构成了完整的可调体系。从控制变量值显示宽度的truncate_length到决定堆栈处理深度的effective_lines再到多行模式的源码上下文与缩进每一项都能精准应对不同的调试场景。现在打开你的 Gemfile 装上 pretty_backtrace动手体验一下这 10 个配置项带来的调试效率提升吧。遇到问题先看源码注释改动配置后立刻生效无需重启。【免费下载链接】pretty_backtracePretty your exception backtrace.项目地址: https://gitcode.com/gh_mirrors/pr/pretty_backtrace创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考