有关文档，请参阅 pretty_trace。

lib.rs:

此包提供生成美观回溯和性能分析的工具。

美观回溯

堆栈跟踪（或“回溯”）是描述给定时刻代码行为的基本手段。Rust的美丽之处在于崩溃几乎总是产生回溯，而这些回溯几乎总是从“损坏”的代码行延伸到主程序。我们可能把这些属性视为理所当然，但通常其他语言（包括C++）并不是这样。

然而，与其他语言一样，Rust的本地回溯很冗长。此包的主要目标是为本地回溯提供简洁且易于阅读的“美观”回溯。这些美观的回溯可能比本地回溯短十倍。此外，与Rust的本地回溯不同，美观的回溯无需设置环境变量即可获得。

本地回溯与美观回溯输出的示例

性能分析

性能分析是优化代码的基本工具。包括perf在内的标准性能分析工具功能强大，但使用起来可能具有挑战性。此包提供了一种易于调用和解释的性能分析功能，并以微小的文件作为输出。

这个想法非常简单：如果有可能显著加快代码的运行速度，那么从随机选择的少量回溯中应该能够直接看出这一点。可以通过向主程序添加一个简单的命令行选项来生成这些回溯，使其进入一个特殊的“性能分析”模式，收集回溯并终止。这使用pprof包来收集回溯。

例如，这个命令行选项可能是 PROFILE 来开启性能分析。您可以选择如何指定这个命令行选项，但这个crate使得这样做变得非常简单。只需几分钟的工作，您就可以在任何时候几乎不费吹灰之力地对您的代码进行性能分析。请参阅函数 start_profiling 和 stop_profiling。请注意，要产生有用的输出，需要指定一个黑名单crate列表，例如 std。这些crate的条目将从跟踪中移除。

漂亮的跟踪性能分析的示例

漂亮的跟踪性能分析可以准确地显示代码在随机实例中的操作；我们展示了收集的跟踪回溯中的第一个。尝试了更多：尝试的跟踪回溯中有95.8%被报告。未报告的跟踪回溯将完全位于黑名单crate中。

每一行显示一个函数名称，它在哪个crate中，crate的版本（如果已知），crate中的文件名以及行号。

使用漂亮的跟踪的简要指南

首先确保您已启用rust调试：似乎只需在 Cargo.toml 中将 debug 设置为 1 即可，具体取决于您使用的是调试模式还是发布模式。

现在，为了访问漂亮的跟踪，将以下内容放入您的 Cargo.toml

 pretty_trace = {git = "https://github.com/10XGenomics/rust-toolbox.git"}
 

并且

 use pretty_trace::*;
 

在您的main程序中。

接下来，要启用漂亮的跟踪，只需在main程序的开头插入以下内容

     PrettyTrace::new().on();
 

即可。这样就可以使用了！任何panic都会生成漂亮的跟踪回溯。

以下是一些其他有用的功能描述。这包括追踪到您数据中的位置（而不仅仅是代码），以及将性能分析集中在您正在优化的关键crate集合上的能力。

致谢

此代码在10x Genomics开发，部分基于从2000年开始在Whitehead Institute Center for Genome Research / Broad Institute开发的C++代码，并包含在https://github.com/CompRD/BroadCRD中。

常见问题解答

1. 漂亮的跟踪回溯可能会丢失重要信息吗？

可能。因此，我们提供了将完整跟踪回溯输出到文件的功能（作为‘保险’），以及一个环境变量来强制完整跟踪回溯。然而，我们还没有看到丢失重要信息的例子。

2. 漂亮的跟踪回溯本身可以保存到单独的文件中吗？

是的，提供了这个功能。

3. 我可以在Ctrl-C时获得跟踪回溯吗？

是的，如果您这样做

     PrettyTrace::new().ctrlc().on();
 

那么任何Ctrl-C都将转换为panic，然后您将获得跟踪回溯。

完整披露

◼ 此代码仅在linux上经过验证。代码已在OS X上使用，但跟踪回溯可能不完整。提供了此行为的示例。

◼ 理想情况下，会捕获内存不足事件并将其转换为panic，以便我们可以跟踪它们，但我们没有。这是一个通用的rust问题，没有人找到解决方案。请参阅问题43596和内部3673。

◼ 此代码解析格式化堆栈跟踪的输出，而不是直接从正式的堆栈跟踪结构生成输出（它应该这样做）。这使得它容易受到堆栈跟踪格式变化的影响。

◼ 有一个不漂亮的字符串黑名单，它很脆弱。这可能是不管方法的本征特征。

◼ 通常，并行代码中的跟踪回溯不会回退到主程序。

更多

请参阅以下链接中的PrettyTrace文档。

待办事项

◼ 修改代码，使所有情况下的回溯格式一致，与性能分析采用的格式相同。并复用相同的代码。