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>
 440 <div id="content">
 441 <div id="preamble">
 442 <div class="sectionbody">
 443 <div class="paragraph">
 444 <p>The Trace2 API can be used to print debug, performance, and telemetry
 445 information to stderr or a file.  The Trace2 feature is inactive unless
 446 explicitly enabled by enabling one or more Trace2 Targets.</p>
 447 </div>
 448 <div class="paragraph">
 449 <p>The Trace2 API is intended to replace the existing (Trace1)
 450 <code>printf</code>()-style tracing provided by the existing <code>GIT_TRACE</code> and
 451 <code>GIT_TRACE_PERFORMANCE</code> facilities.  During initial implementation,
 452 Trace2 and Trace1 may operate in parallel.</p>
 453 </div>
 454 <div class="paragraph">
 455 <p>The Trace2 API defines a set of high-level messages with known fields,
 456 such as (<code>start</code>: <code>argv</code>) and (<code>exit</code>: {<code>exit-code</code>, <code>elapsed-time</code>}).</p>
 457 </div>
 458 <div class="paragraph">
 459 <p>Trace2 instrumentation throughout the Git code base sends Trace2
 460 messages to the enabled Trace2 Targets.  Targets transform these
 461 messages content into purpose-specific formats and write events to
 462 their data streams.  In this manner, the Trace2 API can drive
 463 many different types of analysis.</p>
 464 </div>
 465 <div class="paragraph">
 466 <p>Targets are defined using a VTable allowing easy extension to other
 467 formats in the future.  This might be used to define a binary format,
 468 for example.</p>
 469 </div>
 470 <div class="paragraph">
 471 <p>Trace2 is controlled using <code>trace2.</code>* config values in the system and
 472 global config files and <code>GIT_TRACE2</code>* environment variables.  Trace2 does
 473 not read from repo local or worktree config files, nor does it respect
 474 <code>-c</code> command line config settings.</p>
 475 </div>
 476 </div>
 477 </div>
 478 <div class="sect1">
 479 <h2 id="_trace2_targets">Trace2 Targets</h2>
 480 <div class="sectionbody">
 481 <div class="paragraph">
 482 <p>Trace2 defines the following set of Trace2 Targets.
 483 Format details are given in a later section.</p>
 484 </div>
 485 <div class="sect2">
 486 <h3 id="_the_normal_format_target">The Normal Format Target</h3>
 487 <div class="paragraph">
 488 <p>The normal format target is a traditional <code>printf</code>() format and similar
 489 to the <code>GIT_TRACE</code> format.  This format is enabled with the <code>GIT_TRACE2</code>
 490 environment variable or the <code>trace2.normalTarget</code> system or global
 491 config setting.</p>
 492 </div>
 493 <div class="paragraph">
 494 <p>For example</p>
 495 </div>
 496 <div class="listingblock">
 497 <div class="content">
 498 <pre>$ export GIT_TRACE2=~/log.normal
 499 $ git version
 500 git version 2.20.1.155.g426c96fcdb</pre>
 501 </div>
 502 </div>
 503 <div class="paragraph">
 504 <p>or</p>
 505 </div>
 506 <div class="listingblock">
 507 <div class="content">
 508 <pre>$ git config --global trace2.normalTarget ~/log.normal
 509 $ git version
 510 git version 2.20.1.155.g426c96fcdb</pre>
 511 </div>
 512 </div>
 513 <div class="paragraph">
 514 <p>yields</p>
 515 </div>
 516 <div class="listingblock">
 517 <div class="content">
 518 <pre>$ cat ~/log.normal
 519 12:28:42.620009 common-main.c:38                  version 2.20.1.155.g426c96fcdb
 520 12:28:42.620989 common-main.c:39                  start git version
 521 12:28:42.621101 git.c:432                         cmd_name version (version)
 522 12:28:42.621215 git.c:662                         exit elapsed:0.001227 code:0
 523 12:28:42.621250 trace2/tr2_tgt_normal.c:124       atexit elapsed:0.001265 code:0</pre>
 524 </div>
 525 </div>
 526 </div>
 527 <div class="sect2">
 528 <h3 id="_the_performance_format_target">The Performance Format Target</h3>
 529 <div class="paragraph">
 530 <p>The performance format target (PERF) is a column-based format to
 531 replace <code>GIT_TRACE_PERFORMANCE</code> and is suitable for development and
 532 testing, possibly to complement tools like <code>gprof</code>.  This format is
 533 enabled with the <code>GIT_TRACE2_PERF</code> environment variable or the
 534 <code>trace2.perfTarget</code> system or global config setting.</p>
 535 </div>
 536 <div class="paragraph">
 537 <p>For example</p>
 538 </div>
 539 <div class="listingblock">
 540 <div class="content">
 541 <pre>$ export GIT_TRACE2_PERF=~/log.perf
 542 $ git version
 543 git version 2.20.1.155.g426c96fcdb</pre>
 544 </div>
 545 </div>
 546 <div class="paragraph">
 547 <p>or</p>
 548 </div>
 549 <div class="listingblock">
 550 <div class="content">
 551 <pre>$ git config --global trace2.perfTarget ~/log.perf
 552 $ git version
 553 git version 2.20.1.155.g426c96fcdb</pre>
 554 </div>
 555 </div>
 556 <div class="paragraph">
 557 <p>yields</p>
 558 </div>
 559 <div class="listingblock">
 560 <div class="content">
 561 <pre>$ cat ~/log.perf
 562 12:28:42.620675 common-main.c:38                  | d0 | main                     | version      |     |           |           |            | 2.20.1.155.g426c96fcdb
 563 12:28:42.621001 common-main.c:39                  | d0 | main                     | start        |     |  0.001173 |           |            | git version
 564 12:28:42.621111 git.c:432                         | d0 | main                     | cmd_name     |     |           |           |            | version (version)
 565 12:28:42.621225 git.c:662                         | d0 | main                     | exit         |     |  0.001227 |           |            | code:0
 566 12:28:42.621259 trace2/tr2_tgt_perf.c:211         | d0 | main                     | atexit       |     |  0.001265 |           |            | code:0</pre>
 567 </div>
 568 </div>
 569 </div>
 570 <div class="sect2">
 571 <h3 id="_the_event_format_target">The Event Format Target</h3>
 572 <div class="paragraph">
 573 <p>The event format target is a JSON-based format of event data suitable
 574 for telemetry analysis.  This format is enabled with the <code>GIT_TRACE2_EVENT</code>
 575 environment variable or the <code>trace2.eventTarget</code> system or global config
 576 setting.</p>
 577 </div>
 578 <div class="paragraph">
 579 <p>For example</p>
 580 </div>
 581 <div class="listingblock">
 582 <div class="content">
 583 <pre>$ export GIT_TRACE2_EVENT=~/log.event
 584 $ git version
 585 git version 2.20.1.155.g426c96fcdb</pre>
 586 </div>
 587 </div>
 588 <div class="paragraph">
 589 <p>or</p>
 590 </div>
 591 <div class="listingblock">
 592 <div class="content">
 593 <pre>$ git config --global trace2.eventTarget ~/log.event
 594 $ git version
 595 git version 2.20.1.155.g426c96fcdb</pre>
 596 </div>
 597 </div>
 598 <div class="paragraph">
 599 <p>yields</p>
 600 </div>
 601 <div class="listingblock">
 602 <div class="content">
 603 <pre>$ cat ~/log.event
 604 {"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"}
 605 {"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"]}
 606 {"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"}
 607 {"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}
 608 {"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>
 609 </div>
 610 </div>
 611 </div>
 612 <div class="sect2">
 613 <h3 id="_enabling_a_target">Enabling a Target</h3>
 614 <div class="paragraph">
 615 <p>To enable a target, set the corresponding environment variable or
 616 system or global config value to one of the following:</p>
 617 </div>
 618 <div class="openblock">
 619 <div class="content">
 620 <div class="ulist">
 621 <ul>
 622 <li>
 623 <p><code>0</code> or <code>false</code> - Disables the target.</p>
 624 </li>
 625 <li>
 626 <p><code>1</code> or <code>true</code> - Writes to <code>STDERR</code>.</p>
 627 </li>
 628 <li>
 629 <p>[<code>2-9</code>] - Writes to the already opened file descriptor.</p>
 630 </li>
 631 <li>
 632 <p><em>&lt;absolute-pathname&gt;</em> - Writes to the file in append mode. If the target
 633 already exists and is a directory, the traces will be written to files (one
 634 per process) underneath the given directory.</p>
 635 </li>
 636 <li>
 637 <p><code>af_unix:</code>[<em>&lt;socket-type&gt;</em><code>:</code>]<em>&lt;absolute-pathname&gt;</em> - Write to a
 638 Unix DomainSocket (on platforms that support them).  Socket
 639 type can be either <code>stream</code> or <code>dgram</code>; if omitted Git will
 640 try both.</p>
 641 </li>
 642 </ul>
 643 </div>
 644 </div>
 645 </div>
 646 <div class="paragraph">
 647 <p>When trace files are written to a target directory, they will be named according
 648 to the last component of the SID (optionally followed by a counter to avoid
 649 filename collisions).</p>
 650 </div>
 651 </div>
 652 </div>
 653 </div>
 654 <div class="sect1">
 655 <h2 id="_trace2_api">Trace2 API</h2>
 656 <div class="sectionbody">
 657 <div class="paragraph">
 658 <p>The Trace2 public API is defined and documented in <code>trace2.h</code>; refer to it for
 659 more information.  All public functions and macros are prefixed
 660 with <code>trace2_</code> and are implemented in <code>trace2.c</code>.</p>
 661 </div>
 662 <div class="paragraph">
 663 <p>There are no public Trace2 data structures.</p>
 664 </div>
 665 <div class="paragraph">
 666 <p>The Trace2 code also defines a set of private functions and data types
 667 in the <code>trace2/</code> directory.  These symbols are prefixed with <code>tr2_</code>
 668 and should only be used by functions in <code>trace2.c</code> (or other private
 669 source files in <code>trace2/</code>).</p>
 670 </div>
 671 <div class="sect2">
 672 <h3 id="_conventions_for_public_functions_and_macros">Conventions for Public Functions and Macros</h3>
 673 <div class="paragraph">
 674 <p>Some functions have a <code>_fl</code>() suffix to indicate that they take <code>file</code>
 675 and <code>line-number</code> arguments.</p>
 676 </div>
 677 <div class="paragraph">
 678 <p>Some functions have a <code>_va_fl</code>() suffix to indicate that they also
 679 take a <code>va_list</code> argument.</p>
 680 </div>
 681 <div class="paragraph">
 682 <p>Some functions have a <code>_printf_fl</code>() suffix to indicate that they also
 683 take a <code>printf</code>() style format with a variable number of arguments.</p>
 684 </div>
 685 <div class="paragraph">
 686 <p>CPP wrapper macros are defined to hide most of these details.</p>
 687 </div>
 688 </div>
 689 </div>
 690 </div>
 691 <div class="sect1">
 692 <h2 id="_trace2_target_formats">Trace2 Target Formats</h2>
 693 <div class="sectionbody">
 694 <div class="sect2">
 695 <h3 id="_normal_format">NORMAL Format</h3>
 696 <div class="paragraph">
 697 <p>Events are written as lines of the form:</p>
 698 </div>
 699 <div class="listingblock">
 700 <div class="content">
 701 <pre>[&lt;time&gt; SP &lt;filename&gt;:&lt;line&gt; SP+] &lt;event-name&gt; [[SP] &lt;event-message&gt;] LF</pre>
 702 </div>
 703 </div>
 704 <div class="dlist">
 705 <dl>
 706 <dt class="hdlist1"><em>&lt;event-name&gt;</em></dt>
 707 <dd>
 708 <p>is the event name.</p>
 709 </dd>
 710 <dt class="hdlist1"><em>&lt;event-message&gt;</em></dt>
 711 <dd>
 712 <p>is a free-form <code>printf</code>() message intended for human consumption.</p>
 713 <div class="paragraph">
 714 <p>Note that this may contain embedded LF or CRLF characters that are
 715 not escaped, so the event may spill across multiple lines.</p>
 716 </div>
 717 </dd>
 718 </dl>
 719 </div>
 720 <div class="paragraph">
 721 <p>If <code>GIT_TRACE2_BRIEF</code> or <code>trace2.normalBrief</code> is true, the <code>time</code>, <code>filename</code>,
 722 and <code>line</code> fields are omitted.</p>
 723 </div>
 724 <div class="paragraph">
 725 <p>This target is intended to be more of a summary (like GIT_TRACE) and
 726 less detailed than the other targets.  It ignores thread, region, and
 727 data messages, for example.</p>
 728 </div>
 729 </div>
 730 <div class="sect2">
 731 <h3 id="_perf_format">PERF Format</h3>
 732 <div class="paragraph">
 733 <p>Events are written as lines of the form:</p>
 734 </div>
 735 <div class="listingblock">
 736 <div class="content">
 737 <pre>[&lt;time&gt; SP &lt;filename&gt;:&lt;line&gt; SP+
 738     BAR SP] d&lt;depth&gt; SP
 739     BAR SP &lt;thread-name&gt; SP+
 740     BAR SP &lt;event-name&gt; SP+
 741     BAR SP [r&lt;repo-id&gt;] SP+
 742     BAR SP [&lt;t_abs&gt;] SP+
 743     BAR SP [&lt;t_rel&gt;] SP+
 744     BAR SP [&lt;category&gt;] SP+
 745     BAR SP DOTS* &lt;perf-event-message&gt;
 746     LF</pre>
 747 </div>
 748 </div>
 749 <div class="dlist">
 750 <dl>
 751 <dt class="hdlist1"><em>&lt;depth&gt;</em></dt>
 752 <dd>
 753 <p>is the git process depth.  This is the number of parent
 754 git processes.  A top-level git command has depth value "d0".
 755 A child of it has depth value "d1".  A second level child
 756 has depth value "d2" and so on.</p>
 757 </dd>
 758 <dt class="hdlist1"><em>&lt;thread-name&gt;</em></dt>
 759 <dd>
 760 <p>is a unique name for the thread.  The primary thread
 761 is called "main".  Other thread names are of the form "th%d:%s"
 762 and include a unique number and the name of the thread-proc.</p>
 763 </dd>
 764 <dt class="hdlist1"><em>&lt;event-name&gt;</em></dt>
 765 <dd>
 766 <p>is the event name.</p>
 767 </dd>
 768 <dt class="hdlist1"><em>&lt;repo-id&gt;</em></dt>
 769 <dd>
 770 <p>when present, is a number indicating the repository
 771 in use.  A <code>def_repo</code> event is emitted when a repository is
 772 opened.  This defines the repo-id and associated worktree.
 773 Subsequent repo-specific events will reference this repo-id.</p>
 774 <div class="paragraph">
 775 <p>Currently, this is always "r1" for the main repository.
 776 This field is in anticipation of in-proc submodules in the future.</p>
 777 </div>
 778 </dd>
 779 <dt class="hdlist1">&lt;t_abs&gt;</dt>
 780 <dd>
 781 <p>when present, is the absolute time in seconds since the
 782 program started.</p>
 783 </dd>
 784 <dt class="hdlist1">&lt;t_rel&gt;</dt>
 785 <dd>
 786 <p>when present, is time in seconds relative to the start of
 787 the current region.  For a thread-exit event, it is the elapsed
 788 time of the thread.</p>
 789 </dd>
 790 <dt class="hdlist1"><em>&lt;category&gt;</em></dt>
 791 <dd>
 792 <p>is present on region and data events and is used to
 793 indicate a broad category, such as "index" or "status".</p>
 794 </dd>
 795 <dt class="hdlist1"><em>&lt;perf-event-message&gt;</em></dt>
 796 <dd>
 797 <p>is a free-form <code>printf</code>() message intended for human consumption.</p>
 798 </dd>
 799 </dl>
 800 </div>
 801 <div class="listingblock">
 802 <div class="content">
 803 <pre>15:33:33.532712 wt-status.c:2310                  | d0 | main                     | region_enter | r1  |  0.126064 |           | status     | label:print
 804 15:33:33.532712 wt-status.c:2331                  | d0 | main                     | region_leave | r1  |  0.127568 |  0.001504 | status     | label:print</pre>
 805 </div>
 806 </div>
 807 <div class="paragraph">
 808 <p>If <code>GIT_TRACE2_PERF_BRIEF</code> or <code>trace2.perfBrief</code> is true, the <code>time</code>, <code>file</code>,
 809 and <code>line</code> fields are omitted.</p>
 810 </div>
 811 <div class="listingblock">
 812 <div class="content">
 813 <pre>d0 | main                     | region_leave | r1  |  0.011717 |  0.009122 | index      | label:preload</pre>
 814 </div>
 815 </div>
 816 <div class="paragraph">
 817 <p>The PERF target is intended for interactive performance analysis
 818 during development and is quite noisy.</p>
 819 </div>
 820 </div>
 821 <div class="sect2">
 822 <h3 id="_event_format">EVENT Format</h3>
 823 <div class="paragraph">
 824 <p>Each event is a JSON-object containing multiple key/value pairs
 825 written as a single line and followed by a LF.</p>
 826 </div>
 827 <div class="listingblock">
 828 <div class="content">
 829 <pre>'{' &lt;key&gt; ':' &lt;value&gt; [',' &lt;key&gt; ':' &lt;value&gt;]* '}' LF</pre>
 830 </div>
 831 </div>
 832 <div class="paragraph">
 833 <p>Some key/value pairs are common to all events and some are
 834 event-specific.</p>
 835 </div>
 836 <div class="sect3">
 837 <h4 id="_common_keyvalue_pairs">Common Key/Value Pairs</h4>
 838 <div class="paragraph">
 839 <p>The following key/value pairs are common to all events:</p>
 840 </div>
 841 <div class="listingblock">
 842 <div class="content">
 843 <pre>{
 844         "event":"version",
 845         "sid":"20190408T191827.272759Z-H9b68c35f-P00003510",
 846         "thread":"main",
 847         "time":"2019-04-08T19:18:27.282761Z",
 848         "file":"common-main.c",
 849         "line":42,
 850         ...
 851 }</pre>
 852 </div>
 853 </div>
 854 <div class="dlist">
 855 <dl>
 856 <dt class="hdlist1">"event":<em>&lt;event&gt;</em></dt>
 857 <dd>
 858 <p>is the event name.</p>
 859 </dd>
 860 <dt class="hdlist1">"sid":<em>&lt;sid&gt;</em></dt>
 861 <dd>
 862 <p>is the session-id.  This is a unique string to identify the
 863 process instance to allow all events emitted by a process to
 864 be identified.  A session-id is used instead of a PID because
 865 PIDs are recycled by the OS.  For child git processes, the
 866 session-id is prepended with the session-id of the parent git
 867 process to allow parent-child relationships to be identified
 868 during post-processing.</p>
 869 </dd>
 870 <dt class="hdlist1">"thread":<em>&lt;thread&gt;</em></dt>
 871 <dd>
 872 <p>is the thread name.</p>
 873 </dd>
 874 <dt class="hdlist1">"time":<em>&lt;time&gt;</em></dt>
 875 <dd>
 876 <p>is the UTC time of the event.</p>
 877 </dd>
 878 <dt class="hdlist1">"file":<em>&lt;filename&gt;</em></dt>
 879 <dd>
 880 <p>is source file generating the event.</p>
 881 </dd>
 882 <dt class="hdlist1">"line":<em>&lt;line-number&gt;</em></dt>
 883 <dd>
 884 <p>is the integer source line number generating the event.</p>
 885 </dd>
 886 <dt class="hdlist1">"repo":<em>&lt;repo-id&gt;</em></dt>
 887 <dd>
 888 <p>when present, is the integer repo-id as described previously.</p>
 889 </dd>
 890 </dl>
 891 </div>
 892 <div class="paragraph">
 893 <p>If <code>GIT_TRACE2_EVENT_BRIEF</code> or <code>trace2.eventBrief</code> is true, the <code>file</code>
 894 and <code>line</code> fields are omitted from all events and the <code>time</code> field is
 895 only present on the "start" and "atexit" events.</p>
 896 </div>
 897 </div>
 898 <div class="sect3">
 899 <h4 id="_event_specific_keyvalue_pairs">Event-Specific Key/Value Pairs</h4>
 900 <div class="dlist">
 901 <dl>
 902 <dt class="hdlist1">"version"</dt>
 903 <dd>
 904 <p>This event gives the version of the executable and the EVENT format. It
 905 should always be the first event in a trace session. The EVENT format
 906 version will be incremented if new event types are added, if existing
 907 fields are removed, or if there are significant changes in
 908 interpretation of existing events or fields. Smaller changes, such as
 909 adding a new field to an existing event, will not require an increment
 910 to the EVENT format version.</p>
 911 <div class="listingblock">
 912 <div class="content">
 913 <pre>{
 914         "event":"version",
 915         ...
 916         "evt":"4",                     # EVENT format version
 917         "exe":"2.20.1.155.g426c96fcdb" # git version
 918 }</pre>
 919 </div>
 920 </div>
 921 </dd>
 922 <dt class="hdlist1">"too_many_files"</dt>
 923 <dd>
 924 <p>This event is written to the git-trace2-discard sentinel file if there
 925 are too many files in the target trace directory (see the
 926 trace2.maxFiles config option).</p>
 927 <div class="listingblock">
 928 <div class="content">
 929 <pre>{
 930         "event":"too_many_files",
 931         ...
 932 }</pre>
 933 </div>
 934 </div>
 935 </dd>
 936 <dt class="hdlist1">"start"</dt>
 937 <dd>
 938 <p>This event contains the complete argv received by main().</p>
 939 <div class="listingblock">
 940 <div class="content">
 941 <pre>{
 942         "event":"start",
 943         ...
 944         "t_abs":0.001227, # elapsed time in seconds
 945         "argv":["git","version"]
 946 }</pre>
 947 </div>
 948 </div>
 949 </dd>
 950 <dt class="hdlist1">"exit"</dt>
 951 <dd>
 952 <p>This event is emitted when git calls <code>exit</code>().</p>
 953 <div class="listingblock">
 954 <div class="content">
 955 <pre>{
 956         "event":"exit",
 957         ...
 958         "t_abs":0.001227, # elapsed time in seconds
 959         "code":0          # exit code
 960 }</pre>
 961 </div>
 962 </div>
 963 </dd>
 964 <dt class="hdlist1">"atexit"</dt>
 965 <dd>
 966 <p>This event is emitted by the Trace2 <code>atexit</code> routine during
 967 final shutdown.  It should be the last event emitted by the
 968 process.</p>
 969 <div class="paragraph">
 970 <p>(The elapsed time reported here is greater than the time reported in
 971 the "exit" event because it runs after all other atexit tasks have
 972 completed.)</p>
 973 </div>
 974 <div class="listingblock">
 975 <div class="content">
 976 <pre>{
 977         "event":"atexit",
 978         ...
 979         "t_abs":0.001227, # elapsed time in seconds
 980         "code":0          # exit code
 981 }</pre>
 982 </div>
 983 </div>
 984 </dd>
 985 <dt class="hdlist1">"signal"</dt>
 986 <dd>
 987 <p>This event is emitted when the program is terminated by a user
 988 signal.  Depending on the platform, the signal event may
 989 prevent the "atexit" event from being generated.</p>
 990 <div class="listingblock">
 991 <div class="content">
 992 <pre>{
 993         "event":"signal",
 994         ...
 995         "t_abs":0.001227,  # elapsed time in seconds
 996         "signo":13         # SIGTERM, SIGINT, etc.
 997 }</pre>
 998 </div>
 999 </div>
1000 </dd>
1001 <dt class="hdlist1">"error"</dt>
1002 <dd>
1003 <p>This event is emitted when one of the <code>BUG</code>(), <code>bug</code>(), <code>error</code>(),
1004 <code>die</code>(), <code>warning</code>(), or <code>usage</code>() functions are called.</p>
1005 <div class="listingblock">
1006 <div class="content">
1007 <pre>{
1008         "event":"error",
1009         ...
1010         "msg":"invalid option: --cahced", # formatted error message
1011         "fmt":"invalid option: %s"        # error format string
1012 }</pre>
1013 </div>
1014 </div>
1015 <div class="paragraph">
1016 <p>The error event may be emitted more than once.  The format string
1017 allows post-processors to group errors by type without worrying
1018 about specific error arguments.</p>
1019 </div>
1020 </dd>
1021 <dt class="hdlist1">"cmd_path"</dt>
1022 <dd>
1023 <p>This event contains the discovered full path of the git
1024 executable (on platforms that are configured to resolve it).</p>
1025 <div class="listingblock">
1026 <div class="content">
1027 <pre>{
1028         "event":"cmd_path",
1029         ...
1030         "path":"C:/work/gfw/git.exe"
1031 }</pre>
1032 </div>
1033 </div>
1034 </dd>
1035 <dt class="hdlist1">"cmd_ancestry"</dt>
1036 <dd>
1037 <p>This event contains the text command name for the parent (and earlier
1038 generations of parents) of the current process, in an array ordered from
1039 nearest parent to furthest great-grandparent. It may not be implemented
1040 on all platforms.</p>
1041 <div class="listingblock">
1042 <div class="content">
1043 <pre>{
1044         "event":"cmd_ancestry",
1045         ...
1046         "ancestry":["bash","tmux: server","systemd"]
1047 }</pre>
1048 </div>
1049 </div>
1050 </dd>
1051 <dt class="hdlist1">"cmd_name"</dt>
1052 <dd>
1053 <p>This event contains the command name for this git process
1054 and the hierarchy of commands from parent git processes.</p>
1055 <div class="listingblock">
1056 <div class="content">
1057 <pre>{
1058         "event":"cmd_name",
1059         ...
1060         "name":"pack-objects",
1061         "hierarchy":"push/pack-objects"
1062 }</pre>
1063 </div>
1064 </div>
1065 <div class="paragraph">
1066 <p>Normally, the "name" field contains the canonical name of the
1067 command.  When a canonical name is not available, one of
1068 these special values are used:</p>
1069 </div>
1070 <div class="listingblock">
1071 <div class="content">
1072 <pre>"_query_"            # "git --html-path"
1073 "_run_dashed_"       # when "git foo" tries to run "git-foo"
1074 "_run_shell_alias_"  # alias expansion to a shell command
1075 "_run_git_alias_"    # alias expansion to a git command
1076 "_usage_"            # usage error</pre>
1077 </div>
1078 </div>
1079 </dd>
1080 <dt class="hdlist1">"cmd_mode"</dt>
1081 <dd>
1082 <p>This event, when present, describes the command variant. This
1083 event may be emitted more than once.</p>
1084 <div class="listingblock">
1085 <div class="content">
1086 <pre>{
1087         "event":"cmd_mode",
1088         ...
1089         "name":"branch"
1090 }</pre>
1091 </div>
1092 </div>
1093 <div class="paragraph">
1094 <p>The "name" field is an arbitrary string to describe the command mode.
1095 For example, checkout can checkout a branch or an individual file.
1096 And these variations typically have different performance
1097 characteristics that are not comparable.</p>
1098 </div>
1099 </dd>
1100 <dt class="hdlist1">"alias"</dt>
1101 <dd>
1102 <p>This event is present when an alias is expanded.</p>
1103 <div class="listingblock">
1104 <div class="content">
1105 <pre>{
1106         "event":"alias",
1107         ...
1108         "alias":"l",             # registered alias
1109         "argv":["log","--graph"] # alias expansion
1110 }</pre>
1111 </div>
1112 </div>
1113 </dd>
1114 <dt class="hdlist1">"child_start"</dt>
1115 <dd>
1116 <p>This event describes a child process that is about to be
1117 spawned.</p>
1118 <div class="listingblock">
1119 <div class="content">
1120 <pre>{
1121         "event":"child_start",
1122         ...
1123         "child_id":2,
1124         "child_class":"?",
1125         "use_shell":false,
1126         "argv":["git","rev-list","--objects","--stdin","--not","--all","--quiet"]
1127
1128         "hook_name":"&lt;hook_name&gt;"  # present when child_class is "hook"
1129         "cd":"&lt;path&gt;"              # present when cd is required
1130 }</pre>
1131 </div>
1132 </div>
1133 <div class="paragraph">
1134 <p>The "child_id" field can be used to match this child_start with the
1135 corresponding child_exit event.</p>
1136 </div>
1137 <div class="paragraph">
1138 <p>The "child_class" field is a rough classification, such as "editor",
1139 "pager", "transport/*", and "hook".  Unclassified children are classified
1140 with "?".</p>
1141 </div>
1142 </dd>
1143 <dt class="hdlist1">"child_exit"</dt>
1144 <dd>
1145 <p>This event is generated after the current process has returned
1146 from the <code>waitpid</code>() and collected the exit information from the
1147 child.</p>
1148 <div class="listingblock">
1149 <div class="content">
1150 <pre>{
1151         "event":"child_exit",
1152         ...
1153         "child_id":2,
1154         "pid":14708,     # child PID
1155         "code":0,        # child exit-code
1156         "t_rel":0.110605 # observed run-time of child process
1157 }</pre>
1158 </div>
1159 </div>
1160 <div class="paragraph">
1161 <p>Note that the session-id of the child process is not available to
1162 the current/spawning process, so the child&#8217;s PID is reported here as
1163 a hint for post-processing.  (But it is only a hint because the child
1164 process may be a shell script which doesn&#8217;t have a session-id.)</p>
1165 </div>
1166 <div class="paragraph">
1167 <p>Note that the <code>t_rel</code> field contains the observed run time in seconds
1168 for the child process (starting before the fork/exec/spawn and
1169 stopping after the <code>waitpid</code>() and includes OS process creation overhead).
1170 So this time will be slightly larger than the atexit time reported by
1171 the child process itself.</p>
1172 </div>
1173 </dd>
1174 <dt class="hdlist1">"child_ready"</dt>
1175 <dd>
1176 <p>This event is generated after the current process has started
1177 a background process and released all handles to it.</p>
1178 <div class="listingblock">
1179 <div class="content">
1180 <pre>{
1181         "event":"child_ready",
1182         ...
1183         "child_id":2,
1184         "pid":14708,     # child PID
1185         "ready":"ready", # child ready state
1186         "t_rel":0.110605 # observed run-time of child process
1187 }</pre>
1188 </div>
1189 </div>
1190 <div class="paragraph">
1191 <p>Note that the session-id of the child process is not available to
1192 the current/spawning process, so the child&#8217;s PID is reported here as
1193 a hint for post-processing.  (But it is only a hint because the child
1194 process may be a shell script which doesn&#8217;t have a session-id.)</p>
1195 </div>
1196 <div class="paragraph">
1197 <p>This event is generated after the child is started in the background
1198 and given a little time to boot up and start working.  If the child
1199 starts up normally while the parent is still waiting, the "ready"
1200 field will have the value "ready".
1201 If the child is too slow to start and the parent times out, the field
1202 will have the value "timeout".
1203 If the child starts but the parent is unable to probe it, the field
1204 will have the value "error".</p>
1205 </div>
1206 <div class="paragraph">
1207 <p>After the parent process emits this event, it will release all of its
1208 handles to the child process and treat the child as a background
1209 daemon.  So even if the child does eventually finish booting up,
1210 the parent will not emit an updated event.</p>
1211 </div>
1212 <div class="paragraph">
1213 <p>Note that the <code>t_rel</code> field contains the observed run time in seconds
1214 when the parent released the child process into the background.
1215 The child is assumed to be a long-running daemon process and may
1216 outlive the parent process.  So the parent&#8217;s child event times should
1217 not be compared to the child&#8217;s atexit times.</p>
1218 </div>
1219 </dd>
1220 <dt class="hdlist1">"exec"</dt>
1221 <dd>
1222 <p>This event is generated before git attempts to <code>exec</code>()
1223 another command rather than starting a child process.</p>
1224 <div class="listingblock">
1225 <div class="content">
1226 <pre>{
1227         "event":"exec",
1228         ...
1229         "exec_id":0,
1230         "exe":"git",
1231         "argv":["foo", "bar"]
1232 }</pre>
1233 </div>
1234 </div>
1235 <div class="paragraph">
1236 <p>The "exec_id" field is a command-unique id and is only useful if the
1237 <code>exec</code>() fails and a corresponding exec_result event is generated.</p>
1238 </div>
1239 </dd>
1240 <dt class="hdlist1">"exec_result"</dt>
1241 <dd>
1242 <p>This event is generated if the <code>exec</code>() fails and control
1243 returns to the current git command.</p>
1244 <div class="listingblock">
1245 <div class="content">
1246 <pre>{
1247         "event":"exec_result",
1248         ...
1249         "exec_id":0,
1250         "code":1      # error code (errno) from exec()
1251 }</pre>
1252 </div>
1253 </div>
1254 </dd>
1255 <dt class="hdlist1">"thread_start"</dt>
1256 <dd>
1257 <p>This event is generated when a thread is started.  It is
1258 generated from <strong>within</strong> the new thread&#8217;s thread-proc (because
1259 it needs to access data in the thread&#8217;s thread-local storage).</p>
1260 <div class="listingblock">
1261 <div class="content">
1262 <pre>{
1263         "event":"thread_start",
1264         ...
1265         "thread":"th02:preload_thread" # thread name
1266 }</pre>
1267 </div>
1268 </div>
1269 </dd>
1270 <dt class="hdlist1">"thread_exit"</dt>
1271 <dd>
1272 <p>This event is generated when a thread exits.  It is generated
1273 from <strong>within</strong> the thread&#8217;s thread-proc.</p>
1274 <div class="listingblock">
1275 <div class="content">
1276 <pre>{
1277         "event":"thread_exit",
1278         ...
1279         "thread":"th02:preload_thread", # thread name
1280         "t_rel":0.007328                # thread elapsed time
1281 }</pre>
1282 </div>
1283 </div>
1284 </dd>
1285 <dt class="hdlist1">"def_param"</dt>
1286 <dd>
1287 <p>This event is generated to log a global parameter, such as a config
1288 setting, command-line flag, or environment variable.</p>
1289 <div class="listingblock">
1290 <div class="content">
1291 <pre>{
1292         "event":"def_param",
1293         ...
1294         "scope":"global",
1295         "param":"core.abbrev",
1296         "value":"7"
1297 }</pre>
1298 </div>
1299 </div>
1300 </dd>
1301 <dt class="hdlist1">"def_repo"</dt>
1302 <dd>
1303 <p>This event defines a repo-id and associates it with the root
1304 of the worktree.</p>
1305 <div class="listingblock">
1306 <div class="content">
1307 <pre>{
1308         "event":"def_repo",
1309         ...
1310         "repo":1,
1311         "worktree":"/Users/jeffhost/work/gfw"
1312 }</pre>
1313 </div>
1314 </div>
1315 <div class="paragraph">
1316 <p>As stated earlier, the repo-id is currently always 1, so there will
1317 only be one def_repo event.  Later, if in-proc submodules are
1318 supported, a def_repo event should be emitted for each submodule
1319 visited.</p>
1320 </div>
1321 </dd>
1322 <dt class="hdlist1">"region_enter"</dt>
1323 <dd>
1324 <p>This event is generated when entering a region.</p>
1325 <div class="listingblock">
1326 <div class="content">
1327 <pre>{
1328         "event":"region_enter",
1329         ...
1330         "repo":1,                # optional
1331         "nesting":1,             # current region stack depth
1332         "category":"index",      # optional
1333         "label":"do_read_index", # optional
1334         "msg":".git/index"       # optional
1335 }</pre>
1336 </div>
1337 </div>
1338 <div class="paragraph">
1339 <p>The <code>category</code> field may be used in a future enhancement to
1340 do category-based filtering.</p>
1341 </div>
1342 <div class="paragraph">
1343 <p><code>GIT_TRACE2_EVENT_NESTING</code> or <code>trace2.eventNesting</code> can be used to
1344 filter deeply nested regions and data events.  It defaults to "2".</p>
1345 </div>
1346 </dd>
1347 <dt class="hdlist1">"region_leave"</dt>
1348 <dd>
1349 <p>This event is generated when leaving a region.</p>
1350 <div class="listingblock">
1351 <div class="content">
1352 <pre>{
1353         "event":"region_leave",
1354         ...
1355         "repo":1,                # optional
1356         "t_rel":0.002876,        # time spent in region in seconds
1357         "nesting":1,             # region stack depth
1358         "category":"index",      # optional
1359         "label":"do_read_index", # optional
1360         "msg":".git/index"       # optional
1361 }</pre>
1362 </div>
1363 </div>
1364 </dd>
1365 <dt class="hdlist1">"data"</dt>
1366 <dd>
1367 <p>This event is generated to log a thread- and region-local
1368 key/value pair.</p>
1369 <div class="listingblock">
1370 <div class="content">
1371 <pre>{
1372         "event":"data",
1373         ...
1374         "repo":1,              # optional
1375         "t_abs":0.024107,      # absolute elapsed time
1376         "t_rel":0.001031,      # elapsed time in region/thread
1377         "nesting":2,           # region stack depth
1378         "category":"index",
1379         "key":"read/cache_nr",
1380         "value":"3552"
1381 }</pre>
1382 </div>
1383 </div>
1384 <div class="paragraph">
1385 <p>The "value" field may be an integer or a string.</p>
1386 </div>
1387 </dd>
1388 <dt class="hdlist1">"data-json"</dt>
1389 <dd>
1390 <p>This event is generated to log a pre-formatted JSON string
1391 containing structured data.</p>
1392 <div class="listingblock">
1393 <div class="content">
1394 <pre>{
1395         "event":"data_json",
1396         ...
1397         "repo":1,              # optional
1398         "t_abs":0.015905,
1399         "t_rel":0.015905,
1400         "nesting":1,
1401         "category":"process",
1402         "key":"windows/ancestry",
1403         "value":["bash.exe","bash.exe"]
1404 }</pre>
1405 </div>
1406 </div>
1407 </dd>
1408 <dt class="hdlist1">"th_timer"</dt>
1409 <dd>
1410 <p>This event logs the amount of time that a stopwatch timer was
1411 running in the thread.  This event is generated when a thread
1412 exits for timers that requested per-thread events.</p>
1413 <div class="listingblock">
1414 <div class="content">
1415 <pre>{
1416         "event":"th_timer",
1417         ...
1418         "category":"my_category",
1419         "name":"my_timer",
1420         "intervals":5,         # number of time it was started/stopped
1421         "t_total":0.052741,    # total time in seconds it was running
1422         "t_min":0.010061,      # shortest interval
1423         "t_max":0.011648       # longest interval
1424 }</pre>
1425 </div>
1426 </div>
1427 </dd>
1428 <dt class="hdlist1">"timer"</dt>
1429 <dd>
1430 <p>This event logs the amount of time that a stopwatch timer was
1431 running aggregated across all threads.  This event is generated
1432 when the process exits.</p>
1433 <div class="listingblock">
1434 <div class="content">
1435 <pre>{
1436         "event":"timer",
1437         ...
1438         "category":"my_category",
1439         "name":"my_timer",
1440         "intervals":5,         # number of time it was started/stopped
1441         "t_total":0.052741,    # total time in seconds it was running
1442         "t_min":0.010061,      # shortest interval
1443         "t_max":0.011648       # longest interval
1444 }</pre>
1445 </div>
1446 </div>
1447 </dd>
1448 <dt class="hdlist1">"th_counter"</dt>
1449 <dd>
1450 <p>This event logs the value of a counter variable in a thread.
1451 This event is generated when a thread exits for counters that
1452 requested per-thread events.</p>
1453 <div class="listingblock">
1454 <div class="content">
1455 <pre>{
1456         "event":"th_counter",
1457         ...
1458         "category":"my_category",
1459         "name":"my_counter",
1460         "count":23
1461 }</pre>
1462 </div>
1463 </div>
1464 </dd>
1465 <dt class="hdlist1">"counter"</dt>
1466 <dd>
1467 <p>This event logs the value of a counter variable across all threads.
1468 This event is generated when the process exits.  The total value
1469 reported here is the sum across all threads.</p>
1470 <div class="listingblock">
1471 <div class="content">
1472 <pre>{
1473         "event":"counter",
1474         ...
1475         "category":"my_category",
1476         "name":"my_counter",
1477         "count":23
1478 }</pre>
1479 </div>
1480 </div>
1481 </dd>
1482 <dt class="hdlist1">"printf"</dt>
1483 <dd>
1484 <p>This event logs a human-readable message with no particular formatting
1485 guidelines.</p>
1486 <div class="listingblock">
1487 <div class="content">
1488 <pre>{
1489         "event":"printf",
1490         ...
1491         "t_abs":0.015905,      # elapsed time in seconds
1492         "msg":"Hello world"    # optional
1493 }</pre>
1494 </div>
1495 </div>
1496 </dd>
1497 </dl>
1498 </div>
1499 </div>
1500 </div>
1501 </div>
1502 </div>
1503 <div class="sect1">
1504 <h2 id="_example_trace2_api_usage">Example Trace2 API Usage</h2>
1505 <div class="sectionbody">
1506 <div class="paragraph">
1507 <p>Here is a hypothetical usage of the Trace2 API showing the intended
1508 usage (without worrying about the actual Git details).</p>
1509 </div>
1510 <div class="dlist">
1511 <dl>
1512 <dt class="hdlist1">Initialization</dt>
1513 <dd>
1514 <p>Initialization happens in <code>main</code>().  Behind the scenes, an
1515 <code>atexit</code> and <code>signal</code> handler are registered.</p>
1516 <div class="listingblock">
1517 <div class="content">
1518 <pre>int main(int argc, const char **argv)
1519 {
1520         int exit_code;
1521
1522         trace2_initialize();
1523         trace2_cmd_start(argv);
1524
1525         exit_code = cmd_main(argc, argv);
1526
1527         trace2_cmd_exit(exit_code);
1528
1529         return exit_code;
1530 }</pre>
1531 </div>
1532 </div>
1533 </dd>
1534 <dt class="hdlist1">Command Details</dt>
1535 <dd>
1536 <p>After the basics are established, additional command
1537 information can be sent to Trace2 as it is discovered.</p>
1538 <div class="listingblock">
1539 <div class="content">
1540 <pre>int cmd_checkout(int argc, const char **argv)
1541 {
1542         trace2_cmd_name("checkout");
1543         trace2_cmd_mode("branch");
1544         trace2_def_repo(the_repository);
1545
1546         // emit "def_param" messages for "interesting" config settings.
1547         trace2_cmd_list_config();
1548
1549         if (do_something())
1550             trace2_cmd_error("Path '%s': cannot do something", path);
1551
1552         return 0;
1553 }</pre>
1554 </div>
1555 </div>
1556 </dd>
1557 <dt class="hdlist1">Child Processes</dt>
1558 <dd>
1559 <p>Wrap code spawning child processes.</p>
1560 <div class="listingblock">
1561 <div class="content">
1562 <pre>void run_child(...)
1563 {
1564         int child_exit_code;
1565         struct child_process cmd = CHILD_PROCESS_INIT;
1566         ...
1567         cmd.trace2_child_class = "editor";
1568
1569         trace2_child_start(&amp;cmd);
1570         child_exit_code = spawn_child_and_wait_for_it();
1571         trace2_child_exit(&amp;cmd, child_exit_code);
1572 }</pre>
1573 </div>
1574 </div>
1575 <div class="paragraph">
1576 <p>For example, the following fetch command spawned ssh, index-pack,
1577 rev-list, and gc.  This example also shows that fetch took
1578 5.199 seconds and of that 4.932 was in ssh.</p>
1579 </div>
1580 <div class="listingblock">
1581 <div class="content">
1582 <pre>$ export GIT_TRACE2_BRIEF=1
1583 $ export GIT_TRACE2=~/log.normal
1584 $ git fetch origin
1585 ...</pre>
1586 </div>
1587 </div>
1588 <div class="listingblock">
1589 <div class="content">
1590 <pre>$ cat ~/log.normal
1591 version 2.20.1.vfs.1.1.47.g534dbe1ad1
1592 start git fetch origin
1593 worktree /Users/jeffhost/work/gfw
1594 cmd_name fetch (fetch)
1595 child_start[0] ssh git@github.com ...
1596 child_start[1] git index-pack ...
1597 ... (Trace2 events from child processes omitted)
1598 child_exit[1] pid:14707 code:0 elapsed:0.076353
1599 child_exit[0] pid:14706 code:0 elapsed:4.931869
1600 child_start[2] git rev-list ...
1601 ... (Trace2 events from child process omitted)
1602 child_exit[2] pid:14708 code:0 elapsed:0.110605
1603 child_start[3] git gc --auto
1604 ... (Trace2 events from child process omitted)
1605 child_exit[3] pid:14709 code:0 elapsed:0.006240
1606 exit elapsed:5.198503 code:0
1607 atexit elapsed:5.198541 code:0</pre>
1608 </div>
1609 </div>
1610 <div class="paragraph">
1611 <p>When a git process is a (direct or indirect) child of another
1612 git process, it inherits Trace2 context information.  This
1613 allows the child to print the command hierarchy.  This example
1614 shows gc as child[3] of fetch.  When the gc process reports
1615 its name as "gc", it also reports the hierarchy as "fetch/gc".
1616 (In this example, trace2 messages from the child process is
1617 indented for clarity.)</p>
1618 </div>
1619 <div class="listingblock">
1620 <div class="content">
1621 <pre>$ export GIT_TRACE2_BRIEF=1
1622 $ export GIT_TRACE2=~/log.normal
1623 $ git fetch origin
1624 ...</pre>
1625 </div>
1626 </div>
1627 <div class="listingblock">
1628 <div class="content">
1629 <pre>$ cat ~/log.normal
1630 version 2.20.1.160.g5676107ecd.dirty
1631 start git fetch official
1632 worktree /Users/jeffhost/work/gfw
1633 cmd_name fetch (fetch)
1634 ...
1635 child_start[3] git gc --auto
1636     version 2.20.1.160.g5676107ecd.dirty
1637     start /Users/jeffhost/work/gfw/git gc --auto
1638     worktree /Users/jeffhost/work/gfw
1639     cmd_name gc (fetch/gc)
1640     exit elapsed:0.001959 code:0
1641     atexit elapsed:0.001997 code:0
1642 child_exit[3] pid:20303 code:0 elapsed:0.007564
1643 exit elapsed:3.868938 code:0
1644 atexit elapsed:3.868970 code:0</pre>
1645 </div>
1646 </div>
1647 </dd>
1648 <dt class="hdlist1">Regions</dt>
1649 <dd>
1650 <p>Regions can be used to time an interesting section of code.</p>
1651 <div class="listingblock">
1652 <div class="content">
1653 <pre>void wt_status_collect(struct wt_status *s)
1654 {
1655         trace2_region_enter("status", "worktrees", s-&gt;repo);
1656         wt_status_collect_changes_worktree(s);
1657         trace2_region_leave("status", "worktrees", s-&gt;repo);
1658
1659         trace2_region_enter("status", "index", s-&gt;repo);
1660         wt_status_collect_changes_index(s);
1661         trace2_region_leave("status", "index", s-&gt;repo);
1662
1663         trace2_region_enter("status", "untracked", s-&gt;repo);
1664         wt_status_collect_untracked(s);
1665         trace2_region_leave("status", "untracked", s-&gt;repo);
1666 }
1667
1668 void wt_status_print(struct wt_status *s)
1669 {
1670         trace2_region_enter("status", "print", s-&gt;repo);
1671         switch (s-&gt;status_format) {
1672             ...
1673         }
1674         trace2_region_leave("status", "print", s-&gt;repo);
1675 }</pre>
1676 </div>
1677 </div>
1678 <div class="paragraph">
1679 <p>In this example, scanning for untracked files ran from +0.012568 to
1680 +0.027149 (since the process started) and took 0.014581 seconds.</p>
1681 </div>
1682 <div class="listingblock">
1683 <div class="content">
1684 <pre>$ export GIT_TRACE2_PERF_BRIEF=1
1685 $ export GIT_TRACE2_PERF=~/log.perf
1686 $ git status
1687 ...
1688
1689 $ cat ~/log.perf
1690 d0 | main                     | version      |     |           |           |            | 2.20.1.160.g5676107ecd.dirty
1691 d0 | main                     | start        |     |  0.001173 |           |            | git status
1692 d0 | main                     | def_repo     | r1  |           |           |            | worktree:/Users/jeffhost/work/gfw
1693 d0 | main                     | cmd_name     |     |           |           |            | status (status)
1694 ...
1695 d0 | main                     | region_enter | r1  |  0.010988 |           | status     | label:worktrees
1696 d0 | main                     | region_leave | r1  |  0.011236 |  0.000248 | status     | label:worktrees
1697 d0 | main                     | region_enter | r1  |  0.011260 |           | status     | label:index
1698 d0 | main                     | region_leave | r1  |  0.012542 |  0.001282 | status     | label:index
1699 d0 | main                     | region_enter | r1  |  0.012568 |           | status     | label:untracked
1700 d0 | main                     | region_leave | r1  |  0.027149 |  0.014581 | status     | label:untracked
1701 d0 | main                     | region_enter | r1  |  0.027411 |           | status     | label:print
1702 d0 | main                     | region_leave | r1  |  0.028741 |  0.001330 | status     | label:print
1703 d0 | main                     | exit         |     |  0.028778 |           |            | code:0
1704 d0 | main                     | atexit       |     |  0.028809 |           |            | code:0</pre>
1705 </div>
1706 </div>
1707 <div class="paragraph">
1708 <p>Regions may be nested.  This causes messages to be indented in the
1709 PERF target, for example.
1710 Elapsed times are relative to the start of the corresponding nesting
1711 level as expected.  For example, if we add region message to:</p>
1712 </div>
1713 <div class="listingblock">
1714 <div class="content">
1715 <pre>static enum path_treatment read_directory_recursive(struct dir_struct *dir,
1716         struct index_state *istate, const char *base, int baselen,
1717         struct untracked_cache_dir *untracked, int check_only,
1718         int stop_at_first_file, const struct pathspec *pathspec)
1719 {
1720         enum path_treatment state, subdir_state, dir_state = path_none;
1721
1722         trace2_region_enter_printf("dir", "read_recursive", NULL, "%.*s", baselen, base);
1723         ...
1724         trace2_region_leave_printf("dir", "read_recursive", NULL, "%.*s", baselen, base);
1725         return dir_state;
1726 }</pre>
1727 </div>
1728 </div>
1729 <div class="paragraph">
1730 <p>We can further investigate the time spent scanning for untracked files.</p>
1731 </div>
1732 <div class="listingblock">
1733 <div class="content">
1734 <pre>$ export GIT_TRACE2_PERF_BRIEF=1
1735 $ export GIT_TRACE2_PERF=~/log.perf
1736 $ git status
1737 ...
1738 $ cat ~/log.perf
1739 d0 | main                     | version      |     |           |           |            | 2.20.1.162.gb4ccea44db.dirty
1740 d0 | main                     | start        |     |  0.001173 |           |            | git status
1741 d0 | main                     | def_repo     | r1  |           |           |            | worktree:/Users/jeffhost/work/gfw
1742 d0 | main                     | cmd_name     |     |           |           |            | status (status)
1743 ...
1744 d0 | main                     | region_enter | r1  |  0.015047 |           | status     | label:untracked
1745 d0 | main                     | region_enter |     |  0.015132 |           | dir        | ..label:read_recursive
1746 d0 | main                     | region_enter |     |  0.016341 |           | dir        | ....label:read_recursive vcs-svn/
1747 d0 | main                     | region_leave |     |  0.016422 |  0.000081 | dir        | ....label:read_recursive vcs-svn/
1748 d0 | main                     | region_enter |     |  0.016446 |           | dir        | ....label:read_recursive xdiff/
1749 d0 | main                     | region_leave |     |  0.016522 |  0.000076 | dir        | ....label:read_recursive xdiff/
1750 d0 | main                     | region_enter |     |  0.016612 |           | dir        | ....label:read_recursive git-gui/
1751 d0 | main                     | region_enter |     |  0.016698 |           | dir        | ......label:read_recursive git-gui/po/
1752 d0 | main                     | region_enter |     |  0.016810 |           | dir        | ........label:read_recursive git-gui/po/glossary/
1753 d0 | main                     | region_leave |     |  0.016863 |  0.000053 | dir        | ........label:read_recursive git-gui/po/glossary/
1754 ...
1755 d0 | main                     | region_enter |     |  0.031876 |           | dir        | ....label:read_recursive builtin/
1756 d0 | main                     | region_leave |     |  0.032270 |  0.000394 | dir        | ....label:read_recursive builtin/
1757 d0 | main                     | region_leave |     |  0.032414 |  0.017282 | dir        | ..label:read_recursive
1758 d0 | main                     | region_leave | r1  |  0.032454 |  0.017407 | status     | label:untracked
1759 ...
1760 d0 | main                     | exit         |     |  0.034279 |           |            | code:0
1761 d0 | main                     | atexit       |     |  0.034322 |           |            | code:0</pre>
1762 </div>
1763 </div>
1764 <div class="paragraph">
1765 <p>Trace2 regions are similar to the existing trace_performance_enter()
1766 and trace_performance_leave() routines, but are thread safe and
1767 maintain per-thread stacks of timers.</p>
1768 </div>
1769 </dd>
1770 <dt class="hdlist1">Data Messages</dt>
1771 <dd>
1772 <p>Data messages added to a region.</p>
1773 <div class="listingblock">
1774 <div class="content">
1775 <pre>int read_index_from(struct index_state *istate, const char *path,
1776         const char *gitdir)
1777 {
1778         trace2_region_enter_printf("index", "do_read_index", the_repository, "%s", path);
1779
1780         ...
1781
1782         trace2_data_intmax("index", the_repository, "read/version", istate-&gt;version);
1783         trace2_data_intmax("index", the_repository, "read/cache_nr", istate-&gt;cache_nr);
1784
1785         trace2_region_leave_printf("index", "do_read_index", the_repository, "%s", path);
1786 }</pre>
1787 </div>
1788 </div>
1789 <div class="paragraph">
1790 <p>This example shows that the index contained 3552 entries.</p>
1791 </div>
1792 <div class="listingblock">
1793 <div class="content">
1794 <pre>$ export GIT_TRACE2_PERF_BRIEF=1
1795 $ export GIT_TRACE2_PERF=~/log.perf
1796 $ git status
1797 ...
1798 $ cat ~/log.perf
1799 d0 | main                     | version      |     |           |           |            | 2.20.1.156.gf9916ae094.dirty
1800 d0 | main                     | start        |     |  0.001173 |           |            | git status
1801 d0 | main                     | def_repo     | r1  |           |           |            | worktree:/Users/jeffhost/work/gfw
1802 d0 | main                     | cmd_name     |     |           |           |            | status (status)
1803 d0 | main                     | region_enter | r1  |  0.001791 |           | index      | label:do_read_index .git/index
1804 d0 | main                     | data         | r1  |  0.002494 |  0.000703 | index      | ..read/version:2
1805 d0 | main                     | data         | r1  |  0.002520 |  0.000729 | index      | ..read/cache_nr:3552
1806 d0 | main                     | region_leave | r1  |  0.002539 |  0.000748 | index      | label:do_read_index .git/index
1807 ...</pre>
1808 </div>
1809 </div>
1810 </dd>
1811 <dt class="hdlist1">Thread Events</dt>
1812 <dd>
1813 <p>Thread messages added to a thread-proc.</p>
1814 <div class="paragraph">
1815 <p>For example, the multi-threaded preload-index code can be
1816 instrumented with a region around the thread pool and then
1817 per-thread start and exit events within the thread-proc.</p>
1818 </div>
1819 <div class="listingblock">
1820 <div class="content">
1821 <pre>static void *preload_thread(void *_data)
1822 {
1823         // start the per-thread clock and emit a message.
1824         trace2_thread_start("preload_thread");
1825
1826         // report which chunk of the array this thread was assigned.
1827         trace2_data_intmax("index", the_repository, "offset", p-&gt;offset);
1828         trace2_data_intmax("index", the_repository, "count", nr);
1829
1830         do {
1831             ...
1832         } while (--nr &gt; 0);
1833         ...
1834
1835         // report elapsed time taken by this thread.
1836         trace2_thread_exit();
1837         return NULL;
1838 }
1839
1840 void preload_index(struct index_state *index,
1841         const struct pathspec *pathspec,
1842         unsigned int refresh_flags)
1843 {
1844         trace2_region_enter("index", "preload", the_repository);
1845
1846         for (i = 0; i &lt; threads; i++) {
1847             ... /* create thread */
1848         }
1849
1850         for (i = 0; i &lt; threads; i++) {
1851             ... /* join thread */
1852         }
1853
1854         trace2_region_leave("index", "preload", the_repository);
1855 }</pre>
1856 </div>
1857 </div>
1858 <div class="paragraph">
1859 <p>In this example preload_index() was executed by the <code>main</code> thread
1860 and started the <code>preload</code> region.  Seven threads, named
1861 <code>th01:preload_thread</code> through <code>th07:preload_thread</code>, were started.
1862 Events from each thread are atomically appended to the shared target
1863 stream as they occur so they may appear in random order with respect
1864 other threads. Finally, the main thread waits for the threads to
1865 finish and leaves the region.</p>
1866 </div>
1867 <div class="paragraph">
1868 <p>Data events are tagged with the active thread name.  They are used
1869 to report the per-thread parameters.</p>
1870 </div>
1871 <div class="listingblock">
1872 <div class="content">
1873 <pre>$ export GIT_TRACE2_PERF_BRIEF=1
1874 $ export GIT_TRACE2_PERF=~/log.perf
1875 $ git status
1876 ...
1877 $ cat ~/log.perf
1878 ...
1879 d0 | main                     | region_enter | r1  |  0.002595 |           | index      | label:preload
1880 d0 | th01:preload_thread      | thread_start |     |  0.002699 |           |            |
1881 d0 | th02:preload_thread      | thread_start |     |  0.002721 |           |            |
1882 d0 | th01:preload_thread      | data         | r1  |  0.002736 |  0.000037 | index      | offset:0
1883 d0 | th02:preload_thread      | data         | r1  |  0.002751 |  0.000030 | index      | offset:2032
1884 d0 | th03:preload_thread      | thread_start |     |  0.002711 |           |            |
1885 d0 | th06:preload_thread      | thread_start |     |  0.002739 |           |            |
1886 d0 | th01:preload_thread      | data         | r1  |  0.002766 |  0.000067 | index      | count:508
1887 d0 | th06:preload_thread      | data         | r1  |  0.002856 |  0.000117 | index      | offset:2540
1888 d0 | th03:preload_thread      | data         | r1  |  0.002824 |  0.000113 | index      | offset:1016
1889 d0 | th04:preload_thread      | thread_start |     |  0.002710 |           |            |
1890 d0 | th02:preload_thread      | data         | r1  |  0.002779 |  0.000058 | index      | count:508
1891 d0 | th06:preload_thread      | data         | r1  |  0.002966 |  0.000227 | index      | count:508
1892 d0 | th07:preload_thread      | thread_start |     |  0.002741 |           |            |
1893 d0 | th07:preload_thread      | data         | r1  |  0.003017 |  0.000276 | index      | offset:3048
1894 d0 | th05:preload_thread      | thread_start |     |  0.002712 |           |            |
1895 d0 | th05:preload_thread      | data         | r1  |  0.003067 |  0.000355 | index      | offset:1524
1896 d0 | th05:preload_thread      | data         | r1  |  0.003090 |  0.000378 | index      | count:508
1897 d0 | th07:preload_thread      | data         | r1  |  0.003037 |  0.000296 | index      | count:504
1898 d0 | th03:preload_thread      | data         | r1  |  0.002971 |  0.000260 | index      | count:508
1899 d0 | th04:preload_thread      | data         | r1  |  0.002983 |  0.000273 | index      | offset:508
1900 d0 | th04:preload_thread      | data         | r1  |  0.007311 |  0.004601 | index      | count:508
1901 d0 | th05:preload_thread      | thread_exit  |     |  0.008781 |  0.006069 |            |
1902 d0 | th01:preload_thread      | thread_exit  |     |  0.009561 |  0.006862 |            |
1903 d0 | th03:preload_thread      | thread_exit  |     |  0.009742 |  0.007031 |            |
1904 d0 | th06:preload_thread      | thread_exit  |     |  0.009820 |  0.007081 |            |
1905 d0 | th02:preload_thread      | thread_exit  |     |  0.010274 |  0.007553 |            |
1906 d0 | th07:preload_thread      | thread_exit  |     |  0.010477 |  0.007736 |            |
1907 d0 | th04:preload_thread      | thread_exit  |     |  0.011657 |  0.008947 |            |
1908 d0 | main                     | region_leave | r1  |  0.011717 |  0.009122 | index      | label:preload
1909 ...
1910 d0 | main                     | exit         |     |  0.029996 |           |            | code:0
1911 d0 | main                     | atexit       |     |  0.030027 |           |            | code:0</pre>
1912 </div>
1913 </div>
1914 <div class="paragraph">
1915 <p>In this example, the preload region took 0.009122 seconds.  The 7 threads
1916 took between 0.006069 and 0.008947 seconds to work on their portion of
1917 the index.  Thread "th01" worked on 508 items at offset 0.  Thread "th02"
1918 worked on 508 items at offset 2032.  Thread "th04" worked on 508 items
1919 at offset 508.</p>
1920 </div>
1921 <div class="paragraph">
1922 <p>This example also shows that thread names are assigned in a racy manner
1923 as each thread starts.</p>
1924 </div>
1925 </dd>
1926 <dt class="hdlist1">Config (def param) Events</dt>
1927 <dd>
1928 <p>Dump "interesting" config values to trace2 log.</p>
1929 <div class="paragraph">
1930 <p>We can optionally emit configuration events, see
1931 <code>trace2.configparams</code> in <a href="../git-config.html">git-config(1)</a> for how to enable
1932 it.</p>
1933 </div>
1934 <div class="listingblock">
1935 <div class="content">
1936 <pre>$ git config --system color.ui never
1937 $ git config --global color.ui always
1938 $ git config --local color.ui auto
1939 $ git config --list --show-scope | grep 'color.ui'
1940 system  color.ui=never
1941 global  color.ui=always
1942 local   color.ui=auto</pre>
1943 </div>
1944 </div>
1945 <div class="paragraph">
1946 <p>Then, mark the config <code>color.ui</code> as "interesting" config with
1947 <code>GIT_TRACE2_CONFIG_PARAMS</code>:</p>
1948 </div>
1949 <div class="listingblock">
1950 <div class="content">
1951 <pre>$ export GIT_TRACE2_PERF_BRIEF=1
1952 $ export GIT_TRACE2_PERF=~/log.perf
1953 $ export GIT_TRACE2_CONFIG_PARAMS=color.ui
1954 $ git version
1955 ...
1956 $ cat ~/log.perf
1957 d0 | main                     | version      |     |           |           |              | ...
1958 d0 | main                     | start        |     |  0.001642 |           |              | /usr/local/bin/git version
1959 d0 | main                     | cmd_name     |     |           |           |              | version (version)
1960 d0 | main                     | def_param    |     |           |           | scope:system | color.ui:never
1961 d0 | main                     | def_param    |     |           |           | scope:global | color.ui:always
1962 d0 | main                     | def_param    |     |           |           | scope:local  | color.ui:auto
1963 d0 | main                     | data         | r0  |  0.002100 |  0.002100 | fsync        | fsync/writeout-only:0
1964 d0 | main                     | data         | r0  |  0.002126 |  0.002126 | fsync        | fsync/hardware-flush:0
1965 d0 | main                     | exit         |     |  0.000470 |           |              | code:0
1966 d0 | main                     | atexit       |     |  0.000477 |           |              | code:0</pre>
1967 </div>
1968 </div>
1969 </dd>
1970 <dt class="hdlist1">Stopwatch Timer Events</dt>
1971 <dd>
1972 <p>Measure the time spent in a function call or span of code
1973 that might be called from many places within the code
1974 throughout the life of the process.</p>
1975 <div class="listingblock">
1976 <div class="content">
1977 <pre>static void expensive_function(void)
1978 {
1979         trace2_timer_start(TRACE2_TIMER_ID_TEST1);
1980         ...
1981         sleep_millisec(1000); // Do something expensive
1982         ...
1983         trace2_timer_stop(TRACE2_TIMER_ID_TEST1);
1984 }
1985
1986 static int ut_100timer(int argc, const char **argv)
1987 {
1988         ...
1989
1990         expensive_function();
1991
1992         // Do something else 1...
1993
1994         expensive_function();
1995
1996         // Do something else 2...
1997
1998         expensive_function();
1999
2000         return 0;
2001 }</pre>
2002 </div>
2003 </div>
2004 <div class="paragraph">
2005 <p>In this example, we measure the total time spent in
2006 <code>expensive_function</code>() regardless of when it is called
2007 in the overall flow of the program.</p>
2008 </div>
2009 <div class="listingblock">
2010 <div class="content">
2011 <pre>$ export GIT_TRACE2_PERF_BRIEF=1
2012 $ export GIT_TRACE2_PERF=~/log.perf
2013 $ t/helper/test-tool trace2 100timer 3 1000
2014 ...
2015 $ cat ~/log.perf
2016 d0 | main                     | version      |     |           |           |              | ...
2017 d0 | main                     | start        |     |  0.001453 |           |              | t/helper/test-tool trace2 100timer 3 1000
2018 d0 | main                     | cmd_name     |     |           |           |              | trace2 (trace2)
2019 d0 | main                     | exit         |     |  3.003667 |           |              | code:0
2020 d0 | main                     | timer        |     |           |           | test         | name:test1 intervals:3 total:3.001686 min:1.000254 max:1.000929
2021 d0 | main                     | atexit       |     |  3.003796 |           |              | code:0</pre>
2022 </div>
2023 </div>
2024 </dd>
2025 </dl>
2026 </div>
2027 </div>
2028 </div>
2029 <div class="sect1">
2030 <h2 id="_future_work">Future Work</h2>
2031 <div class="sectionbody">
2032 <div class="sect2">
2033 <h3 id="_relationship_to_the_existing_trace_api_api_trace_txt">Relationship to the Existing Trace Api (api-trace.txt)</h3>
2034 <div class="paragraph">
2035 <p>There are a few issues to resolve before we can completely
2036 switch to Trace2.</p>
2037 </div>
2038 <div class="ulist">
2039 <ul>
2040 <li>
2041 <p>Updating existing tests that assume <code>GIT_TRACE</code> format messages.</p>
2042 </li>
2043 <li>
2044 <p>How to best handle custom <code>GIT_TRACE_</code><em>&lt;key&gt;</em> messages?</p>
2045 <div class="ulist">
2046 <ul>
2047 <li>
2048 <p>The <code>GIT_TRACE_</code><em>&lt;key&gt;</em> mechanism allows each &lt;key&gt; to write to a
2049 different file (in addition to just stderr).</p>
2050 </li>
2051 <li>
2052 <p>Do we want to maintain that ability or simply write to the existing
2053 Trace2 targets (and convert &lt;key&gt; to a "category").</p>
2054 </li>
2055 </ul>
2056 </div>
2057 </li>
2058 </ul>
2059 </div>
2060 </div>
2061 </div>
2062 </div>
2063 </div>
2064 <div id="footer">
2065 <div id="footer-text">
2066 Last updated 2024-09-03 13:52:44 -0700
2067 </div>
2068 </div>
2069 </body>
2070 </html>