1HTTP Logging 2============ 3 4 5Sometimes, while debugging your Web app (or client-side code using 6Necko), it can be useful to log HTTP traffic. This saves a log of HTTP-related 7information from your browser run into a file that you can examine (or 8upload to Bugzilla if a developer has asked you for a log). 9 10.. note:: 11 12 **Note:** The `Web 13 Console <https://developer.mozilla.org/en-US/docs/Tools/Web_Console>`__ 14 also offers the ability to peek at HTTP transactions within Firefox. 15 HTTP logging generally provides more detailed logging. 16 17Using about:networking 18---------------------- 19 20This is the best and easiest way to do HTTP logging. At any point 21during while your browser is running, you can turn logging on and off. 22This allows you to capture only the "interesting" part of the browser's 23behavior (i.e. your bug), which makes the HTTP log much smaller and 24easier to analyze. 25 26#. Launch the browser and get it into whatever state you need to be in 27 just before your bug occurs. 28#. Open a new tab and type in "about:networking" into the URL bar. 29#. Go to the "Logging section" 30#. Adjust the location of the log file if you don't like the default 31#. Adjust the list of modules that you want to log: this list has the 32 exact same format as the MOZ_LOG environment variable (see below). 33 Generally the default list is OK, unless a Mozilla developer has told 34 you to modify it. 35#. Click on Start Logging. 36#. Reproduce the bug (i.e. go to the web site that is broken for you and 37 make the bug happen in the browser) 38#. Make a note of the value of "Current Log File". 39#. Click on Stop Logging. 40#. Go to the folder containing the specified log file, and gather all 41 the log files. You will see several files that look like: 42 log.txt-main.1806, log.txt-child.1954, log.txt-child.1970, etc. This 43 is because Firefox now uses multiple processes, and each process gets 44 its own log file. 45#. For many bugs, the "log.txt-main" file is the only thing you need to 46 upload as a file attachment to your Bugzilla bug (this is assuming 47 you're logging to help a mozilla developer). Other bugs may require 48 all the logs to be uploaded--ask the developer if you're not sure. 49#. Pat yourself on the back--a job well done! Thanks for helping us 50 debug Firefox. 51 52Logging HTTP activity by manually setting environment variables 53--------------------------------------------------------------- 54 55Sometimes the about:networking approach won't work, for instance if your 56bug occurs during startup, or you're running on mobile, etc. In that 57case you can set environment variables \*before\* you launch Firefox. 58Note that this approach winds up logging the whole browser history, so 59files can get rather large (they compress well :) 60 61Setting environment variables differs by operating system. Don't let the 62scary-looking command line stuff frighten you off; it's not hard at all! 63 64Windows 65~~~~~~~ 66 67#. If Firefox is already running, exit out of it. 68 69#. Open a command prompt by holding down the Windows key and pressing "R". 70 71#. Type CMD and press enter, a new Command Prompt window with a black 72 background will appear. 73 74#. | Copy and paste the following lines one at a time into the Command 75 Prompt window. Press the enter key after each one.: 76 | **For 64-bit Windows:** 77 78 :: 79 80 set MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5,cookie:5 81 set MOZ_LOG_FILE=%TEMP%\log.txt 82 "c:\Program Files\Mozilla Firefox\firefox.exe" 83 84 **For 32-bit Windows:** 85 86 :: 87 88 set MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5,cookie:5 89 set MOZ_LOG_FILE=%TEMP%\log.txt 90 "c:\Program Files (x86)\Mozilla Firefox\firefox.exe" 91 92 (These instructions assume that you installed Firefox to the default 93 location, and that drive C: is your Windows startup disk. Make the 94 appropriate adjustments if those aren't the case.) 95 96#. Reproduce whatever problem it is that you're having. 97 98#. Once you've reproduced the problem, exit Firefox and look for the 99 generated log files in your temporary directory. You can type 100 "%TEMP%" directly into the Windows Explorer location bar to get there 101 quickly. 102 103Linux 104~~~~~ 105 106This section offers information on how to capture HTTP logs for Firefox 107running on Linux. 108 109#. Quit out of Firefox if it's running. 110 111#. Open a new shell. The commands listed here assume a bash-compatible 112 shell. 113 114#. Copy and paste the following commands into the shell one at a time. 115 Make sure to hit enter after each line. 116 117 :: 118 119 export MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5,cookie:5 120 export MOZ_LOG_FILE=/tmp/log.txt 121 cd /path/to/firefox 122 ./firefox 123 124#. Reproduce the problem you're debugging. 125 126#. When the problem has been reproduced, exit Firefox and look for the 127 generated log files, which you can find at ``/tmp/log.txt``. 128 129Mac OS X 130~~~~~~~~ 131 132These instructions show how to log HTTP traffic in Firefox on Mac OS X. 133 134#. Quit Firefox is if it's currently running, by using the Quit option 135 in the File menu. Keep in mind that simply closing all windows does 136 **not** quit Firefox on Mac OS X (this is standard practice for Mac 137 applications). 138 139#. Run the Terminal application, which is located in the Utilities 140 subfolder in your startup disk's Applications folder. 141 142#. Copy and paste the following commands into the Terminal window, 143 hitting the return key after each line. 144 145 :: 146 147 export MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5,cookie:5 148 export MOZ_LOG_FILE=~/Desktop/log.txt 149 cd /Applications/Firefox.app/Contents/MacOS 150 ./firefox-bin 151 152 (The instructions assume that you've installed Firefox directly into 153 your startup disk's Applications folder. If you've put it elsewhere, 154 change the path used on the third line appropriately.) 155 156#. Reproduce whatever problem you're trying to debug. 157 158#. Quit Firefox and look for the generated ``log.txt`` log files on your 159 desktop. 160 161.. note:: 162 163 **Note:** The generated log file uses Unix-style line endings. Older 164 editors may have problems with this, but if you're using an even 165 reasonably modern Mac OS X application to view the log, you won't 166 have any problems. 167 168Start logging using command line arguments 169------------------------------------------ 170 171Since Firefox 61 it's possible to start logging in a bit simpler way 172than setting environment variables: using command line arguments. Here 173is an example for the **Windows** platform, on other platforms we accept 174the same form of the arguments: 175 176#. If Firefox is already running, exit out of it. 177 178#. Open a command prompt. On `Windows 179 XP <https://commandwindows.com/runline.htm>`__, you can find the 180 "Run..." command in the Start menu's "All Programs" submenu. On `all 181 newer versions of 182 Windows <http://www.xp-vista.com/other/where-is-run-in-windows-vista>`__, 183 you can hold down the Windows key and press "R". 184 185#. | Copy and paste the following line into the "Run" command window and 186 then press enter: 187 | **For 32-bit Windows:** 188 189 :: 190 191 "c:\Program Files (x86)\Mozilla Firefox\firefox.exe" -MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5,cookie:5 -MOZ_LOG_FILE=%TEMP%\log.txt 192 193 **For 64-bit Windows:** 194 195 :: 196 197 "c:\Program Files\Mozilla Firefox\firefox.exe" -MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5,cookie:5 -MOZ_LOG_FILE=%TEMP%\log.txt 198 199 (These instructions assume that you installed Firefox to the default 200 location, and that drive C: is your Windows startup disk. Make the 201 appropriate adjustments if those aren't the case.) 202 203#. Reproduce whatever problem it is that you're having. 204 205#. Once you've reproduced the problem, exit Firefox and look for the 206 generated log files in your temporary directory. You can type 207 "%TEMP%" directly into the Windows Explorer location bar to get there 208 quickly. 209 210Advanced techniques 211------------------- 212 213You can adjust some of the settings listed above to change what HTTP 214information get logged. 215 216Limiting the size of the logged data 217~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 218 219By default there is no limit to the size of log file(s), and they 220capture the logging throughout the time Firefox runs, from start to 221finish. These files can get quite large (gigabytes)! So we have added 222a 'rotate:SIZE_IN_MB' option to MOZ_LOG (we use it in the examples 223above). If you are using Firefox >= 51, setting this option saves only 224the last N megabytes of logging data, which helps keep them manageable 225in size. (Unknown modules are ignored, so it's OK to use 'rotate' in 226your environment even if you're running Firefox <= 50: it will do 227nothing). 228 229This is accomplished by splitting the log into up to 4 separate files 230(their filenames have a numbered extension, .0, .1, .2, .3) The logging 231back end cycles the files it writes to, while ensuring that the sum of 232these files’ sizes will never go over the specified limit. 233 234Note 1: **the file with the largest number is not guaranteed to be the 235last file written!** We don’t move the files, we only cycle. Using the 236rotate module automatically adds timestamps to the log, so it’s always 237easy to recognize which file keeps the most recent data. 238 239Note 2: **rotate doesn’t support append**. When you specify rotate, on 240every start all the files (including any previous non-rotated log file) 241are deleted to avoid any mixture of information. The ``append`` module 242specified is then ignored. 243 244Use 'sync' if your browser crashes or hangs 245~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 246 247By default, HTTP logging buffers messages and only periodically writes 248them to disk (this is more efficient and also makes logging less likely 249to interfere with race conditions, etc). However, if you are seeing 250your browser crash (or hang) you should add ",sync" to the list of 251logging modules in your MOZ_LOG environment variable. This will cause 252each log message to be immediately written (and fflush()'d), which is 253likely to give us more information about your crash. 254 255Logging only HTTP request and response headers 256~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 257 258There are two ways to do this: 259 260#. Replace MOZ_LOG\ ``=nsHttp:5`` with MOZ_LOG\ ``=nsHttp:3`` in the 261 commands above. 262#. There's a handy extension for Firefox called `HTTP Header 263 Live <https://addons.mozilla.org/firefox/addon/3829>`__ that you can 264 use to capture just the HTTP request and response headers. This is a 265 useful tool when you want to peek at HTTP traffic. 266 267Turning off logging of socket-level transactions 268~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 269 270If you're not interested in socket-level log information, either because 271it's not relevant to your bug or because you're debugging something that 272includes a lot of noise that's hard to parse through, you can do that. 273Simply remove the text ``nsSocketTransport:5`` from the commands above. 274 275Turning off DNS query logging 276~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 277 278You can turn off logging of host resolving (that is, DNS queries) by 279removing the text ``nsHostResolver:5`` from the commands above. 280 281Enable Logging for try server runs 282~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 283 284You can enable PR_LOGGING on try by hacking build/automation.py.in, in 285'def environment'. For example: 286 287.. note:: 288 289 ``def environment(... env['MOZ_LOG'] = 'nsHttp:5' return env`` 290 291See also 292-------- 293 294- There are similar options available to debug mailnews protocols. 295 See `this 296 document <https://www-archive.mozilla.org/quality/mailnews/mail-troubleshoot.html>`__ for 297 more info about mailnews troubleshooting. 298- On the Windows platform, nightly Firefox builds have FTP logging 299 built-in (don't ask why this is only the case for Windows!). To 300 enable FTP logging, just set ``MOZ_LOG=nsFtp:5`` (in older versions 301 of Mozilla, you need to use ``nsFTPProtocol`` instead of ``nsFtp``). 302- When Mozilla's built-in logging capabilities aren't good enough, and 303 you need a full-fledged packet tracing tool, two free products are 304 `Wireshark <https://www.wireshark.org/>`__ 305 and `ngrep <https://github.com/jpr5/ngrep/>`__. They are available 306 for Windows and most flavors of UNIX (including Linux and Mac OS 307 X), are rock solid, and offer enough features to help uncover any 308 Mozilla networking problem. 309