分析和追踪

追踪

¥Tracing

CPU 分析或采样分析生成一个配置文件，用于跟踪构建期间 JavaScript 的执行，并可用于识别代码库的各个部分以及构建期间在其中花费的时间。跟踪是一个更高级别的配置文件，它跟踪 Parcel 执行的特定阶段、调用了哪些插件以及每个阶段花费了多长时间。

¥CPU profiling or sampling profiling generates a profile which tracks execution of JavaScript during the build, and can be used to identify parts of the codebase and where time was spent in it during the build. Tracing is a higher level profile, that tracks specific phases of Parcel's execution, which plugins were called into, and how long is spent in each.

Parcel 跟踪可以通过回答 "哪个插件在我的构建过程中花费的时间最多？" 或 "我的项目中哪个文件的转换时间最长？" 等问题来帮助你优化构建。这些问题并不容易通过 CPU 采样配置文件提供的数据来回答，但可以通过 Parcel 跟踪来回答。

¥A Parcel trace can help you to optimize your build by answering questions such as, "Which plugin is taking the most time during my build?" or "Which file in my project takes the longest to transform?". These questions are not as easy to answer with the data provided by a CPU sampling profile, but can be answered with a Parcel trace.

运行跟踪的开销相对最小，但不为零 - 它肯定比在构建期间运行采样配置文件便宜。特别是，生成的 JSON 文件可能非常大，具体取决于你使用的插件数量和构建的大小。在决定何时启用跟踪时请考虑这些因素。

¥The overhead of running a trace is relatively minimal, but is non-zero - it's certainly less expensive than running a sampling profile during the build. In particular, the JSON file produced can be quite large depending on the numbers of plugins you are using and the size of your build. Consider these factors when deciding when to enable tracing.

用法

¥Usage

CLI

要使用 CLI 生成跟踪，请使用 --trace CLI 参数启动 Parcel。Parcel 将在项目的根目录中生成一个 跟踪 JSON 文件。Parcel 将记录构建开始时将跟踪写入的文件名。

¥To generate a trace with the CLI, start Parcel with the --trace CLI argument. Parcel will generate a trace JSON file in the root of your project. Parcel will log the filename it is writing the trace to when the build starts.

API

要在使用 API 时生成跟踪，你必须通过 Parcel 选项传递 shouldTrace: true 才能启用跟踪事件。此外，你还需要通过 additionalReporters 添加跟踪报告器，以便 Parcel 创建跟踪 JSON 文件。例如：

¥To generate a trace when using the API, you must pass shouldTrace: true with the Parcel options in order to enable the tracing events. In addition, you will need to add the tracer reporter via additionalReporters to have Parcel create the trace JSON file. For example:

import {Parcel} from '@parcel/core';

let bundler = new Parcel({
  // ...
  shouldTrace: true,
  additionalReporters: [{
    packageName: '@parcel/reporter-tracer',
    resolveFrom: __dirname,
  }],
});

格式

¥Format

跟踪 JSON 文件使用 Chrome 跟踪格式，类似于 CPU 配置文件，但分析它有点不同。

¥The tracing JSON file uses the Chrome Tracing Format, similar to CPU profiles, but analysing it is a little bit different.

Parcel 跟踪仅包含类型 X 完整事件。原始事件如下所示：

¥The Parcel trace consists only of type X Complete Events. The raw events look like this:

{"ts":6020131,"pid":11738,"tid":4,"ph":"X","name":"@parcel/transformer-js","cat":"transform","args":{"name":"src/index.html"},"dur":11642},

分析痕迹

¥Analysing traces

虽然你可以将 Parcel 跟踪加载到 Chrome 开发工具中，但该工具中此类配置文件的分析选项相当有限。这是因为这些数据不是开发工具设计的典型数据。例如，跟踪事件包含可用于更深入分析的元数据，并且无法通过开发工具访问此元数据。此外，中型到大型构建可能会产生大量数据，由于其大小而无法加载到 Chrome 开发工具中。

¥While you can load a Parcel trace into Chrome Dev Tools, the analysis options for this kind of profile in that tool is fairly limited. This is because the data is not typical data that Dev Tools is designed for. The trace events, for example, contain metadata that can be useful for deeper analysis and this metadata is not accessible through Dev Tools. In addition, a medium to large sized build may produce a volume of data that is not feasible to load into Chrome Dev Tools due to it's size.

分析 Parcel 跟踪的推荐工具是 完美，它也是由 Google 构建的，但专门为处理大型跟踪和非浏览器跟踪而设计。特别是，Perfetto 对于分析这些跟踪最有用的部分是它将数据加载到 SQLite 数据库中，该数据库可以通过 UI 进行查询 - 这使我们能够回答前面提到的各种问题。

¥The recommended tool for analysing Parcel traces is Perfetto, which is also built by Google, but specifically designed for dealing with large traces, and non-browser traces. In particular, the most useful part of Perfetto for analysing these traces is that it loads the data into an SQLite database that can be queried via the UI - this allows us to answer the kinds of questions that were mentioned earlier.

示例查询

¥Example queries

以下是一些示例查询，你可以在 Perfetto 中的 "查询（SQL）" 函数中输入这些查询，以生成一些有关 Parcel 构建的有用统计信息。请记住，这些结果中的持续时间是总采样时间 - 鉴于 Parcel 的多线程实现，其中一些总时间可能会超过 Parcel 构建的实际时间。

¥Here are some example queries you can enter into the "Query (SQL)" function in Perfetto to generate some useful statistics about your Parcel builds. Keep in mind that the durations in these results are total sampled time - given Parcel's multi-threaded implementation, some of these total times may exceed the wall time of your Parcel build.

我的构建按阶段细分是什么？

¥What is the breakdown of my build by phase?

这是一个高级查询，提供了构建的主要阶段的细分 - 构建、打包、封装 - 并且可以帮助在高水平上确定是否有任何特定阶段花费的时间比预期更长。

¥This is a high level query that provides a breakdown by the main phases of your build - building, bundling, packaging - and can help to identify at a high level if any particular phase stands out as taking longer than expected.

select
  name, SUM(CAST(dur AS double)/1000/1000) as dur_ms
from
  slice s
where
  s.category = "Core"
group by name
order by dur_ms desc

我的构建中哪些插件花费最多时间？

¥What are the plugins in my build that take the most time?

这对于在较高级别上识别 Parcel 花费最多时间的插件很有用。虽然其中一些将成为核心插件，但在你使用自定义插件或其他第三方插件的构建中，这可能是一个有用的查询，用于确定这些插件中是否有任何插件花费了意外的时间 - 这对于识别优化机会很有用。

¥This can be useful to identify at a high level which plugins Parcel spends the most time in. While some of these are going to be core plugins, in a build where you are using custom plugins, or other third-party plugins, this can be a useful query to identify if any of these plugins stand out as taking an unexpected amount of time - which can be useful for identifying optimisation opportunities.

select
  s.category, name, SUM(CAST(dur AS double)/1000/1000) as dur_ms
from
  slice s
left join
  args using(arg_set_id)
where
  args.flat_key = "args.name"
group by s.category, name
order by dur_ms desc

哪些 Babel 插件在我的构建中花费的时间最多？

¥Which Babel plugins are ones are taking the most time in my build?

这对于确定构建中仍需要哪些 Babel 插件并由 @parcel/transform-babel 执行、占用最多时间非常有用，因此可以优先删除或用 Parcel 转换替换。

¥This can be useful to identify which Babel plugins that are still needed in your build, and executed by @parcel/transform-babel, take the most time and so can be prioritised to be removed or replaced with Parcel transforms.

select
  name, SUM(CAST(dur AS double)/1000/1000) as dur_ms
from
  slice s
left join
  args using(arg_set_id)
where
  args.flat_key = "args.name" AND
  s.category LIKE "transform:@parcel/transformer-babel%"
group by name
order by dur_ms desc