Git 2.22(2019 年第二季度)引入 trace2 和 Jeff Hostetler 的 commit ee4512e:
trace2: 创建新的组合跟踪工具
为 git 创建一个新的统一跟踪工具。
最终意图是用一组统一的git_trace2* 例程替换当前的trace_printf* 和trace_performance* 例程。
除了通常的 printf 样式 API,trace2 还提供了更高级别的
具有固定字段的事件动词允许写入结构化数据。
这使得外部工具更容易进行后期处理和分析。
Trace2 定义了 3 个输出目标。
这些是使用环境变量“GIT_TR2”、“GIT_TR2_PERF”和“GIT_TR2_EVENT”设置的。
这些可以设置为“1”或绝对路径名(就像当前的GIT_TRACE)。
注意:关于环境变量名,请始终使用GIT_TRACExxx,而不是GIT_TRxxx。
所以实际上GIT_TRACE2、GIT_TRACE2_PERF 或GIT_TRACE2_EVENT。
见下文后面提到的 Git 2.22 重命名。
接下来是initial 对这个新跟踪功能的工作,使用old 环境变量名称:
-
GIT_TR2 旨在替代GIT_TRACE 并记录命令摘要数据。
-
GIT_TR2_PERF 旨在替代GIT_TRACE_PERFORMANCE。
它使用命令进程、线程、repo、绝对和相对经过时间的列扩展输出。
它报告子进程启动/停止、线程启动/停止和每个线程函数嵌套的事件。
-
GIT_TR2_EVENT 是一种新的结构化格式。它将事件数据写入一系列 JSON 记录。
对 trace2 函数的调用会记录到启用的 3 个输出目标中的任何一个,而无需调用不同的 trace_printf* 或 trace_performance* 例程。
参见Josh Steadmon (steadmon)commit a4d3a28(2019 年 3 月 21 日)。
(由 Junio C Hamano -- gitster -- 合并于 commit 1b40314,2019 年 5 月 8 日)
trace2: 写入目录目标
当 trace2 环境变量的值是引用现有目录的绝对路径时,将输出写入给定目录下的文件(每个进程一个)。
文件将根据 trace2 SID 的最后一个组件命名,后跟一个计数器以避免潜在的冲突。
这使得为每个 git 调用收集跟踪变得更加方便
通过无条件地将相关的trace2 envvar 设置为常量
目录名。
另请参阅commit f672dee(2019 年 4 月 29 日)和 commit 81567ca、commit 08881b9、commit bad229a、commit 26c6f25、commit bce9db6、commit 800a7f9、commit a7bc01e、commit 39f4317、@89 ,commit 1703751(2019 年 4 月 15 日),Jeff Hostetler (jeffhostetler)。
(由 Junio C Hamano -- gitster -- 合并于 commit 5b2d1c0,2019 年 5 月 13 日)
new documentation 现在包括 config settings which are only read from the system and global config files(意味着存储库本地和工作树配置文件以及 -c 命令行参数不受尊重。)
Example:
$ git config --global trace2.normalTarget ~/log.normal
$ git version
git version 2.20.1.155.g426c96fcdb
产量
$ cat ~/log.normal
12:28:42.620009 common-main.c:38 version 2.20.1.155.g426c96fcdb
12:28:42.620989 common-main.c:39 start git version
12:28:42.621101 git.c:432 cmd_name version (version)
12:28:42.621215 git.c:662 exit elapsed:0.001227 code:0
12:28:42.621250 trace2/tr2_tgt_normal.c:124 atexit elapsed:0.001265 code:0
对于performance measure:
$ git config --global trace2.perfTarget ~/log.perf
$ git version
git version 2.20.1.155.g426c96fcdb
产量
$ cat ~/log.perf
12:28:42.620675 common-main.c:38 | d0 | main | version | | | | | 2.20.1.155.g426c96fcdb
12:28:42.621001 common-main.c:39 | d0 | main | start | | 0.001173 | | | git version
12:28:42.621111 git.c:432 | d0 | main | cmd_name | | | | | version (version)
12:28:42.621225 git.c:662 | d0 | main | exit | | 0.001227 | | | code:0
12:28:42.621259 trace2/tr2_tgt_perf.c:211 | d0 | main | atexit | | 0.001265 | | | code:0
如 Git 2.23(2019 年第三季度)中所述,要使用的环境变量是 GIT_TRACE2。
请参阅commit 6114a40(2019 年 6 月 26 日)Carlo Marcelo Arenas Belón (carenas)。
请参阅 Ævar Arnfjörð Bjarmason (avar) 的 commit 3efa1c6(2019 年 6 月 12 日)。
(由 Junio C Hamano -- gitster -- 合并于 commit e9eaaa4,2019 年 7 月 9 日)
这遵循在 Git 2.22 中完成的工作:commit 4e0d3aa、commit e4b75d6(2019 年 5 月 19 日)SZEDER Gábor (szeder)。
(由 Junio C Hamano -- gitster -- 合并到 commit 463dca6,2019 年 5 月 30 日)
trace2: 将环境变量重命名为 GIT_TRACE2*
对于应该由用户设置的环境变量,GIT_TR2* 环境变量太不清晰、不一致和丑陋。
大部分已建立的GIT_* 环境变量不使用
缩写,如果是少数几个(GIT_DIR、GIT_COMMON_DIR、GIT_DIFF_OPTS),缩写(DIR 和 OPTS)代表什么是非常明显的。
但是TR 代表什么?跟踪,传统,拖车,交易,转移,转换,过渡,翻译,移植,运输,遍历,树,
触发、截断、信任还是...?!
trace2 工具,正如其名称中的“2”后缀所暗示的那样,是
应该最终取代 Git 的原始跟踪工具。
期望相应的环境变量是合理的
跟风,在原来的GIT_TRACE变量之后,它们是
叫GIT_TRACE2;没有这样的东西是'GIT_TR'。
所有 trace2 特定的配置变量都非常明智地位于
'trace2' 部分,不在 'tr2' 中。
OTOH,省略最后三个我们根本没有任何收获
这些环境变量名称中的“trace”字符。
所以让我们将所有GIT_TR2* 环境变量重命名为GIT_TRACE2*,
在他们进入稳定版本之前。
Git 2.24(2019 年第三季度)改进了 Git 存储库初始化。
参见Jeff King (peff)@commit 22932d9、commit 5732f2b、commit 58ebccb(2019 年 8 月 6 日)。
(由 Junio C Hamano -- gitster -- 合并于 commit b4a1eec,2019 年 9 月 9 日)
common-main: 延迟 trace2 初始化
我们在通用 main() 函数中初始化 trace2 系统,以便
所有程序(即使不是内置程序)都将启用跟踪。
但是trace2startup 相对重量级,因为我们必须实际阅读
磁盘配置来决定是否跟踪。
这可能会导致与其他公共主初始化的意外交互。例如,在调用initialize_the_repository() 之前,我们将在配置代码中结束,而the_repository 永远不会为NULL 的通常不变量将不成立。
让我们将 trace2 初始化进一步推到 common-main 中,以
就在我们执行cmd_main()之前。
Git 2.24(2019 年第四季度)还确保 trace2 子系统的输出现在格式更漂亮。
参见commit 742ed63、commit e344305、commit c2b890a(2019 年 8 月 9 日)、commit ad43e37、commit 04f10d3、commit da4589c(2019 年 8 月 8 日)和 commit 371df1b(2019 年 7 月 31 日)@987654 @.
(由 Junio C Hamano -- gitster -- 合并于 commit 93fc876,2019 年 9 月 30 日)
而且,仍然是 Git 2.24
参见Josh Steadmon (steadmon)@commit 87db61a、commit 83e57b0(2019 年 10 月 4 日)和 commit 2254101、commit 3d4548e(2019 年 10 月 3 日)。
(由@987654377 中的Junio C Hamano -- gitster -- 合并@,2019 年 10 月 15 日)
trace2: 如果目标目录有太多文件,则丢弃新的痕迹
签字人:Josh Steadmon
trace2 可以将文件写入目标目录。
由于使用量大,该目录可能会被文件填满,给跟踪处理系统带来困难。
此补丁添加了一个配置选项 (trace2.maxFiles) 以设置 trace2 将写入目标目录的最大文件数。
当maxFiles 设置为正整数时,会启用以下行为:
- 当
trace2 将文件写入目标目录时,首先检查是否应丢弃跟踪。
如果出现以下情况,则应丢弃痕迹:
- 有一个哨兵文件声明文件太多
- 或者,文件数超过
trace2.maxFiles。
在后一种情况下,我们会创建一个名为 git-trace2-discard 的标记文件以加快未来的检查速度。
假设一个单独的跟踪处理系统正在处理生成的跟踪;一旦它处理并删除了标记文件,再次生成新的跟踪文件应该是安全的。
trace2.maxFiles 的默认值为零,这会禁用文件计数检查。
也可以用新的环境变量覆盖配置:GIT_TRACE2_MAX_FILES。
Git 2.24(2019 年第四季度)教授 trace2 关于 git push 阶段。
参见Josh Steadmon (steadmon) 的commit 25e4b80、commit 5fc3118(2019 年 10 月 2 日)。
(由 Junio C Hamano -- gitster -- 合并到 commit 3b9ec27,2019 年 10 月 15 日)
push:添加 trace2 检测
签字人:Josh Steadmon
在transport.c 和builtin/push.c 中添加trace2 区域,以更好地跟踪在推送的各个阶段花费的时间:
在 Git 2.25(2020 年第一季度)中,一些 Documentation/technical 被移动到标题 *.h 文件中。
见commit 6c51cb5、commit d95a77d、commit bbcfa30、commit f1ecbe0、commit 4c4066d、commit 7db0305、commit f3b9055、commit 971b1f2、commit 971b1f2、commit 13aa9c8、@987654398、@987654398、@989 @、commit 3a1b341、commit 126c1cc、commit d27eb35、commit 405c6b1、commit d3d7172、commit 3f1480b、commit 266f03e、commit 13c4d7e(2019 年 11 月 17 日)by Heba Waly (HebaWaly)。
由Junio C Hamano -- gitster -- 合并于commit 26c816a,2019 年 12 月 16 日)
trace2:将文档移至trace2.h
签字人:Heba Waly
将函数文档从Documentation/technical/api-trace2.txt 移至trace2.h,因为开发人员更容易在代码旁边找到使用信息,而不是在另一个文档文件中查找。
只有函数文档部分从Documentation/technical/api-trace2.txt 中删除,因为该文件充满了似乎更适合放在单独的文档文件中的详细信息,并在 trace2.h 中添加了指向该文档文件的链接。此外,函数文档也被删除,以避免冗余信息难以与头文件中的文档保持同步。
(尽管重组对另一个命令产生了副作用,但在 commit cc4f2eb(2020 年 2 月 14 日)Jeff King (peff) 中使用 Git 2.25.2(2020 年 3 月)进行了解释和修复。
(由Junio C Hamano -- gitster --commit 1235384,2020 年 2 月 17 日))
使用 Git 2.27(2020 年第二季度):Trace2 增强以允许记录环境变量。
参见Josh Steadmon (steadmon)commit 3d3adaa(2020 年 3 月 20 日)。
(由 Junio C Hamano -- gitster -- 合并于 commit 810dc64,2020 年 4 月 22 日)
trace2: 教 Git 记录环境变量
签字人:Josh Steadmon
签字人:Jeff Hostetler
通过 trace2,Git 已经可以记录有趣的配置参数(参见trace2_cmd_list_config() 函数)。但是,这可能会导致图片不完整,因为许多配置参数还允许通过环境变量进行覆盖。
为了允许更完整的日志,我们添加了一个新的 trace2_cmd_list_env_vars() 函数和支持实现,以预先存在的配置参数日志记录实现为模型。
使用 Git 2.27(2020 年第二季度),教导显示进度表的代码路径也使用 start_progress() 和 stop_progress() 调用作为要跟踪的“region”。
参见 Emily Shaffer (nasamuffin) 的 commit 98a1364(2020 年 5 月 12 日)。
(由 Junio C Hamano -- gitster -- 合并到 commit d98abce,2020 年 5 月 14 日)
签字人:Emily Shaffer
与其只教授一个操作,如“git fetch”,如何将吞吐量写入跟踪,我们可以通过向进度库本身添加工具来了解可能看起来很慢的各种用户操作。
显示进度的操作可能运行缓慢,并且是我们想要监控性能的那种东西。
通过显示对象计数和数据传输大小,我们应该能够进行一些派生测量,以确保操作按我们预期的方式扩展。
还有:
在 Git 2.27(2020 年第 2 季度)中,我们在最后一刻修复了我们最近的更改,以允许将进度 API 用作可跟踪区域。
参见Derrick Stolee (derrickstolee)commit 3af029c(2020 年 5 月 15 日)。
(由 Junio C Hamano -- gitster -- 合并于 commit 85d6e28,2020 年 5 月 20 日)
progress:仅在调用_enter() 后调用trace2_region_leave()
签字人:Derrick Stolee
progress API 的用户有条件地调用start_progress(),并依赖display_progress() 和stop_progress() 函数在start_progress() 未被调用时变为无操作。
由于我们添加了对 trace2_region_enter() 到 start_progress() 的调用,因此从进度 API 函数对其他 trace2 API 调用的调用必须确保在未对进度调用 start_progress() 时跳过这些 trace2 调用结构。
具体来说,当我们没有调用start_progress() 时,不要从stop_progress() 调用trace2_region_leave(),这会调用匹配的trace2_region_enter()。
Git 2.29(2020 年第四季度)的最后一部分更加强大:
参见Martin Ågren (none) 的commit ac900fd(2020 年 8 月 10 日)。
(由 Junio C Hamano -- gitster -- 合并于 commit e6ec620,2020 年 8 月 17 日)
progress:在检查 NULL 之前不要取消引用
签字人:Martin Ågren
在stop_progress() 中,我们在取消引用之前仔细检查p_progress 是否为非NULL,但到那时我们在调用finish_if_sparse(*p_progress) 时已经取消引用它。
而且,对于它的价值,我们将继续在 stop_progress_msg() 中再次盲目地取消引用它。
如果我们得到一个 NULL 指针,我们可以提前返回,但让我们更进一步,BUG 代替。
进度 API 可以很好地处理 NULL,但这是 *p_progress 的 NULL 特性,例如,在使用 --no-progress 运行时。
如果p_progress 是NULL,那很可能是个错误。
为了对称,让我们在stop_progress_msg() 中也进行同样的检查。
在 Git 2.29(2020 年第四季度)中,有更多的跟踪信息,这次是在 Git 开发环境中。
见Han-Wen Nienhuys (hanwen)commit 4441f42(2020 年 9 月 9 日)。
(由 Junio C Hamano -- gitster -- 合并于 commit c9a04f0,2020 年 9 月 22 日)
refs:添加GIT_TRACE_REFS调试机制
签字人:Han-Wen Nienhuys
在环境中设置时,GIT_TRACE_REFS 使git 打印操作和结果,因为它们流经 ref 存储后端。
这有助于调试不同 ref 后端之间的差异。
例子:
$ GIT_TRACE_REFS="1" ./git branch
15:42:09.769631 refs/debug.c:26 ref_store for .git
15:42:09.769681 refs/debug.c:249 read_raw_ref: HEAD: 0000000000000000000000000000000000000000 (=> refs/heads/ref-debug) type 1: 0
15:42:09.769695 refs/debug.c:249 read_raw_ref: refs/heads/ref-debug: 3a238e539bcdfe3f9eb5010fd218640c1b499f7a (=> refs/heads/ref-debug) type 0: 0
15:42:09.770282 refs/debug.c:233 ref_iterator_begin: refs/heads/ (0x1)
15:42:09.770290 refs/debug.c:189 iterator_advance: refs/heads/b4 (0)
15:42:09.770295 refs/debug.c:189 iterator_advance: refs/heads/branch3 (0)
git 现在包含在其man page 中:
GIT_TRACE_REFS
为 ref 数据库上的操作启用跟踪消息。
有关可用的跟踪输出选项,请参阅 GIT_TRACE。
使用 Git 2.30(2021 年第一季度),如 die() 和 error(),对 warning() 的调用也将触发 trace2 事件。
参见 Jonathan Tan (jhowtan) 的 commit 0ee10fd(2020 年 11 月 23 日)。
(由 Junio C Hamano -- gitster -- 合并于 commit 2aeafbc,2020 年 12 月 8 日)
usage:在warning() 上添加trace2 条目
签字人:Jonathan Tan
每当调用warning() 时都会发出trace2 错误事件,就像调用die()、error() 或usage() 时一样。
这有助于调试会触发警告但不会触发错误的问题。
特别是,这可能有助于调试我在$DAYJOB 遇到的提交图问题。
在包含潜在相关消息和使生成的跟踪输出混乱之间需要权衡取舍。
我认为warning() 消息应该包含在跟踪中,因为就其性质而言,Git 用于 Git 工具的多次调用,并且 Git 调用中的失败(当前跟踪)可能是由先前的意外交互引起的仅将警告(当前未跟踪)作为症状的 Git 调用 - case in here 也是如此。
使用 Git 2.35(2022 年第一季度),exit 被正确跟踪:
参见Ævar Arnfjörð Bjarmason (avar) 的commit 368b584(2021 年 12 月 7 日)。
(由 Junio C Hamano -- gitster -- 合并到 commit 67b7017,2021 年 12 月 22 日)
签字人:Ævar Arnfjörð Bjarmason
将 main() 函数更改为调用“exit()”而不是以“return”语句结束。
“exit()”函数是我们自己的包装器,它为我们调用trace2_cmd_exit_fl(),来自git-compat-util.h:
#define exit(code) exit(trace2_cmd_exit_fl(__FILE__, __LINE__, (code)))
从ee4512e ("trace2: create new combined trace facility", 2019-02-22, Git v2.22.0-rc0 -- merge 列出以来,“exit()”包装器一直在使用在batch #2)。
我们的“main()”下游已经有代码,它非常依赖它,例如“git.c”中"cmd_main()”下游的各种“exit()”调用。
我们甚至在“t/helper/test-trace2.c”中有一个评论,它似乎对“exit()”包装器如何与“return”的使用交互感到困惑,即使它是在同一个文件中引入的a15860d 中的 trace2 系列 (trace2: t/helper/test-trace2, 2019-02-22, Git v2.22.0-rc0 -- merge 列在batch #2) (trace2: t/helper/test -trace2, t0210.sh, t0211.sh, t0212.sh, 2019-02-22),在上述ee4512e之后。
也许它早于“exit()”包装器?