curl_global_trace.md (5462B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: curl_global_trace 5 Section: 3 6 Source: libcurl 7 See-also: 8 - curl_global_init (3) 9 - libcurl (3) 10 Protocol: 11 - All 12 Added-in: 8.3.0 13 --- 14 15 # NAME 16 17 curl_global_trace - log configuration 18 19 # SYNOPSIS 20 21 ~~~c 22 #include <curl/curl.h> 23 24 CURLcode curl_global_trace(const char *config); 25 ~~~ 26 27 # DESCRIPTION 28 29 This function configures the logging behavior to make some parts of curl more 30 verbose or silent than others. 31 32 This function may be called during the initialization phase of a program. It 33 does not have to be. It can be called several times even, possibly overwriting 34 settings of previous calls. 35 36 Calling this function after transfers have been started is undefined. On some 37 platforms/architectures it might take effect, on others not. 38 39 This function is thread-safe since libcurl 8.3.0 if curl_version_info(3) has 40 the CURL_VERSION_THREADSAFE feature bit set (most platforms). 41 42 If this is not thread-safe, you must not call this function when any other 43 thread in the program (i.e. a thread sharing the same memory) is running. This 44 does not just mean no other thread that is using libcurl. Because 45 curl_global_init(3) may call functions of other libraries that are similarly 46 thread unsafe, it could conflict with any other thread that uses these other 47 libraries. 48 49 If you are initializing libcurl from a Windows DLL you should not initialize 50 it from *DllMain* or a static initializer because Windows holds the loader 51 lock during that time and it could cause a deadlock. 52 53 The *config* string is a list of comma-separated component names. Names are 54 case-insensitive and unknown names are ignored. The special name "all" applies 55 to all components. Names may be prefixed with '+' or '-' to enable or disable 56 detailed logging for a component. 57 58 The list of component names is not part of curl's public API. Names may be 59 added or disappear in future versions of libcurl. Since unknown names are 60 silently ignored, outdated log configurations does not cause errors when 61 upgrading libcurl. Given that, some names can be expected to be fairly stable 62 and are listed below for easy reference. 63 64 Note that log configuration applies only to transfers where debug logging is 65 enabled. See CURLOPT_VERBOSE(3) or CURLOPT_DEBUGFUNCTION(3) on how to control 66 that. 67 68 # TRACE COMPONENTS 69 70 ## `tcp` 71 72 Tracing of TCP socket handling: connect, sends, receives. 73 74 ## `ssl` 75 76 Tracing of SSL/TLS operations, whichever SSL backend is used in your build. 77 78 ## `ftp` 79 80 Tracing of FTP operations when this protocol is enabled in your build. 81 82 ## `http/2` 83 84 Details about HTTP/2 handling: frames, events, I/O, etc. 85 86 ## `http/3` 87 88 Details about HTTP/3 handling: connect, frames, events, I/O etc. 89 90 ## `http-proxy` 91 92 Involved when transfers are tunneled through an HTTP proxy. "h1-proxy" or 93 "h2-proxy" are also involved, depending on the HTTP version negotiated with 94 the proxy. 95 96 In order to find out all components involved in a transfer, run it with "all" 97 configured. You can then see all names involved in your libcurl version in the 98 trace. 99 100 ## `dns` 101 102 Tracing of DNS operations to resolve hostnames and HTTPS records. 103 104 ## `lib-ids` 105 106 Adds transfer and connection identifiers as prefix to every call to 107 CURLOPT_DEBUGFUNCTION(3). The format is `[n-m]` where `n` is the identifier 108 of the transfer and `m` is the identifier of the connection. A literal `x` 109 is used for internal transfers or when no connection is assigned. 110 111 For example, `[5-x]` is the prefix for transfer 5 that has no 112 connection. The command line tool `curl`uses the same format for its 113 `--trace-ids` option. 114 115 `lib-ids` is intended for libcurl applications that handle multiple 116 transfers but have no own way to identify in trace output which transfer 117 a trace event is connected to. 118 119 ## `doh` 120 121 Former name for DNS-over-HTTP operations. Now an alias for `dns`. 122 123 ## `multi` 124 125 Traces multi operations managing transfers' state changes and sockets poll 126 states. 127 128 ## `read` 129 130 Traces reading of upload data from the application in order to send it to the 131 server. 132 133 ## `ssls` 134 135 Tracing of SSL Session handling, e.g. caching/import/export. 136 137 ## `smtp` 138 139 Tracing of SMTP operations when this protocol is enabled in your build. 140 141 ## `write` 142 143 Traces writing of download data, received from the server, to the application. 144 145 ## `ws` 146 147 Tracing of WebSocket operations when this protocol is enabled in your build. 148 149 # TRACE GROUPS 150 151 Besides the specific component names there are the following group names 152 defined: 153 154 ## `all` 155 156 ## `network` 157 158 All components involved in bare network I/O, including the SSL layer. 159 160 All components that your libcurl is built with. 161 162 ## `protocol` 163 164 All components involved in transfer protocols, such as 'ftp' and 'http/2'. 165 166 ## `proxy` 167 168 All components involved in use of proxies. 169 170 # %PROTOCOLS% 171 172 # EXAMPLE 173 174 ~~~c 175 int main(void) 176 { 177 /* log details of HTTP/2 and SSL handling */ 178 curl_global_trace("http/2,ssl"); 179 180 /* log all details, except SSL handling */ 181 curl_global_trace("all,-ssl"); 182 } 183 ~~~ 184 185 Below is a trace sample where "http/2" was configured. The trace output 186 of an enabled component appears at the beginning in brackets. 187 ~~~ 188 * [HTTP/2] [h2sid=1] cf_send(len=96) submit https://example.com/ 189 ... 190 * [HTTP/2] [h2sid=1] FRAME[HEADERS] 191 * [HTTP/2] [h2sid=1] 249 header bytes 192 ... 193 ~~~ 194 195 # %AVAILABILITY% 196 197 # RETURN VALUE 198 199 If this function returns non-zero, something went wrong and the configuration 200 may not have any effects or may only been applied partially.