technical/api-trace2.html

   1 <!DOCTYPE html>
   2 <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
   3 <head>
   4 <meta charset="UTF-8"/>
   5 <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
   6 <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
   7 <meta name="generator" content="Asciidoctor 2.0.20"/>
   8 <title>Trace2 API</title>
   9 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"/>
  10 <style>
  11 /*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
  12 /* Uncomment the following line when using as a custom stylesheet */
  13 /* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
  14 html{font-family:sans-serif;-webkit-text-size-adjust:100%}
  15 a{background:none}
  16 a:focus{outline:thin dotted}
  17 a:active,a:hover{outline:0}
  18 h1{font-size:2em;margin:.67em 0}
  19 b,strong{font-weight:bold}
  20 abbr{font-size:.9em}
  21 abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
  22 dfn{font-style:italic}
  23 hr{height:0}
  24 mark{background:#ff0;color:#000}
  25 code,kbd,pre,samp{font-family:monospace;font-size:1em}
  26 pre{white-space:pre-wrap}
  27 q{quotes:"\201C" "\201D" "\2018" "\2019"}
  28 small{font-size:80%}
  29 sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
  30 sup{top:-.5em}
  31 sub{bottom:-.25em}
  32 img{border:0}
  33 svg:not(:root){overflow:hidden}
  34 figure{margin:0}
  35 audio,video{display:inline-block}
  36 audio:not([controls]){display:none;height:0}
  37 fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
  38 legend{border:0;padding:0}
  39 button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
  40 button,input{line-height:normal}
  41 button,select{text-transform:none}
  42 button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
  43 button[disabled],html input[disabled]{cursor:default}
  44 input[type=checkbox],input[type=radio]{padding:0}
  45 button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
  46 textarea{overflow:auto;vertical-align:top}
  47 table{border-collapse:collapse;border-spacing:0}
  48 *,::before,::after{box-sizing:border-box}
  49 html,body{font-size:100%}
  50 body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
  51 a:hover{cursor:pointer}
  52 img,object,embed{max-width:100%;height:auto}
  53 object,embed{height:100%}
  54 img{-ms-interpolation-mode:bicubic}
  55 .left{float:left!important}
  56 .right{float:right!important}
  57 .text-left{text-align:left!important}
  58 .text-right{text-align:right!important}
  59 .text-center{text-align:center!important}
  60 .text-justify{text-align:justify!important}
  61 .hide{display:none}
  62 img,object,svg{display:inline-block;vertical-align:middle}
  63 textarea{height:auto;min-height:50px}
  64 select{width:100%}
  65 .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
  66 div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
  67 a{color:#2156a5;text-decoration:underline;line-height:inherit}
  68 a:hover,a:focus{color:#1d4b8f}
  69 a img{border:0}
  70 p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
  71 p aside{font-size:.875em;line-height:1.35;font-style:italic}
  72 h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
  73 h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
  74 h1{font-size:2.125em}
  75 h2{font-size:1.6875em}
  76 h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
  77 h4,h5{font-size:1.125em}
  78 h6{font-size:1em}
  79 hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
  80 em,i{font-style:italic;line-height:inherit}
  81 strong,b{font-weight:bold;line-height:inherit}
  82 small{font-size:60%;line-height:inherit}
  83 code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
  84 ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
  85 ul,ol{margin-left:1.5em}
  86 ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
  87 ul.circle{list-style-type:circle}
  88 ul.disc{list-style-type:disc}
  89 ul.square{list-style-type:square}
  90 ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
  91 ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
  92 dl dt{margin-bottom:.3125em;font-weight:bold}
  93 dl dd{margin-bottom:1.25em}
  94 blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
  95 blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
  96 @media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
  97 h1{font-size:2.75em}
  98 h2{font-size:2.3125em}
  99 h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
 100 h4{font-size:1.4375em}}
 101 table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
 102 table thead,table tfoot{background:#f7f8f7}
 103 table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
 104 table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
 105 table tr.even,table tr.alt{background:#f8f8f7}
 106 table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
 107 h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
 108 h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
 109 .center{margin-left:auto;margin-right:auto}
 110 .stretch{width:100%}
 111 .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
 112 .clearfix::after,.float-group::after{clear:both}
 113 :not(pre).nobreak{word-wrap:normal}
 114 :not(pre).nowrap{white-space:nowrap}
 115 :not(pre).pre-wrap{white-space:pre-wrap}
 116 :not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
 117 pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
 118 pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
 119 pre>code{display:block}
 120 pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
 121 em em{font-style:normal}
 122 strong strong{font-weight:400}
 123 .keyseq{color:rgba(51,51,51,.8)}
 124 kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
 125 .keyseq kbd:first-child{margin-left:0}
 126 .keyseq kbd:last-child{margin-right:0}
 127 .menuseq,.menuref{color:#000}
 128 .menuseq b:not(.caret),.menuref{font-weight:inherit}
 129 .menuseq{word-spacing:-.02em}
 130 .menuseq b.caret{font-size:1.25em;line-height:.8}
 131 .menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
 132 b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
 133 b.button::before{content:"[";padding:0 3px 0 2px}
 134 b.button::after{content:"]";padding:0 2px 0 3px}
 135 p a>code:hover{color:rgba(0,0,0,.9)}
 136 #header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
 137 #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
 138 #header::after,#content::after,#footnotes::after,#footer::after{clear:both}
 139 #content{margin-top:1.25em}
 140 #content::before{content:none}
 141 #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
 142 #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
 143 #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
 144 #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
 145 #header .details span:first-child{margin-left:-.125em}
 146 #header .details span.email a{color:rgba(0,0,0,.85)}
 147 #header .details br{display:none}
 148 #header .details br+span::before{content:"\00a0\2013\00a0"}
 149 #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
 150 #header .details br+span#revremark::before{content:"\00a0|\00a0"}
 151 #header #revnumber{text-transform:capitalize}
 152 #header #revnumber::after{content:"\00a0"}
 153 #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
 154 #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
 155 #toc>ul{margin-left:.125em}
 156 #toc ul.sectlevel0>li>a{font-style:italic}
 157 #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
 158 #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
 159 #toc li{line-height:1.3334;margin-top:.3334em}
 160 #toc a{text-decoration:none}
 161 #toc a:active{text-decoration:underline}
 162 #toctitle{color:#7a2518;font-size:1.2em}
 163 @media screen and (min-width:768px){#toctitle{font-size:1.375em}
 164 body.toc2{padding-left:15em;padding-right:0}
 165 #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
 166 #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
 167 #toc.toc2>ul{font-size:.9em;margin-bottom:0}
 168 #toc.toc2 ul ul{margin-left:0;padding-left:1em}
 169 #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
 170 body.toc2.toc-right{padding-left:0;padding-right:15em}
 171 body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
 172 @media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
 173 #toc.toc2{width:20em}
 174 #toc.toc2 #toctitle{font-size:1.375em}
 175 #toc.toc2>ul{font-size:.95em}
 176 #toc.toc2 ul ul{padding-left:1.25em}
 177 body.toc2.toc-right{padding-left:0;padding-right:20em}}
 178 #content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
 179 #content #toc>:first-child{margin-top:0}
 180 #content #toc>:last-child{margin-bottom:0}
 181 #footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
 182 #footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
 183 #content{margin-bottom:.625em}
 184 .sect1{padding-bottom:.625em}
 185 @media screen and (min-width:768px){#content{margin-bottom:1.25em}
 186 .sect1{padding-bottom:1.25em}}
 187 .sect1:last-child{padding-bottom:0}
 188 .sect1+.sect1{border-top:1px solid #e7e7e9}
 189 #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
 190 #content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
 191 #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
 192 #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
 193 #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
 194 details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
 195 details{margin-left:1.25rem}
 196 details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
 197 details>summary::-webkit-details-marker{display:none}
 198 details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
 199 details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
 200 details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
 201 .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
 202 table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
 203 .paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
 204 .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
 205 .admonitionblock>table td.icon{text-align:center;width:80px}
 206 .admonitionblock>table td.icon img{max-width:none}
 207 .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
 208 .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
 209 .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
 210 .exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
 211 .sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
 212 .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
 213 .exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0}
 214 .exampleblock>.content>:last-child,.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
 215 .literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
 216 @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
 217 @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
 218 .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
 219 .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
 220 .listingblock>.content{position:relative}
 221 .listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
 222 .listingblock:hover code[data-lang]::before{display:block}
 223 .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
 224 .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
 225 .listingblock pre.highlightjs{padding:0}
 226 .listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
 227 .listingblock pre.prettyprint{border-width:0}
 228 .prettyprint{background:#f7f7f8}
 229 pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
 230 pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
 231 pre.prettyprint li code[data-lang]::before{opacity:1}
 232 pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
 233 table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
 234 table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
 235 table.linenotable td.code{padding-left:.75em}
 236 table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
 237 pre.pygments span.linenos{display:inline-block;margin-right:.75em}
 238 .quoteblock{margin:0 1em 1.25em 1.5em;display:table}
 239 .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
 240 .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
 241 .quoteblock blockquote{margin:0;padding:0;border:0}
 242 .quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
 243 .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
 244 .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
 245 .verseblock{margin:0 1em 1.25em}
 246 .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
 247 .verseblock pre strong{font-weight:400}
 248 .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
 249 .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
 250 .quoteblock .attribution br,.verseblock .attribution br{display:none}
 251 .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
 252 .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
 253 .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
 254 .quoteblock.abstract{margin:0 1em 1.25em;display:block}
 255 .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
 256 .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
 257 .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
 258 .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
 259 .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
 260 p.tableblock:last-child{margin-bottom:0}
 261 td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
 262 td.tableblock>.content>:last-child{margin-bottom:-1.25em}
 263 table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
 264 table.grid-all>*>tr>*{border-width:1px}
 265 table.grid-cols>*>tr>*{border-width:0 1px}
 266 table.grid-rows>*>tr>*{border-width:1px 0}
 267 table.frame-all{border-width:1px}
 268 table.frame-ends{border-width:1px 0}
 269 table.frame-sides{border-width:0 1px}
 270 table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
 271 table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
 272 table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
 273 table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
 274 table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
 275 th.halign-left,td.halign-left{text-align:left}
 276 th.halign-right,td.halign-right{text-align:right}
 277 th.halign-center,td.halign-center{text-align:center}
 278 th.valign-top,td.valign-top{vertical-align:top}
 279 th.valign-bottom,td.valign-bottom{vertical-align:bottom}
 280 th.valign-middle,td.valign-middle{vertical-align:middle}
 281 table thead th,table tfoot th{font-weight:bold}
 282 tbody tr th{background:#f7f8f7}
 283 tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
 284 p.tableblock>code:only-child{background:none;padding:0}
 285 p.tableblock{font-size:1em}
 286 ol{margin-left:1.75em}
 287 ul li ol{margin-left:1.5em}
 288 dl dd{margin-left:1.125em}
 289 dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
 290 li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
 291 ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
 292 ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
 293 ul.unstyled,ol.unstyled{margin-left:0}
 294 li>p:empty:only-child::before{content:"";display:inline-block}
 295 ul.checklist>li>p:first-child{margin-left:-1em}
 296 ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
 297 ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
 298 ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
 299 ul.inline>li{margin-left:1.25em}
 300 .unstyled dl dt{font-weight:400;font-style:normal}
 301 ol.arabic{list-style-type:decimal}
 302 ol.decimal{list-style-type:decimal-leading-zero}
 303 ol.loweralpha{list-style-type:lower-alpha}
 304 ol.upperalpha{list-style-type:upper-alpha}
 305 ol.lowerroman{list-style-type:lower-roman}
 306 ol.upperroman{list-style-type:upper-roman}
 307 ol.lowergreek{list-style-type:lower-greek}
 308 .hdlist>table,.colist>table{border:0;background:none}
 309 .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
 310 td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
 311 td.hdlist1{font-weight:bold;padding-bottom:1.25em}
 312 td.hdlist2{word-wrap:anywhere}
 313 .literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
 314 .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
 315 .colist td:not([class]):first-child img{max-width:none}
 316 .colist td:not([class]):last-child{padding:.25em 0}
 317 .thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
 318 .imageblock.left{margin:.25em .625em 1.25em 0}
 319 .imageblock.right{margin:.25em 0 1.25em .625em}
 320 .imageblock>.title{margin-bottom:0}
 321 .imageblock.thumb,.imageblock.th{border-width:6px}
 322 .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
 323 .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
 324 .image.left{margin-right:.625em}
 325 .image.right{margin-left:.625em}
 326 a.image{text-decoration:none;display:inline-block}
 327 a.image object{pointer-events:none}
 328 sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
 329 sup.footnote a,sup.footnoteref a{text-decoration:none}
 330 sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
 331 #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
 332 #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
 333 #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
 334 #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
 335 #footnotes .footnote:last-of-type{margin-bottom:0}
 336 #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
 337 div.unbreakable{page-break-inside:avoid}
 338 .big{font-size:larger}
 339 .small{font-size:smaller}
 340 .underline{text-decoration:underline}
 341 .overline{text-decoration:overline}
 342 .line-through{text-decoration:line-through}
 343 .aqua{color:#00bfbf}
 344 .aqua-background{background:#00fafa}
 345 .black{color:#000}
 346 .black-background{background:#000}
 347 .blue{color:#0000bf}
 348 .blue-background{background:#0000fa}
 349 .fuchsia{color:#bf00bf}
 350 .fuchsia-background{background:#fa00fa}
 351 .gray{color:#606060}
 352 .gray-background{background:#7d7d7d}
 353 .green{color:#006000}
 354 .green-background{background:#007d00}
 355 .lime{color:#00bf00}
 356 .lime-background{background:#00fa00}
 357 .maroon{color:#600000}
 358 .maroon-background{background:#7d0000}
 359 .navy{color:#000060}
 360 .navy-background{background:#00007d}
 361 .olive{color:#606000}
 362 .olive-background{background:#7d7d00}
 363 .purple{color:#600060}
 364 .purple-background{background:#7d007d}
 365 .red{color:#bf0000}
 366 .red-background{background:#fa0000}
 367 .silver{color:#909090}
 368 .silver-background{background:#bcbcbc}
 369 .teal{color:#006060}
 370 .teal-background{background:#007d7d}
 371 .white{color:#bfbfbf}
 372 .white-background{background:#fafafa}
 373 .yellow{color:#bfbf00}
 374 .yellow-background{background:#fafa00}
 375 span.icon>.fa{cursor:default}
 376 a span.icon>.fa{cursor:inherit}
 377 .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
 378 .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
 379 .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
 380 .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
 381 .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
 382 .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
 383 .conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
 384 .conum[data-value] *{color:#fff!important}
 385 .conum[data-value]+b{display:none}
 386 .conum[data-value]::after{content:attr(data-value)}
 387 pre .conum[data-value]{position:relative;top:-.125em}
 388 b.conum *{color:inherit!important}
 389 .conum:not([data-value]):empty{display:none}
 390 dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
 391 h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
 392 p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
 393 p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem}
 394 p{margin-bottom:1.25rem}
 395 .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
 396 .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
 397 .print-only{display:none!important}
 398 @page{margin:1.25cm .75cm}
 399 @media print{*{box-shadow:none!important;text-shadow:none!important}
 400 html{font-size:80%}
 401 a{color:inherit!important;text-decoration:underline!important}
 402 a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
 403 a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
 404 abbr[title]{border-bottom:1px dotted}
 405 abbr[title]::after{content:" (" attr(title) ")"}
 406 pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
 407 thead{display:table-header-group}
 408 svg{max-width:100%}
 409 p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
 410 h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
 411 #header,#content,#footnotes,#footer{max-width:none}
 412 #toc,.sidebarblock,.exampleblock>.content{background:none!important}
 413 #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
 414 body.book #header{text-align:center}
 415 body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
 416 body.book #header .details{border:0!important;display:block;padding:0!important}
 417 body.book #header .details span:first-child{margin-left:0!important}
 418 body.book #header .details br{display:block}
 419 body.book #header .details br+span::before{content:none!important}
 420 body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
 421 body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
 422 .listingblock code[data-lang]::before{display:block}
 423 #footer{padding:0 .9375em}
 424 .hide-on-print{display:none!important}
 425 .print-only{display:block!important}
 426 .hide-for-print{display:none!important}
 427 .show-for-print{display:inherit!important}}
 428 @media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
 429 .sect1{padding:0!important}
 430 .sect1+.sect1{border:0}
 431 #footer{background:none}
 432 #footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
 433 @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
 434 </style>
 435 </head>
 436 <body class="article">
 437 <div id="header">
 438 <h1>Trace2 API</h1>
 439 <div class="details">
 440 <span id="revdate">2024-11-01</span>
 441 </div>
 442 </div>
 443 <div id="content">
 444 <div id="preamble">
 445 <div class="sectionbody">
 446 <div class="paragraph">
 447 <p>The Trace2 API can be used to print debug, performance, and telemetry
 448 information to stderr or a file.  The Trace2 feature is inactive unless
 449 explicitly enabled by enabling one or more Trace2 Targets.</p>
 450 </div>
 451 <div class="paragraph">
 452 <p>The Trace2 API is intended to replace the existing (Trace1)
 453 <code>printf</code>()-style tracing provided by the existing <code>GIT_TRACE</code> and
 454 <code>GIT_TRACE_PERFORMANCE</code> facilities.  During initial implementation,
 455 Trace2 and Trace1 may operate in parallel.</p>
 456 </div>
 457 <div class="paragraph">
 458 <p>The Trace2 API defines a set of high-level messages with known fields,
 459 such as (<code>start</code>: <code>argv</code>) and (<code>exit</code>: {<code>exit-code</code>, <code>elapsed-time</code>}).</p>
 460 </div>
 461 <div class="paragraph">
 462 <p>Trace2 instrumentation throughout the Git code base sends Trace2
 463 messages to the enabled Trace2 Targets.  Targets transform these
 464 messages content into purpose-specific formats and write events to
 465 their data streams.  In this manner, the Trace2 API can drive
 466 many different types of analysis.</p>
 467 </div>
 468 <div class="paragraph">
 469 <p>Targets are defined using a VTable allowing easy extension to other
 470 formats in the future.  This might be used to define a binary format,
 471 for example.</p>
 472 </div>
 473 <div class="paragraph">
 474 <p>Trace2 is controlled using <code>trace2.</code>* config values in the system and
 475 global config files and <code>GIT_TRACE2</code>* environment variables.  Trace2 does
 476 not read from repo local or worktree config files, nor does it respect
 477 <code>-c</code> command line config settings.</p>
 478 </div>
 479 </div>
 480 </div>
 481 <div class="sect1">
 482 <h2 id="_trace2_targets">Trace2 Targets</h2>
 483 <div class="sectionbody">
 484 <div class="paragraph">
 485 <p>Trace2 defines the following set of Trace2 Targets.
 486 Format details are given in a later section.</p>
 487 </div>
 488 <div class="sect2">
 489 <h3 id="_the_normal_format_target">The Normal Format Target</h3>
 490 <div class="paragraph">
 491 <p>The normal format target is a traditional <code>printf</code>() format and similar
 492 to the <code>GIT_TRACE</code> format.  This format is enabled with the <code>GIT_TRACE2</code>
 493 environment variable or the <code>trace2.normalTarget</code> system or global
 494 config setting.</p>
 495 </div>
 496 <div class="paragraph">
 497 <p>For example</p>
 498 </div>
 499 <div class="listingblock">
 500 <div class="content">
 501 <pre>$ export GIT_TRACE2=~/log.normal
 502 $ git version
 503 git version 2.20.1.155.g426c96fcdb</pre>
 504 </div>
 505 </div>
 506 <div class="paragraph">
 507 <p>or</p>
 508 </div>
 509 <div class="listingblock">
 510 <div class="content">
 511 <pre>$ git config --global trace2.normalTarget ~/log.normal
 512 $ git version
 513 git version 2.20.1.155.g426c96fcdb</pre>
 514 </div>
 515 </div>
 516 <div class="paragraph">
 517 <p>yields</p>
 518 </div>
 519 <div class="listingblock">
 520 <div class="content">
 521 <pre>$ cat ~/log.normal
 522 12:28:42.620009 common-main.c:38                  version 2.20.1.155.g426c96fcdb
 523 12:28:42.620989 common-main.c:39                  start git version
 524 12:28:42.621101 git.c:432                         cmd_name version (version)
 525 12:28:42.621215 git.c:662                         exit elapsed:0.001227 code:0
 526 12:28:42.621250 trace2/tr2_tgt_normal.c:124       atexit elapsed:0.001265 code:0</pre>
 527 </div>
 528 </div>
 529 </div>
 530 <div class="sect2">
 531 <h3 id="_the_performance_format_target">The Performance Format Target</h3>
 532 <div class="paragraph">
 533 <p>The performance format target (PERF) is a column-based format to
 534 replace <code>GIT_TRACE_PERFORMANCE</code> and is suitable for development and
 535 testing, possibly to complement tools like <code>gprof</code>.  This format is
 536 enabled with the <code>GIT_TRACE2_PERF</code> environment variable or the
 537 <code>trace2.perfTarget</code> system or global config setting.</p>
 538 </div>
 539 <div class="paragraph">
 540 <p>For example</p>
 541 </div>
 542 <div class="listingblock">
 543 <div class="content">
 544 <pre>$ export GIT_TRACE2_PERF=~/log.perf
 545 $ git version
 546 git version 2.20.1.155.g426c96fcdb</pre>
 547 </div>
 548 </div>
 549 <div class="paragraph">
 550 <p>or</p>
 551 </div>
 552 <div class="listingblock">
 553 <div class="content">
 554 <pre>$ git config --global trace2.perfTarget ~/log.perf
 555 $ git version
 556 git version 2.20.1.155.g426c96fcdb</pre>
 557 </div>
 558 </div>
 559 <div class="paragraph">
 560 <p>yields</p>
 561 </div>
 562 <div class="listingblock">
 563 <div class="content">
 564 <pre>$ cat ~/log.perf
 565 12:28:42.620675 common-main.c:38                  | d0 | main                     | version      |     |           |           |            | 2.20.1.155.g426c96fcdb
 566 12:28:42.621001 common-main.c:39                  | d0 | main                     | start        |     |  0.001173 |           |            | git version
 567 12:28:42.621111 git.c:432                         | d0 | main                     | cmd_name     |     |           |           |            | version (version)
 568 12:28:42.621225 git.c:662                         | d0 | main                     | exit         |     |  0.001227 |           |            | code:0
 569 12:28:42.621259 trace2/tr2_tgt_perf.c:211         | d0 | main                     | atexit       |     |  0.001265 |           |            | code:0</pre>
 570 </div>
 571 </div>
 572 </div>
 573 <div class="sect2">
 574 <h3 id="_the_event_format_target">The Event Format Target</h3>
 575 <div class="paragraph">
 576 <p>The event format target is a JSON-based format of event data suitable
 577 for telemetry analysis.  This format is enabled with the <code>GIT_TRACE2_EVENT</code>
 578 environment variable or the <code>trace2.eventTarget</code> system or global config
 579 setting.</p>
 580 </div>
 581 <div class="paragraph">
 582 <p>For example</p>
 583 </div>
 584 <div class="listingblock">
 585 <div class="content">
 586 <pre>$ export GIT_TRACE2_EVENT=~/log.event
 587 $ git version
 588 git version 2.20.1.155.g426c96fcdb</pre>
 589 </div>
 590 </div>
 591 <div class="paragraph">
 592 <p>or</p>
 593 </div>
 594 <div class="listingblock">
 595 <div class="content">
 596 <pre>$ git config --global trace2.eventTarget ~/log.event
 597 $ git version
 598 git version 2.20.1.155.g426c96fcdb</pre>
 599 </div>
 600 </div>
 601 <div class="paragraph">
 602 <p>yields</p>
 603 </div>
 604 <div class="listingblock">
 605 <div class="content">
 606 <pre>$ cat ~/log.event
 607 {"event":"version","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.620713Z","file":"common-main.c","line":38,"evt":"4","exe":"2.20.1.155.g426c96fcdb"}
 608 {"event":"start","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621027Z","file":"common-main.c","line":39,"t_abs":0.001173,"argv":["git","version"]}
 609 {"event":"cmd_name","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621122Z","file":"git.c","line":432,"name":"version","hierarchy":"version"}
 610 {"event":"exit","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621236Z","file":"git.c","line":662,"t_abs":0.001227,"code":0}
 611 {"event":"atexit","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621268Z","file":"trace2/tr2_tgt_event.c","line":163,"t_abs":0.001265,"code":0}</pre>
 612 </div>
 613 </div>
 614 </div>
 615 <div class="sect2">
 616 <h3 id="_enabling_a_target">Enabling a Target</h3>
 617 <div class="paragraph">
 618 <p>To enable a target, set the corresponding environment variable or
 619 system or global config value to one of the following:</p>
 620 </div>
 621 <div class="openblock">
 622 <div class="content">
 623 <div class="ulist">
 624 <ul>
 625 <li>
 626 <p><code>0</code> or <code>false</code> - Disables the target.</p>
 627 </li>
 628 <li>
 629 <p><code>1</code> or <code>true</code> - Writes to <code>STDERR</code>.</p>
 630 </li>
 631 <li>
 632 <p>[<code>2-9</code>] - Writes to the already opened file descriptor.</p>
 633 </li>
 634 <li>
 635 <p><em>&lt;absolute-pathname&gt;</em> - Writes to the file in append mode. If the target
 636 already exists and is a directory, the traces will be written to files (one
 637 per process) underneath the given directory.</p>
 638 </li>
 639 <li>
 640 <p><code>af_unix:</code>[<em>&lt;socket-type&gt;</em><code>:</code>]<em>&lt;absolute-pathname&gt;</em> - Write to a
 641 Unix DomainSocket (on platforms that support them).  Socket
 642 type can be either <code>stream</code> or <code>dgram</code>; if omitted Git will
 643 try both.</p>
 644 </li>
 645 </ul>
 646 </div>
 647 </div>
 648 </div>
 649 <div class="paragraph">
 650 <p>When trace files are written to a target directory, they will be named according
 651 to the last component of the SID (optionally followed by a counter to avoid
 652 filename collisions).</p>
 653 </div>
 654 </div>
 655 </div>
 656 </div>
 657 <div class="sect1">
 658 <h2 id="_trace2_api">Trace2 API</h2>
 659 <div class="sectionbody">
 660 <div class="paragraph">
 661 <p>The Trace2 public API is defined and documented in <code>trace2.h</code>; refer to it for
 662 more information.  All public functions and macros are prefixed
 663 with <code>trace2_</code> and are implemented in <code>trace2.c</code>.</p>
 664 </div>
 665 <div class="paragraph">
 666 <p>There are no public Trace2 data structures.</p>
 667 </div>
 668 <div class="paragraph">
 669 <p>The Trace2 code also defines a set of private functions and data types
 670 in the <code>trace2/</code> directory.  These symbols are prefixed with <code>tr2_</code>
 671 and should only be used by functions in <code>trace2.c</code> (or other private
 672 source files in <code>trace2/</code>).</p>
 673 </div>
 674 <div class="sect2">
 675 <h3 id="_conventions_for_public_functions_and_macros">Conventions for Public Functions and Macros</h3>
 676 <div class="paragraph">
 677 <p>Some functions have a <code>_fl</code>() suffix to indicate that they take <code>file</code>
 678 and <code>line-number</code> arguments.</p>
 679 </div>
 680 <div class="paragraph">
 681 <p>Some functions have a <code>_va_fl</code>() suffix to indicate that they also
 682 take a <code>va_list</code> argument.</p>
 683 </div>
 684 <div class="paragraph">
 685 <p>Some functions have a <code>_printf_fl</code>() suffix to indicate that they also
 686 take a <code>printf</code>() style format with a variable number of arguments.</p>
 687 </div>
 688 <div class="paragraph">
 689 <p>CPP wrapper macros are defined to hide most of these details.</p>
 690 </div>
 691 </div>
 692 </div>
 693 </div>
 694 <div class="sect1">
 695 <h2 id="_trace2_target_formats">Trace2 Target Formats</h2>
 696 <div class="sectionbody">
 697 <div class="sect2">
 698 <h3 id="_normal_format">NORMAL Format</h3>
 699 <div class="paragraph">
 700 <p>Events are written as lines of the form:</p>
 701 </div>
 702 <div class="listingblock">
 703 <div class="content">
 704 <pre>[&lt;time&gt; SP &lt;filename&gt;:&lt;line&gt; SP+] &lt;event-name&gt; [[SP] &lt;event-message&gt;] LF</pre>
 705 </div>
 706 </div>
 707 <div class="dlist">
 708 <dl>
 709 <dt class="hdlist1"><em>&lt;event-name&gt;</em></dt>
 710 <dd>
 711 <p>is the event name.</p>
 712 </dd>
 713 <dt class="hdlist1"><em>&lt;event-message&gt;</em></dt>
 714 <dd>
 715 <p>is a free-form <code>printf</code>() message intended for human consumption.</p>
 716 <div class="paragraph">
 717 <p>Note that this may contain embedded LF or CRLF characters that are
 718 not escaped, so the event may spill across multiple lines.</p>
 719 </div>
 720 </dd>
 721 </dl>
 722 </div>
 723 <div class="paragraph">
 724 <p>If <code>GIT_TRACE2_BRIEF</code> or <code>trace2.normalBrief</code> is true, the <code>time</code>, <code>filename</code>,
 725 and <code>line</code> fields are omitted.</p>
 726 </div>
 727 <div class="paragraph">
 728 <p>This target is intended to be more of a summary (like GIT_TRACE) and
 729 less detailed than the other targets.  It ignores thread, region, and
 730 data messages, for example.</p>
 731 </div>
 732 </div>
 733 <div class="sect2">
 734 <h3 id="_perf_format">PERF Format</h3>
 735 <div class="paragraph">
 736 <p>Events are written as lines of the form:</p>
 737 </div>
 738 <div class="listingblock">
 739 <div class="content">
 740 <pre>[&lt;time&gt; SP &lt;filename&gt;:&lt;line&gt; SP+
 741     BAR SP] d&lt;depth&gt; SP
 742     BAR SP &lt;thread-name&gt; SP+
 743     BAR SP &lt;event-name&gt; SP+
 744     BAR SP [r&lt;repo-id&gt;] SP+
 745     BAR SP [&lt;t_abs&gt;] SP+
 746     BAR SP [&lt;t_rel&gt;] SP+
 747     BAR SP [&lt;category&gt;] SP+
 748     BAR SP DOTS* &lt;perf-event-message&gt;
 749     LF</pre>
 750 </div>
 751 </div>
 752 <div class="dlist">
 753 <dl>
 754 <dt class="hdlist1"><em>&lt;depth&gt;</em></dt>
 755 <dd>
 756 <p>is the git process depth.  This is the number of parent
 757 git processes.  A top-level git command has depth value "d0".
 758 A child of it has depth value "d1".  A second level child
 759 has depth value "d2" and so on.</p>
 760 </dd>
 761 <dt class="hdlist1"><em>&lt;thread-name&gt;</em></dt>
 762 <dd>
 763 <p>is a unique name for the thread.  The primary thread
 764 is called "main".  Other thread names are of the form "th%d:%s"
 765 and include a unique number and the name of the thread-proc.</p>
 766 </dd>
 767 <dt class="hdlist1"><em>&lt;event-name&gt;</em></dt>
 768 <dd>
 769 <p>is the event name.</p>
 770 </dd>
 771 <dt class="hdlist1"><em>&lt;repo-id&gt;</em></dt>
 772 <dd>
 773 <p>when present, is a number indicating the repository
 774 in use.  A <code>def_repo</code> event is emitted when a repository is
 775 opened.  This defines the repo-id and associated worktree.
 776 Subsequent repo-specific events will reference this repo-id.</p>
 777 <div class="paragraph">
 778 <p>Currently, this is always "r1" for the main repository.
 779 This field is in anticipation of in-proc submodules in the future.</p>
 780 </div>
 781 </dd>
 782 <dt class="hdlist1">&lt;t_abs&gt;</dt>
 783 <dd>
 784 <p>when present, is the absolute time in seconds since the
 785 program started.</p>
 786 </dd>
 787 <dt class="hdlist1">&lt;t_rel&gt;</dt>
 788 <dd>
 789 <p>when present, is time in seconds relative to the start of
 790 the current region.  For a thread-exit event, it is the elapsed
 791 time of the thread.</p>
 792 </dd>
 793 <dt class="hdlist1"><em>&lt;category&gt;</em></dt>
 794 <dd>
 795 <p>is present on region and data events and is used to
 796 indicate a broad category, such as "index" or "status".</p>
 797 </dd>
 798 <dt class="hdlist1"><em>&lt;perf-event-message&gt;</em></dt>
 799 <dd>
 800 <p>is a free-form <code>printf</code>() message intended for human consumption.</p>
 801 </dd>
 802 </dl>
 803 </div>
 804 <div class="listingblock">
 805 <div class="content">
 806 <pre>15:33:33.532712 wt-status.c:2310                  | d0 | main                     | region_enter | r1  |  0.126064 |           | status     | label:print
 807 15:33:33.532712 wt-status.c:2331                  | d0 | main                     | region_leave | r1  |  0.127568 |  0.001504 | status     | label:print</pre>
 808 </div>
 809 </div>
 810 <div class="paragraph">
 811 <p>If <code>GIT_TRACE2_PERF_BRIEF</code> or <code>trace2.perfBrief</code> is true, the <code>time</code>, <code>file</code>,
 812 and <code>line</code> fields are omitted.</p>
 813 </div>
 814 <div class="listingblock">
 815 <div class="content">
 816 <pre>d0 | main                     | region_leave | r1  |  0.011717 |  0.009122 | index      | label:preload</pre>
 817 </div>
 818 </div>
 819 <div class="paragraph">
 820 <p>The PERF target is intended for interactive performance analysis
 821 during development and is quite noisy.</p>
 822 </div>
 823 </div>
 824 <div class="sect2">
 825 <h3 id="_event_format">EVENT Format</h3>
 826 <div class="paragraph">
 827 <p>Each event is a JSON-object containing multiple key/value pairs
 828 written as a single line and followed by a LF.</p>
 829 </div>
 830 <div class="listingblock">
 831 <div class="content">
 832 <pre>'{' &lt;key&gt; ':' &lt;value&gt; [',' &lt;key&gt; ':' &lt;value&gt;]* '}' LF</pre>
 833 </div>
 834 </div>
 835 <div class="paragraph">
 836 <p>Some key/value pairs are common to all events and some are
 837 event-specific.</p>
 838 </div>
 839 <div class="sect3">
 840 <h4 id="_common_keyvalue_pairs">Common Key/Value Pairs</h4>
 841 <div class="paragraph">
 842 <p>The following key/value pairs are common to all events:</p>
 843 </div>
 844 <div class="listingblock">
 845 <div class="content">
 846 <pre>{
 847         "event":"version",
 848         "sid":"20190408T191827.272759Z-H9b68c35f-P00003510",
 849         "thread":"main",
 850         "time":"2019-04-08T19:18:27.282761Z",
 851         "file":"common-main.c",
 852         "line":42,
 853         ...
 854 }</pre>
 855 </div>
 856 </div>
 857 <div class="dlist">
 858 <dl>
 859 <dt class="hdlist1">"event":<em>&lt;event&gt;</em></dt>
 860 <dd>
 861 <p>is the event name.</p>
 862 </dd>
 863 <dt class="hdlist1">"sid":<em>&lt;sid&gt;</em></dt>
 864 <dd>
 865 <p>is the session-id.  This is a unique string to identify the
 866 process instance to allow all events emitted by a process to
 867 be identified.  A session-id is used instead of a PID because
 868 PIDs are recycled by the OS.  For child git processes, the
 869 session-id is prepended with the session-id of the parent git
 870 process to allow parent-child relationships to be identified
 871 during post-processing.</p>
 872 </dd>
 873 <dt class="hdlist1">"thread":<em>&lt;thread&gt;</em></dt>
 874 <dd>
 875 <p>is the thread name.</p>
 876 </dd>
 877 <dt class="hdlist1">"time":<em>&lt;time&gt;</em></dt>
 878 <dd>
 879 <p>is the UTC time of the event.</p>
 880 </dd>
 881 <dt class="hdlist1">"file":<em>&lt;filename&gt;</em></dt>
 882 <dd>
 883 <p>is source file generating the event.</p>
 884 </dd>
 885 <dt class="hdlist1">"line":<em>&lt;line-number&gt;</em></dt>
 886 <dd>
 887 <p>is the integer source line number generating the event.</p>
 888 </dd>
 889 <dt class="hdlist1">"repo":<em>&lt;repo-id&gt;</em></dt>
 890 <dd>
 891 <p>when present, is the integer repo-id as described previously.</p>
 892 </dd>
 893 </dl>
 894 </div>
 895 <div class="paragraph">
 896 <p>If <code>GIT_TRACE2_EVENT_BRIEF</code> or <code>trace2.eventBrief</code> is true, the <code>file</code>
 897 and <code>line</code> fields are omitted from all events and the <code>time</code> field is
 898 only present on the "start" and "atexit" events.</p>
 899 </div>
 900 </div>
 901 <div class="sect3">
 902 <h4 id="_event_specific_keyvalue_pairs">Event-Specific Key/Value Pairs</h4>
 903 <div class="dlist">
 904 <dl>
 905 <dt class="hdlist1">"version"</dt>
 906 <dd>
 907 <p>This event gives the version of the executable and the EVENT format. It
 908 should always be the first event in a trace session. The EVENT format
 909 version will be incremented if new event types are added, if existing
 910 fields are removed, or if there are significant changes in
 911 interpretation of existing events or fields. Smaller changes, such as
 912 adding a new field to an existing event, will not require an increment
 913 to the EVENT format version.</p>
 914 <div class="listingblock">
 915 <div class="content">
 916 <pre>{
 917         "event":"version",
 918         ...
 919         "evt":"4",                     # EVENT format version
 920         "exe":"2.20.1.155.g426c96fcdb" # git version
 921 }</pre>
 922 </div>
 923 </div>
 924 </dd>
 925 <dt class="hdlist1">"too_many_files"</dt>
 926 <dd>
 927 <p>This event is written to the git-trace2-discard sentinel file if there
 928 are too many files in the target trace directory (see the
 929 trace2.maxFiles config option).</p>
 930 <div class="listingblock">
 931 <div class="content">
 932 <pre>{
 933         "event":"too_many_files",
 934         ...
 935 }</pre>
 936 </div>
 937 </div>
 938 </dd>
 939 <dt class="hdlist1">"start"</dt>
 940 <dd>
 941 <p>This event contains the complete argv received by main().</p>
 942 <div class="listingblock">
 943 <div class="content">
 944 <pre>{
 945         "event":"start",
 946         ...
 947         "t_abs":0.001227, # elapsed time in seconds
 948         "argv":["git","version"]
 949 }</pre>
 950 </div>
 951 </div>
 952 </dd>
 953 <dt class="hdlist1">"exit"</dt>
 954 <dd>
 955 <p>This event is emitted when git calls <code>exit</code>().</p>
 956 <div class="listingblock">
 957 <div class="content">
 958 <pre>{
 959         "event":"exit",
 960         ...
 961         "t_abs":0.001227, # elapsed time in seconds
 962         "code":0          # exit code
 963 }</pre>
 964 </div>
 965 </div>
 966 </dd>
 967 <dt class="hdlist1">"atexit"</dt>
 968 <dd>
 969 <p>This event is emitted by the Trace2 <code>atexit</code> routine during
 970 final shutdown.  It should be the last event emitted by the
 971 process.</p>
 972 <div class="paragraph">
 973 <p>(The elapsed time reported here is greater than the time reported in
 974 the "exit" event because it runs after all other atexit tasks have
 975 completed.)</p>
 976 </div>
 977 <div class="listingblock">
 978 <div class="content">
 979 <pre>{
 980         "event":"atexit",
 981         ...
 982         "t_abs":0.001227, # elapsed time in seconds
 983         "code":0          # exit code
 984 }</pre>
 985 </div>
 986 </div>
 987 </dd>
 988 <dt class="hdlist1">"signal"</dt>
 989 <dd>
 990 <p>This event is emitted when the program is terminated by a user
 991 signal.  Depending on the platform, the signal event may
 992 prevent the "atexit" event from being generated.</p>
 993 <div class="listingblock">
 994 <div class="content">
 995 <pre>{
 996         "event":"signal",
 997         ...
 998         "t_abs":0.001227,  # elapsed time in seconds
 999         "signo":13         # SIGTERM, SIGINT, etc.
1000 }</pre>
1001 </div>
1002 </div>
1003 </dd>
1004 <dt class="hdlist1">"error"</dt>
1005 <dd>
1006 <p>This event is emitted when one of the <code>BUG</code>(), <code>bug</code>(), <code>error</code>(),
1007 <code>die</code>(), <code>warning</code>(), or <code>usage</code>() functions are called.</p>
1008 <div class="listingblock">
1009 <div class="content">
1010 <pre>{
1011         "event":"error",
1012         ...
1013         "msg":"invalid option: --cahced", # formatted error message
1014         "fmt":"invalid option: %s"        # error format string
1015 }</pre>
1016 </div>
1017 </div>
1018 <div class="paragraph">
1019 <p>The error event may be emitted more than once.  The format string
1020 allows post-processors to group errors by type without worrying
1021 about specific error arguments.</p>
1022 </div>
1023 </dd>
1024 <dt class="hdlist1">"cmd_path"</dt>
1025 <dd>
1026 <p>This event contains the discovered full path of the git
1027 executable (on platforms that are configured to resolve it).</p>
1028 <div class="listingblock">
1029 <div class="content">
1030 <pre>{
1031         "event":"cmd_path",
1032         ...
1033         "path":"C:/work/gfw/git.exe"
1034 }</pre>
1035 </div>
1036 </div>
1037 </dd>
1038 <dt class="hdlist1">"cmd_ancestry"</dt>
1039 <dd>
1040 <p>This event contains the text command name for the parent (and earlier
1041 generations of parents) of the current process, in an array ordered from
1042 nearest parent to furthest great-grandparent. It may not be implemented
1043 on all platforms.</p>
1044 <div class="listingblock">
1045 <div class="content">
1046 <pre>{
1047         "event":"cmd_ancestry",
1048         ...
1049         "ancestry":["bash","tmux: server","systemd"]
1050 }</pre>
1051 </div>
1052 </div>
1053 </dd>
1054 <dt class="hdlist1">"cmd_name"</dt>
1055 <dd>
1056 <p>This event contains the command name for this git process
1057 and the hierarchy of commands from parent git processes.</p>
1058 <div class="listingblock">
1059 <div class="content">
1060 <pre>{
1061         "event":"cmd_name",
1062         ...
1063         "name":"pack-objects",
1064         "hierarchy":"push/pack-objects"
1065 }</pre>
1066 </div>
1067 </div>
1068 <div class="paragraph">
1069 <p>Normally, the "name" field contains the canonical name of the
1070 command.  When a canonical name is not available, one of
1071 these special values are used:</p>
1072 </div>
1073 <div class="listingblock">
1074 <div class="content">
1075 <pre>"_query_"            # "git --html-path"
1076 "_run_dashed_"       # when "git foo" tries to run "git-foo"
1077 "_run_shell_alias_"  # alias expansion to a shell command
1078 "_run_git_alias_"    # alias expansion to a git command
1079 "_usage_"            # usage error</pre>
1080 </div>
1081 </div>
1082 </dd>
1083 <dt class="hdlist1">"cmd_mode"</dt>
1084 <dd>
1085 <p>This event, when present, describes the command variant. This
1086 event may be emitted more than once.</p>
1087 <div class="listingblock">
1088 <div class="content">
1089 <pre>{
1090         "event":"cmd_mode",
1091         ...
1092         "name":"branch"
1093 }</pre>
1094 </div>
1095 </div>
1096 <div class="paragraph">
1097 <p>The "name" field is an arbitrary string to describe the command mode.
1098 For example, checkout can checkout a branch or an individual file.
1099 And these variations typically have different performance
1100 characteristics that are not comparable.</p>
1101 </div>
1102 </dd>
1103 <dt class="hdlist1">"alias"</dt>
1104 <dd>
1105 <p>This event is present when an alias is expanded.</p>
1106 <div class="listingblock">
1107 <div class="content">
1108 <pre>{
1109         "event":"alias",
1110         ...
1111         "alias":"l",             # registered alias
1112         "argv":["log","--graph"] # alias expansion
1113 }</pre>
1114 </div>
1115 </div>
1116 </dd>
1117 <dt class="hdlist1">"child_start"</dt>
1118 <dd>
1119 <p>This event describes a child process that is about to be
1120 spawned.</p>
1121 <div class="listingblock">
1122 <div class="content">
1123 <pre>{
1124         "event":"child_start",
1125         ...
1126         "child_id":2,
1127         "child_class":"?",
1128         "use_shell":false,
1129         "argv":["git","rev-list","--objects","--stdin","--not","--all","--quiet"]
1130
1131         "hook_name":"&lt;hook_name&gt;"  # present when child_class is "hook"
1132         "cd":"&lt;path&gt;"              # present when cd is required
1133 }</pre>
1134 </div>
1135 </div>
1136 <div class="paragraph">
1137 <p>The "child_id" field can be used to match this child_start with the
1138 corresponding child_exit event.</p>
1139 </div>
1140 <div class="paragraph">
1141 <p>The "child_class" field is a rough classification, such as "editor",
1142 "pager", "transport/*", and "hook".  Unclassified children are classified
1143 with "?".</p>
1144 </div>
1145 </dd>
1146 <dt class="hdlist1">"child_exit"</dt>
1147 <dd>
1148 <p>This event is generated after the current process has returned
1149 from the <code>waitpid</code>() and collected the exit information from the
1150 child.</p>
1151 <div class="listingblock">
1152 <div class="content">
1153 <pre>{
1154         "event":"child_exit",
1155         ...
1156         "child_id":2,
1157         "pid":14708,     # child PID
1158         "code":0,        # child exit-code
1159         "t_rel":0.110605 # observed run-time of child process
1160 }</pre>
1161 </div>
1162 </div>
1163 <div class="paragraph">
1164 <p>Note that the session-id of the child process is not available to
1165 the current/spawning process, so the child&#8217;s PID is reported here as
1166 a hint for post-processing.  (But it is only a hint because the child
1167 process may be a shell script which doesn&#8217;t have a session-id.)</p>
1168 </div>
1169 <div class="paragraph">
1170 <p>Note that the <code>t_rel</code> field contains the observed run time in seconds
1171 for the child process (starting before the fork/exec/spawn and
1172 stopping after the <code>waitpid</code>() and includes OS process creation overhead).
1173 So this time will be slightly larger than the atexit time reported by
1174 the child process itself.</p>
1175 </div>
1176 </dd>
1177 <dt class="hdlist1">"child_ready"</dt>
1178 <dd>
1179 <p>This event is generated after the current process has started
1180 a background process and released all handles to it.</p>
1181 <div class="listingblock">
1182 <div class="content">
1183 <pre>{
1184         "event":"child_ready",
1185         ...
1186         "child_id":2,
1187         "pid":14708,     # child PID
1188         "ready":"ready", # child ready state
1189         "t_rel":0.110605 # observed run-time of child process
1190 }</pre>
1191 </div>
1192 </div>
1193 <div class="paragraph">
1194 <p>Note that the session-id of the child process is not available to
1195 the current/spawning process, so the child&#8217;s PID is reported here as
1196 a hint for post-processing.  (But it is only a hint because the child
1197 process may be a shell script which doesn&#8217;t have a session-id.)</p>
1198 </div>
1199 <div class="paragraph">
1200 <p>This event is generated after the child is started in the background
1201 and given a little time to boot up and start working.  If the child
1202 starts up normally while the parent is still waiting, the "ready"
1203 field will have the value "ready".
1204 If the child is too slow to start and the parent times out, the field
1205 will have the value "timeout".
1206 If the child starts but the parent is unable to probe it, the field
1207 will have the value "error".</p>
1208 </div>
1209 <div class="paragraph">
1210 <p>After the parent process emits this event, it will release all of its
1211 handles to the child process and treat the child as a background
1212 daemon.  So even if the child does eventually finish booting up,
1213 the parent will not emit an updated event.</p>
1214 </div>
1215 <div class="paragraph">
1216 <p>Note that the <code>t_rel</code> field contains the observed run time in seconds
1217 when the parent released the child process into the background.
1218 The child is assumed to be a long-running daemon process and may
1219 outlive the parent process.  So the parent&#8217;s child event times should
1220 not be compared to the child&#8217;s atexit times.</p>
1221 </div>
1222 </dd>
1223 <dt class="hdlist1">"exec"</dt>
1224 <dd>
1225 <p>This event is generated before git attempts to <code>exec</code>()
1226 another command rather than starting a child process.</p>
1227 <div class="listingblock">
1228 <div class="content">
1229 <pre>{
1230         "event":"exec",
1231         ...
1232         "exec_id":0,
1233         "exe":"git",
1234         "argv":["foo", "bar"]
1235 }</pre>
1236 </div>
1237 </div>
1238 <div class="paragraph">
1239 <p>The "exec_id" field is a command-unique id and is only useful if the
1240 <code>exec</code>() fails and a corresponding exec_result event is generated.</p>
1241 </div>
1242 </dd>
1243 <dt class="hdlist1">"exec_result"</dt>
1244 <dd>
1245 <p>This event is generated if the <code>exec</code>() fails and control
1246 returns to the current git command.</p>
1247 <div class="listingblock">
1248 <div class="content">
1249 <pre>{
1250         "event":"exec_result",
1251         ...
1252         "exec_id":0,
1253         "code":1      # error code (errno) from exec()
1254 }</pre>
1255 </div>
1256 </div>
1257 </dd>
1258 <dt class="hdlist1">"thread_start"</dt>
1259 <dd>
1260 <p>This event is generated when a thread is started.  It is
1261 generated from <strong>within</strong> the new thread&#8217;s thread-proc (because
1262 it needs to access data in the thread&#8217;s thread-local storage).</p>
1263 <div class="listingblock">
1264 <div class="content">
1265 <pre>{
1266         "event":"thread_start",
1267         ...
1268         "thread":"th02:preload_thread" # thread name
1269 }</pre>
1270 </div>
1271 </div>
1272 </dd>
1273 <dt class="hdlist1">"thread_exit"</dt>
1274 <dd>
1275 <p>This event is generated when a thread exits.  It is generated
1276 from <strong>within</strong> the thread&#8217;s thread-proc.</p>
1277 <div class="listingblock">
1278 <div class="content">
1279 <pre>{
1280         "event":"thread_exit",
1281         ...
1282         "thread":"th02:preload_thread", # thread name
1283         "t_rel":0.007328                # thread elapsed time
1284 }</pre>
1285 </div>
1286 </div>
1287 </dd>
1288 <dt class="hdlist1">"def_param"</dt>
1289 <dd>
1290 <p>This event is generated to log a global parameter, such as a config
1291 setting, command-line flag, or environment variable.</p>
1292 <div class="listingblock">
1293 <div class="content">
1294 <pre>{
1295         "event":"def_param",
1296         ...
1297         "scope":"global",
1298         "param":"core.abbrev",
1299         "value":"7"
1300 }</pre>
1301 </div>
1302 </div>
1303 </dd>
1304 <dt class="hdlist1">"def_repo"</dt>
1305 <dd>
1306 <p>This event defines a repo-id and associates it with the root
1307 of the worktree.</p>
1308 <div class="listingblock">
1309 <div class="content">
1310 <pre>{
1311         "event":"def_repo",
1312         ...
1313         "repo":1,
1314         "worktree":"/Users/jeffhost/work/gfw"
1315 }</pre>
1316 </div>
1317 </div>
1318 <div class="paragraph">
1319 <p>As stated earlier, the repo-id is currently always 1, so there will
1320 only be one def_repo event.  Later, if in-proc submodules are
1321 supported, a def_repo event should be emitted for each submodule
1322 visited.</p>
1323 </div>
1324 </dd>
1325 <dt class="hdlist1">"region_enter"</dt>
1326 <dd>
1327 <p>This event is generated when entering a region.</p>
1328 <div class="listingblock">
1329 <div class="content">
1330 <pre>{
1331         "event":"region_enter",
1332         ...
1333         "repo":1,                # optional
1334         "nesting":1,             # current region stack depth
1335         "category":"index",      # optional
1336         "label":"do_read_index", # optional
1337         "msg":".git/index"       # optional
1338 }</pre>
1339 </div>
1340 </div>
1341 <div class="paragraph">
1342 <p>The <code>category</code> field may be used in a future enhancement to
1343 do category-based filtering.</p>
1344 </div>
1345 <div class="paragraph">
1346 <p><code>GIT_TRACE2_EVENT_NESTING</code> or <code>trace2.eventNesting</code> can be used to
1347 filter deeply nested regions and data events.  It defaults to "2".</p>
1348 </div>
1349 </dd>
1350 <dt class="hdlist1">"region_leave"</dt>
1351 <dd>
1352 <p>This event is generated when leaving a region.</p>
1353 <div class="listingblock">
1354 <div class="content">
1355 <pre>{
1356         "event":"region_leave",
1357         ...
1358         "repo":1,                # optional
1359         "t_rel":0.002876,        # time spent in region in seconds
1360         "nesting":1,             # region stack depth
1361         "category":"index",      # optional
1362         "label":"do_read_index", # optional
1363         "msg":".git/index"       # optional
1364 }</pre>
1365 </div>
1366 </div>
1367 </dd>
1368 <dt class="hdlist1">"data"</dt>
1369 <dd>
1370 <p>This event is generated to log a thread- and region-local
1371 key/value pair.</p>
1372 <div class="listingblock">
1373 <div class="content">
1374 <pre>{
1375         "event":"data",
1376         ...
1377         "repo":1,              # optional
1378         "t_abs":0.024107,      # absolute elapsed time
1379         "t_rel":0.001031,      # elapsed time in region/thread
1380         "nesting":2,           # region stack depth
1381         "category":"index",
1382         "key":"read/cache_nr",
1383         "value":"3552"
1384 }</pre>
1385 </div>
1386 </div>
1387 <div class="paragraph">
1388 <p>The "value" field may be an integer or a string.</p>
1389 </div>
1390 </dd>
1391 <dt class="hdlist1">"data-json"</dt>
1392 <dd>
1393 <p>This event is generated to log a pre-formatted JSON string
1394 containing structured data.</p>
1395 <div class="listingblock">
1396 <div class="content">
1397 <pre>{
1398         "event":"data_json",
1399         ...
1400         "repo":1,              # optional
1401         "t_abs":0.015905,
1402         "t_rel":0.015905,
1403         "nesting":1,
1404         "category":"process",
1405         "key":"windows/ancestry",
1406         "value":["bash.exe","bash.exe"]
1407 }</pre>
1408 </div>
1409 </div>
1410 </dd>
1411 <dt class="hdlist1">"th_timer"</dt>
1412 <dd>
1413 <p>This event logs the amount of time that a stopwatch timer was
1414 running in the thread.  This event is generated when a thread
1415 exits for timers that requested per-thread events.</p>
1416 <div class="listingblock">
1417 <div class="content">
1418 <pre>{
1419         "event":"th_timer",
1420         ...
1421         "category":"my_category",
1422         "name":"my_timer",
1423         "intervals":5,         # number of time it was started/stopped
1424         "t_total":0.052741,    # total time in seconds it was running
1425         "t_min":0.010061,      # shortest interval
1426         "t_max":0.011648       # longest interval
1427 }</pre>
1428 </div>
1429 </div>
1430 </dd>
1431 <dt class="hdlist1">"timer"</dt>
1432 <dd>
1433 <p>This event logs the amount of time that a stopwatch timer was
1434 running aggregated across all threads.  This event is generated
1435 when the process exits.</p>
1436 <div class="listingblock">
1437 <div class="content">
1438 <pre>{
1439         "event":"timer",
1440         ...
1441         "category":"my_category",
1442         "name":"my_timer",
1443         "intervals":5,         # number of time it was started/stopped
1444         "t_total":0.052741,    # total time in seconds it was running
1445         "t_min":0.010061,      # shortest interval
1446         "t_max":0.011648       # longest interval
1447 }</pre>
1448 </div>
1449 </div>
1450 </dd>
1451 <dt class="hdlist1">"th_counter"</dt>
1452 <dd>
1453 <p>This event logs the value of a counter variable in a thread.
1454 This event is generated when a thread exits for counters that
1455 requested per-thread events.</p>
1456 <div class="listingblock">
1457 <div class="content">
1458 <pre>{
1459         "event":"th_counter",
1460         ...
1461         "category":"my_category",
1462         "name":"my_counter",
1463         "count":23
1464 }</pre>
1465 </div>
1466 </div>
1467 </dd>
1468 <dt class="hdlist1">"counter"</dt>
1469 <dd>
1470 <p>This event logs the value of a counter variable across all threads.
1471 This event is generated when the process exits.  The total value
1472 reported here is the sum across all threads.</p>
1473 <div class="listingblock">
1474 <div class="content">
1475 <pre>{
1476         "event":"counter",
1477         ...
1478         "category":"my_category",
1479         "name":"my_counter",
1480         "count":23
1481 }</pre>
1482 </div>
1483 </div>
1484 </dd>
1485 <dt class="hdlist1">"printf"</dt>
1486 <dd>
1487 <p>This event logs a human-readable message with no particular formatting
1488 guidelines.</p>
1489 <div class="listingblock">
1490 <div class="content">
1491 <pre>{
1492         "event":"printf",
1493         ...
1494         "t_abs":0.015905,      # elapsed time in seconds
1495         "msg":"Hello world"    # optional
1496 }</pre>
1497 </div>
1498 </div>
1499 </dd>
1500 </dl>
1501 </div>
1502 </div>
1503 </div>
1504 </div>
1505 </div>
1506 <div class="sect1">
1507 <h2 id="_example_trace2_api_usage">Example Trace2 API Usage</h2>
1508 <div class="sectionbody">
1509 <div class="paragraph">
1510 <p>Here is a hypothetical usage of the Trace2 API showing the intended
1511 usage (without worrying about the actual Git details).</p>
1512 </div>
1513 <div class="dlist">
1514 <dl>
1515 <dt class="hdlist1">Initialization</dt>
1516 <dd>
1517 <p>Initialization happens in <code>main</code>().  Behind the scenes, an
1518 <code>atexit</code> and <code>signal</code> handler are registered.</p>
1519 <div class="listingblock">
1520 <div class="content">
1521 <pre>int main(int argc, const char **argv)
1522 {
1523         int exit_code;
1524
1525         trace2_initialize();
1526         trace2_cmd_start(argv);
1527
1528         exit_code = cmd_main(argc, argv);
1529
1530         trace2_cmd_exit(exit_code);
1531
1532         return exit_code;
1533 }</pre>
1534 </div>
1535 </div>
1536 </dd>
1537 <dt class="hdlist1">Command Details</dt>
1538 <dd>
1539 <p>After the basics are established, additional command
1540 information can be sent to Trace2 as it is discovered.</p>
1541 <div class="listingblock">
1542 <div class="content">
1543 <pre>int cmd_checkout(int argc, const char **argv)
1544 {
1545         trace2_cmd_name("checkout");
1546         trace2_cmd_mode("branch");
1547         trace2_def_repo(the_repository);
1548
1549         // emit "def_param" messages for "interesting" config settings.
1550         trace2_cmd_list_config();
1551
1552         if (do_something())
1553             trace2_cmd_error("Path '%s': cannot do something", path);
1554
1555         return 0;
1556 }</pre>
1557 </div>
1558 </div>
1559 </dd>
1560 <dt class="hdlist1">Child Processes</dt>
1561 <dd>
1562 <p>Wrap code spawning child processes.</p>
1563 <div class="listingblock">
1564 <div class="content">
1565 <pre>void run_child(...)
1566 {
1567         int child_exit_code;
1568         struct child_process cmd = CHILD_PROCESS_INIT;
1569         ...
1570         cmd.trace2_child_class = "editor";
1571
1572         trace2_child_start(&amp;cmd);
1573         child_exit_code = spawn_child_and_wait_for_it();
1574         trace2_child_exit(&amp;cmd, child_exit_code);
1575 }</pre>
1576 </div>
1577 </div>
1578 <div class="paragraph">
1579 <p>For example, the following fetch command spawned ssh, index-pack,
1580 rev-list, and gc.  This example also shows that fetch took
1581 5.199 seconds and of that 4.932 was in ssh.</p>
1582 </div>
1583 <div class="listingblock">
1584 <div class="content">
1585 <pre>$ export GIT_TRACE2_BRIEF=1
1586 $ export GIT_TRACE2=~/log.normal
1587 $ git fetch origin
1588 ...</pre>
1589 </div>
1590 </div>
1591 <div class="listingblock">
1592 <div class="content">
1593 <pre>$ cat ~/log.normal
1594 version 2.20.1.vfs.1.1.47.g534dbe1ad1
1595 start git fetch origin
1596 worktree /Users/jeffhost/work/gfw
1597 cmd_name fetch (fetch)
1598 child_start[0] ssh git@github.com ...
1599 child_start[1] git index-pack ...
1600 ... (Trace2 events from child processes omitted)
1601 child_exit[1] pid:14707 code:0 elapsed:0.076353
1602 child_exit[0] pid:14706 code:0 elapsed:4.931869
1603 child_start[2] git rev-list ...
1604 ... (Trace2 events from child process omitted)
1605 child_exit[2] pid:14708 code:0 elapsed:0.110605
1606 child_start[3] git gc --auto
1607 ... (Trace2 events from child process omitted)
1608 child_exit[3] pid:14709 code:0 elapsed:0.006240
1609 exit elapsed:5.198503 code:0
1610 atexit elapsed:5.198541 code:0</pre>
1611 </div>
1612 </div>
1613 <div class="paragraph">
1614 <p>When a git process is a (direct or indirect) child of another
1615 git process, it inherits Trace2 context information.  This
1616 allows the child to print the command hierarchy.  This example
1617 shows gc as child[3] of fetch.  When the gc process reports
1618 its name as "gc", it also reports the hierarchy as "fetch/gc".
1619 (In this example, trace2 messages from the child process is
1620 indented for clarity.)</p>
1621 </div>
1622 <div class="listingblock">
1623 <div class="content">
1624 <pre>$ export GIT_TRACE2_BRIEF=1
1625 $ export GIT_TRACE2=~/log.normal
1626 $ git fetch origin
1627 ...</pre>
1628 </div>
1629 </div>
1630 <div class="listingblock">
1631 <div class="content">
1632 <pre>$ cat ~/log.normal
1633 version 2.20.1.160.g5676107ecd.dirty
1634 start git fetch official
1635 worktree /Users/jeffhost/work/gfw
1636 cmd_name fetch (fetch)
1637 ...
1638 child_start[3] git gc --auto
1639     version 2.20.1.160.g5676107ecd.dirty
1640     start /Users/jeffhost/work/gfw/git gc --auto
1641     worktree /Users/jeffhost/work/gfw
1642     cmd_name gc (fetch/gc)
1643     exit elapsed:0.001959 code:0
1644     atexit elapsed:0.001997 code:0
1645 child_exit[3] pid:20303 code:0 elapsed:0.007564
1646 exit elapsed:3.868938 code:0
1647 atexit elapsed:3.868970 code:0</pre>
1648 </div>
1649 </div>
1650 </dd>
1651 <dt class="hdlist1">Regions</dt>
1652 <dd>
1653 <p>Regions can be used to time an interesting section of code.</p>
1654 <div class="listingblock">
1655 <div class="content">
1656 <pre>void wt_status_collect(struct wt_status *s)
1657 {
1658         trace2_region_enter("status", "worktrees", s-&gt;repo);
1659         wt_status_collect_changes_worktree(s);
1660         trace2_region_leave("status", "worktrees", s-&gt;repo);
1661
1662         trace2_region_enter("status", "index", s-&gt;repo);
1663         wt_status_collect_changes_index(s);
1664         trace2_region_leave("status", "index", s-&gt;repo);
1665
1666         trace2_region_enter("status", "untracked", s-&gt;repo);
1667         wt_status_collect_untracked(s);
1668         trace2_region_leave("status", "untracked", s-&gt;repo);
1669 }
1670
1671 void wt_status_print(struct wt_status *s)
1672 {
1673         trace2_region_enter("status", "print", s-&gt;repo);
1674         switch (s-&gt;status_format) {
1675             ...
1676         }
1677         trace2_region_leave("status", "print", s-&gt;repo);
1678 }</pre>
1679 </div>
1680 </div>
1681 <div class="paragraph">
1682 <p>In this example, scanning for untracked files ran from +0.012568 to
1683 +0.027149 (since the process started) and took 0.014581 seconds.</p>
1684 </div>
1685 <div class="listingblock">
1686 <div class="content">
1687 <pre>$ export GIT_TRACE2_PERF_BRIEF=1
1688 $ export GIT_TRACE2_PERF=~/log.perf
1689 $ git status
1690 ...
1691
1692 $ cat ~/log.perf
1693 d0 | main                     | version      |     |           |           |            | 2.20.1.160.g5676107ecd.dirty
1694 d0 | main                     | start        |     |  0.001173 |           |            | git status
1695 d0 | main                     | def_repo     | r1  |           |           |            | worktree:/Users/jeffhost/work/gfw
1696 d0 | main                     | cmd_name     |     |           |           |            | status (status)
1697 ...
1698 d0 | main                     | region_enter | r1  |  0.010988 |           | status     | label:worktrees
1699 d0 | main                     | region_leave | r1  |  0.011236 |  0.000248 | status     | label:worktrees
1700 d0 | main                     | region_enter | r1  |  0.011260 |           | status     | label:index
1701 d0 | main                     | region_leave | r1  |  0.012542 |  0.001282 | status     | label:index
1702 d0 | main                     | region_enter | r1  |  0.012568 |           | status     | label:untracked
1703 d0 | main                     | region_leave | r1  |  0.027149 |  0.014581 | status     | label:untracked
1704 d0 | main                     | region_enter | r1  |  0.027411 |           | status     | label:print
1705 d0 | main                     | region_leave | r1  |  0.028741 |  0.001330 | status     | label:print
1706 d0 | main                     | exit         |     |  0.028778 |           |            | code:0
1707 d0 | main                     | atexit       |     |  0.028809 |           |            | code:0</pre>
1708 </div>
1709 </div>
1710 <div class="paragraph">
1711 <p>Regions may be nested.  This causes messages to be indented in the
1712 PERF target, for example.
1713 Elapsed times are relative to the start of the corresponding nesting
1714 level as expected.  For example, if we add region message to:</p>
1715 </div>
1716 <div class="listingblock">
1717 <div class="content">
1718 <pre>static enum path_treatment read_directory_recursive(struct dir_struct *dir,
1719         struct index_state *istate, const char *base, int baselen,
1720         struct untracked_cache_dir *untracked, int check_only,
1721         int stop_at_first_file, const struct pathspec *pathspec)
1722 {
1723         enum path_treatment state, subdir_state, dir_state = path_none;
1724
1725         trace2_region_enter_printf("dir", "read_recursive", NULL, "%.*s", baselen, base);
1726         ...
1727         trace2_region_leave_printf("dir", "read_recursive", NULL, "%.*s", baselen, base);
1728         return dir_state;
1729 }</pre>
1730 </div>
1731 </div>
1732 <div class="paragraph">
1733 <p>We can further investigate the time spent scanning for untracked files.</p>
1734 </div>
1735 <div class="listingblock">
1736 <div class="content">
1737 <pre>$ export GIT_TRACE2_PERF_BRIEF=1
1738 $ export GIT_TRACE2_PERF=~/log.perf
1739 $ git status
1740 ...
1741 $ cat ~/log.perf
1742 d0 | main                     | version      |     |           |           |            | 2.20.1.162.gb4ccea44db.dirty
1743 d0 | main                     | start        |     |  0.001173 |           |            | git status
1744 d0 | main                     | def_repo     | r1  |           |           |            | worktree:/Users/jeffhost/work/gfw
1745 d0 | main                     | cmd_name     |     |           |           |            | status (status)
1746 ...
1747 d0 | main                     | region_enter | r1  |  0.015047 |           | status     | label:untracked
1748 d0 | main                     | region_enter |     |  0.015132 |           | dir        | ..label:read_recursive
1749 d0 | main                     | region_enter |     |  0.016341 |           | dir        | ....label:read_recursive vcs-svn/
1750 d0 | main                     | region_leave |     |  0.016422 |  0.000081 | dir        | ....label:read_recursive vcs-svn/
1751 d0 | main                     | region_enter |     |  0.016446 |           | dir        | ....label:read_recursive xdiff/
1752 d0 | main                     | region_leave |     |  0.016522 |  0.000076 | dir        | ....label:read_recursive xdiff/
1753 d0 | main                     | region_enter |     |  0.016612 |           | dir        | ....label:read_recursive git-gui/
1754 d0 | main                     | region_enter |     |  0.016698 |           | dir        | ......label:read_recursive git-gui/po/
1755 d0 | main                     | region_enter |     |  0.016810 |           | dir        | ........label:read_recursive git-gui/po/glossary/
1756 d0 | main                     | region_leave |     |  0.016863 |  0.000053 | dir        | ........label:read_recursive git-gui/po/glossary/
1757 ...
1758 d0 | main                     | region_enter |     |  0.031876 |           | dir        | ....label:read_recursive builtin/
1759 d0 | main                     | region_leave |     |  0.032270 |  0.000394 | dir        | ....label:read_recursive builtin/
1760 d0 | main                     | region_leave |     |  0.032414 |  0.017282 | dir        | ..label:read_recursive
1761 d0 | main                     | region_leave | r1  |  0.032454 |  0.017407 | status     | label:untracked
1762 ...
1763 d0 | main                     | exit         |     |  0.034279 |           |            | code:0
1764 d0 | main                     | atexit       |     |  0.034322 |           |            | code:0</pre>
1765 </div>
1766 </div>
1767 <div class="paragraph">
1768 <p>Trace2 regions are similar to the existing trace_performance_enter()
1769 and trace_performance_leave() routines, but are thread safe and
1770 maintain per-thread stacks of timers.</p>
1771 </div>
1772 </dd>
1773 <dt class="hdlist1">Data Messages</dt>
1774 <dd>
1775 <p>Data messages added to a region.</p>
1776 <div class="listingblock">
1777 <div class="content">
1778 <pre>int read_index_from(struct index_state *istate, const char *path,
1779         const char *gitdir)
1780 {
1781         trace2_region_enter_printf("index", "do_read_index", the_repository, "%s", path);
1782
1783         ...
1784
1785         trace2_data_intmax("index", the_repository, "read/version", istate-&gt;version);
1786         trace2_data_intmax("index", the_repository, "read/cache_nr", istate-&gt;cache_nr);
1787
1788         trace2_region_leave_printf("index", "do_read_index", the_repository, "%s", path);
1789 }</pre>
1790 </div>
1791 </div>
1792 <div class="paragraph">
1793 <p>This example shows that the index contained 3552 entries.</p>
1794 </div>
1795 <div class="listingblock">
1796 <div class="content">
1797 <pre>$ export GIT_TRACE2_PERF_BRIEF=1
1798 $ export GIT_TRACE2_PERF=~/log.perf
1799 $ git status
1800 ...
1801 $ cat ~/log.perf
1802 d0 | main                     | version      |     |           |           |            | 2.20.1.156.gf9916ae094.dirty
1803 d0 | main                     | start        |     |  0.001173 |           |            | git status
1804 d0 | main                     | def_repo     | r1  |           |           |            | worktree:/Users/jeffhost/work/gfw
1805 d0 | main                     | cmd_name     |     |           |           |            | status (status)
1806 d0 | main                     | region_enter | r1  |  0.001791 |           | index      | label:do_read_index .git/index
1807 d0 | main                     | data         | r1  |  0.002494 |  0.000703 | index      | ..read/version:2
1808 d0 | main                     | data         | r1  |  0.002520 |  0.000729 | index      | ..read/cache_nr:3552
1809 d0 | main                     | region_leave | r1  |  0.002539 |  0.000748 | index      | label:do_read_index .git/index
1810 ...</pre>
1811 </div>
1812 </div>
1813 </dd>
1814 <dt class="hdlist1">Thread Events</dt>
1815 <dd>
1816 <p>Thread messages added to a thread-proc.</p>
1817 <div class="paragraph">
1818 <p>For example, the multi-threaded preload-index code can be
1819 instrumented with a region around the thread pool and then
1820 per-thread start and exit events within the thread-proc.</p>
1821 </div>
1822 <div class="listingblock">
1823 <div class="content">
1824 <pre>static void *preload_thread(void *_data)
1825 {
1826         // start the per-thread clock and emit a message.
1827         trace2_thread_start("preload_thread");
1828
1829         // report which chunk of the array this thread was assigned.
1830         trace2_data_intmax("index", the_repository, "offset", p-&gt;offset);
1831         trace2_data_intmax("index", the_repository, "count", nr);
1832
1833         do {
1834             ...
1835         } while (--nr &gt; 0);
1836         ...
1837
1838         // report elapsed time taken by this thread.
1839         trace2_thread_exit();
1840         return NULL;
1841 }
1842
1843 void preload_index(struct index_state *index,
1844         const struct pathspec *pathspec,
1845         unsigned int refresh_flags)
1846 {
1847         trace2_region_enter("index", "preload", the_repository);
1848
1849         for (i = 0; i &lt; threads; i++) {
1850             ... /* create thread */
1851         }
1852
1853         for (i = 0; i &lt; threads; i++) {
1854             ... /* join thread */
1855         }
1856
1857         trace2_region_leave("index", "preload", the_repository);
1858 }</pre>
1859 </div>
1860 </div>
1861 <div class="paragraph">
1862 <p>In this example preload_index() was executed by the <code>main</code> thread
1863 and started the <code>preload</code> region.  Seven threads, named
1864 <code>th01:preload_thread</code> through <code>th07:preload_thread</code>, were started.
1865 Events from each thread are atomically appended to the shared target
1866 stream as they occur so they may appear in random order with respect
1867 other threads. Finally, the main thread waits for the threads to
1868 finish and leaves the region.</p>
1869 </div>
1870 <div class="paragraph">
1871 <p>Data events are tagged with the active thread name.  They are used
1872 to report the per-thread parameters.</p>
1873 </div>
1874 <div class="listingblock">
1875 <div class="content">
1876 <pre>$ export GIT_TRACE2_PERF_BRIEF=1
1877 $ export GIT_TRACE2_PERF=~/log.perf
1878 $ git status
1879 ...
1880 $ cat ~/log.perf
1881 ...
1882 d0 | main                     | region_enter | r1  |  0.002595 |           | index      | label:preload
1883 d0 | th01:preload_thread      | thread_start |     |  0.002699 |           |            |
1884 d0 | th02:preload_thread      | thread_start |     |  0.002721 |           |            |
1885 d0 | th01:preload_thread      | data         | r1  |  0.002736 |  0.000037 | index      | offset:0
1886 d0 | th02:preload_thread      | data         | r1  |  0.002751 |  0.000030 | index      | offset:2032
1887 d0 | th03:preload_thread      | thread_start |     |  0.002711 |           |            |
1888 d0 | th06:preload_thread      | thread_start |     |  0.002739 |           |            |
1889 d0 | th01:preload_thread      | data         | r1  |  0.002766 |  0.000067 | index      | count:508
1890 d0 | th06:preload_thread      | data         | r1  |  0.002856 |  0.000117 | index      | offset:2540
1891 d0 | th03:preload_thread      | data         | r1  |  0.002824 |  0.000113 | index      | offset:1016
1892 d0 | th04:preload_thread      | thread_start |     |  0.002710 |           |            |
1893 d0 | th02:preload_thread      | data         | r1  |  0.002779 |  0.000058 | index      | count:508
1894 d0 | th06:preload_thread      | data         | r1  |  0.002966 |  0.000227 | index      | count:508
1895 d0 | th07:preload_thread      | thread_start |     |  0.002741 |           |            |
1896 d0 | th07:preload_thread      | data         | r1  |  0.003017 |  0.000276 | index      | offset:3048
1897 d0 | th05:preload_thread      | thread_start |     |  0.002712 |           |            |
1898 d0 | th05:preload_thread      | data         | r1  |  0.003067 |  0.000355 | index      | offset:1524
1899 d0 | th05:preload_thread      | data         | r1  |  0.003090 |  0.000378 | index      | count:508
1900 d0 | th07:preload_thread      | data         | r1  |  0.003037 |  0.000296 | index      | count:504
1901 d0 | th03:preload_thread      | data         | r1  |  0.002971 |  0.000260 | index      | count:508
1902 d0 | th04:preload_thread      | data         | r1  |  0.002983 |  0.000273 | index      | offset:508
1903 d0 | th04:preload_thread      | data         | r1  |  0.007311 |  0.004601 | index      | count:508
1904 d0 | th05:preload_thread      | thread_exit  |     |  0.008781 |  0.006069 |            |
1905 d0 | th01:preload_thread      | thread_exit  |     |  0.009561 |  0.006862 |            |
1906 d0 | th03:preload_thread      | thread_exit  |     |  0.009742 |  0.007031 |            |
1907 d0 | th06:preload_thread      | thread_exit  |     |  0.009820 |  0.007081 |            |
1908 d0 | th02:preload_thread      | thread_exit  |     |  0.010274 |  0.007553 |            |
1909 d0 | th07:preload_thread      | thread_exit  |     |  0.010477 |  0.007736 |            |
1910 d0 | th04:preload_thread      | thread_exit  |     |  0.011657 |  0.008947 |            |
1911 d0 | main                     | region_leave | r1  |  0.011717 |  0.009122 | index      | label:preload
1912 ...
1913 d0 | main                     | exit         |     |  0.029996 |           |            | code:0
1914 d0 | main                     | atexit       |     |  0.030027 |           |            | code:0</pre>
1915 </div>
1916 </div>
1917 <div class="paragraph">
1918 <p>In this example, the preload region took 0.009122 seconds.  The 7 threads
1919 took between 0.006069 and 0.008947 seconds to work on their portion of
1920 the index.  Thread "th01" worked on 508 items at offset 0.  Thread "th02"
1921 worked on 508 items at offset 2032.  Thread "th04" worked on 508 items
1922 at offset 508.</p>
1923 </div>
1924 <div class="paragraph">
1925 <p>This example also shows that thread names are assigned in a racy manner
1926 as each thread starts.</p>
1927 </div>
1928 </dd>
1929 <dt class="hdlist1">Config (def param) Events</dt>
1930 <dd>
1931 <p>Dump "interesting" config values to trace2 log.</p>
1932 <div class="paragraph">
1933 <p>We can optionally emit configuration events, see
1934 <code>trace2.configparams</code> in <a href="../git-config.html">git-config(1)</a> for how to enable
1935 it.</p>
1936 </div>
1937 <div class="listingblock">
1938 <div class="content">
1939 <pre>$ git config --system color.ui never
1940 $ git config --global color.ui always
1941 $ git config --local color.ui auto
1942 $ git config --list --show-scope | grep 'color.ui'
1943 system  color.ui=never
1944 global  color.ui=always
1945 local   color.ui=auto</pre>
1946 </div>
1947 </div>
1948 <div class="paragraph">
1949 <p>Then, mark the config <code>color.ui</code> as "interesting" config with
1950 <code>GIT_TRACE2_CONFIG_PARAMS</code>:</p>
1951 </div>
1952 <div class="listingblock">
1953 <div class="content">
1954 <pre>$ export GIT_TRACE2_PERF_BRIEF=1
1955 $ export GIT_TRACE2_PERF=~/log.perf
1956 $ export GIT_TRACE2_CONFIG_PARAMS=color.ui
1957 $ git version
1958 ...
1959 $ cat ~/log.perf
1960 d0 | main                     | version      |     |           |           |              | ...
1961 d0 | main                     | start        |     |  0.001642 |           |              | /usr/local/bin/git version
1962 d0 | main                     | cmd_name     |     |           |           |              | version (version)
1963 d0 | main                     | def_param    |     |           |           | scope:system | color.ui:never
1964 d0 | main                     | def_param    |     |           |           | scope:global | color.ui:always
1965 d0 | main                     | def_param    |     |           |           | scope:local  | color.ui:auto
1966 d0 | main                     | data         | r0  |  0.002100 |  0.002100 | fsync        | fsync/writeout-only:0
1967 d0 | main                     | data         | r0  |  0.002126 |  0.002126 | fsync        | fsync/hardware-flush:0
1968 d0 | main                     | exit         |     |  0.000470 |           |              | code:0
1969 d0 | main                     | atexit       |     |  0.000477 |           |              | code:0</pre>
1970 </div>
1971 </div>
1972 </dd>
1973 <dt class="hdlist1">Stopwatch Timer Events</dt>
1974 <dd>
1975 <p>Measure the time spent in a function call or span of code
1976 that might be called from many places within the code
1977 throughout the life of the process.</p>
1978 <div class="listingblock">
1979 <div class="content">
1980 <pre>static void expensive_function(void)
1981 {
1982         trace2_timer_start(TRACE2_TIMER_ID_TEST1);
1983         ...
1984         sleep_millisec(1000); // Do something expensive
1985         ...
1986         trace2_timer_stop(TRACE2_TIMER_ID_TEST1);
1987 }
1988
1989 static int ut_100timer(int argc, const char **argv)
1990 {
1991         ...
1992
1993         expensive_function();
1994
1995         // Do something else 1...
1996
1997         expensive_function();
1998
1999         // Do something else 2...
2000
2001         expensive_function();
2002
2003         return 0;
2004 }</pre>
2005 </div>
2006 </div>
2007 <div class="paragraph">
2008 <p>In this example, we measure the total time spent in
2009 <code>expensive_function</code>() regardless of when it is called
2010 in the overall flow of the program.</p>
2011 </div>
2012 <div class="listingblock">
2013 <div class="content">
2014 <pre>$ export GIT_TRACE2_PERF_BRIEF=1
2015 $ export GIT_TRACE2_PERF=~/log.perf
2016 $ t/helper/test-tool trace2 100timer 3 1000
2017 ...
2018 $ cat ~/log.perf
2019 d0 | main                     | version      |     |           |           |              | ...
2020 d0 | main                     | start        |     |  0.001453 |           |              | t/helper/test-tool trace2 100timer 3 1000
2021 d0 | main                     | cmd_name     |     |           |           |              | trace2 (trace2)
2022 d0 | main                     | exit         |     |  3.003667 |           |              | code:0
2023 d0 | main                     | timer        |     |           |           | test         | name:test1 intervals:3 total:3.001686 min:1.000254 max:1.000929
2024 d0 | main                     | atexit       |     |  3.003796 |           |              | code:0</pre>
2025 </div>
2026 </div>
2027 </dd>
2028 </dl>
2029 </div>
2030 </div>
2031 </div>
2032 <div class="sect1">
2033 <h2 id="_future_work">Future Work</h2>
2034 <div class="sectionbody">
2035 <div class="sect2">
2036 <h3 id="_relationship_to_the_existing_trace_api_api_trace_txt">Relationship to the Existing Trace Api (api-trace.txt)</h3>
2037 <div class="paragraph">
2038 <p>There are a few issues to resolve before we can completely
2039 switch to Trace2.</p>
2040 </div>
2041 <div class="ulist">
2042 <ul>
2043 <li>
2044 <p>Updating existing tests that assume <code>GIT_TRACE</code> format messages.</p>
2045 </li>
2046 <li>
2047 <p>How to best handle custom <code>GIT_TRACE_</code><em>&lt;key&gt;</em> messages?</p>
2048 <div class="ulist">
2049 <ul>
2050 <li>
2051 <p>The <code>GIT_TRACE_</code><em>&lt;key&gt;</em> mechanism allows each &lt;key&gt; to write to a
2052 different file (in addition to just stderr).</p>
2053 </li>
2054 <li>
2055 <p>Do we want to maintain that ability or simply write to the existing
2056 Trace2 targets (and convert &lt;key&gt; to a "category").</p>
2057 </li>
2058 </ul>
2059 </div>
2060 </li>
2061 </ul>
2062 </div>
2063 </div>
2064 </div>
2065 </div>
2066 </div>
2067 <div id="footer">
2068 <div id="footer-text">
2069 Last updated 2024-09-03 13:52:44 -0700
2070 </div>
2071 </div>
2072 </body>
2073 </html>