# HTTP Logging

Sometimes, while debugging your Web app (or client-side code using
Necko), it can be useful to log HTTP traffic. This saves a log of HTTP-related
information from your browser run into a file that you can examine (or
upload to Bugzilla if a developer has asked you for a log).

:::{note}
**Note:** The [Web
Console](https://developer.mozilla.org/en-US/docs/Tools/Web_Console)
also offers the ability to peek at HTTP transactions within Firefox.
HTTP logging generally provides more detailed logging.
:::

(using-about-networking)=

## Using <about:logging>

This is the best and easiest way to do HTTP logging. At any point
during while your browser is running, you can turn logging on and off.

:::{note}
**Note:** Before Firefox 108 the logging UI used to be located at `about:networking#logging`
:::

This allows you to capture only the "interesting" part of the browser's
behavior (i.e. your bug), which makes the HTTP log much smaller and
easier to analyze.

01. Launch the browser and get it into whatever state you need to be in
    just before your bug occurs.

02. Open a new tab and type in "<about:logging>" into the URL bar.

03. Adjust the list of modules that you want to log: this list has the
    exact same format as the MOZ_LOG environment variable (see below).
    Generally the default list is OK, unless a Firefox developer has told
    you to modify it.

    - For cookie issues, use presets `Cookies`
    - For WebSocket issues, use presets `WebSockets`
    - For HTTP/3 or QUIC issues, use presets `HTTP/3`
    - For other networking issues, use presets `Networking`

04. If instructed to do so by a developer, select `Logging to a file` and
    note the path to the log file.

05. Click on Start Logging.

06. Reproduce the bug (i.e. go to the web site that is broken for you and
    make the bug happen in the browser)

07. Click on Stop Logging.

08. If logging to the profiler, a new tab will open with the profile.
    Click `Upload Local Profile` and either upload to the cloud and copy
    the URL, or download the dump to your local device. Note that
    unchecking the boxes will sanitize the profile to remove some private
    information, but that could make it more difficult to diagnose the problem.

09. Provide the link or dump to the Firefox developer via bugzilla or email.

10. If logging to a file, go to the folder containing the specified log file,
    and gather all the log files. You will see several files that look like:
    log.txt-main.1806.moz_log, log.txt-child.1954.moz_log,
    log.txt-child.1970.moz_log, etc. This is because Firefox now uses
    multiple processes, and each process gets its own log file.

11. For many bugs, the "log.txt-main.moz_log" file is the only thing you need to
    upload as a file attachment to your Bugzilla bug (this is assuming
    you're logging to help a firefox developer). Other bugs may require
    all the logs to be uploaded--ask the developer if you're not sure.

12. Pat yourself on the back--a job well done! Thanks for helping us
    debug Firefox.

:::{note}
**Note:** The log may include sensitive data such as URLs and cookies.
To protect your privacy, we kindly request you to send the log file or
the profiler link directly and confidentially to <mailto:necko@mozilla.com>.
:::

## Logging HTTP activity by manually setting environment variables

Sometimes the <about:logging> approach won't work, for instance if your
bug occurs during startup, or you're running on mobile, etc. In that
case you can set environment variables \*before\* you launch Firefox.
Note that this approach winds up logging the whole browser history, so
files can get rather large (they compress well :)

Setting environment variables differs by operating system. Don't let the
scary-looking command line stuff frighten you off; it's not hard at all!

### Windows

1. If Firefox is already running, exit out of it.

2. Open a command prompt by holding down the Windows key and pressing "R".

3. Type CMD and press enter, a new Command Prompt window with a black
   background will appear.

4. Copy and paste the following lines one at a time into the Command
   Prompt window. Press the enter key after each one.:

   **For 64-bit Windows:**

   ```
   set MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5
   set MOZ_LOG_FILE=%TEMP%\log.txt
   "c:\Program Files\Mozilla Firefox\firefox.exe"
   ```

   **For 32-bit Windows:**

   ```
   set MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5
   set MOZ_LOG_FILE=%TEMP%\log.txt
   "c:\Program Files (x86)\Mozilla Firefox\firefox.exe"
   ```

   (These instructions assume that you installed Firefox to the default
   location, and that drive C: is your Windows startup disk. Make the
   appropriate adjustments if those aren't the case.)

5. Reproduce whatever problem it is that you're having.

6. Once you've reproduced the problem, exit Firefox and look for the
   generated log files in your temporary directory. You can type
   "%TEMP%" directly into the Windows Explorer location bar to get there
   quickly.

### Linux

This section offers information on how to capture HTTP logs for Firefox
running on Linux.

1. Quit out of Firefox if it's running.

2. Open a new shell. The commands listed here assume a bash-compatible
   shell.

3. Copy and paste the following commands into the shell one at a time.
   Make sure to hit enter after each line.

   ```
   export MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5
   export MOZ_LOG_FILE=/tmp/log.txt
   cd /path/to/firefox
   ./firefox
   ```

4. Reproduce the problem you're debugging.

5. When the problem has been reproduced, exit Firefox and look for the
   generated log files, which you can find at `/tmp/log.txt`.

### macOS

These instructions show how to log HTTP traffic in Firefox on macOS.

1. Quit Firefox is if it's currently running, by using the Quit option
   in the File menu. Keep in mind that simply closing all windows does
   **not** quit Firefox on macOS (this is standard practice for Mac
   applications).

2. Run the Terminal application, which is located in the Utilities
   subfolder in your startup disk's Applications folder.

3. Copy and paste the following commands into the Terminal window,
   hitting the return key after each line.

   ```
   export MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5
   export MOZ_LOG_FILE=~/Desktop/log.txt
   cd /Applications/Firefox.app/Contents/MacOS
   ./firefox
   ```

   (The instructions assume that you've installed Firefox directly into
   your startup disk's Applications folder. If you've put it elsewhere,
   change the path used on the third line appropriately.)

4. Reproduce whatever problem you're trying to debug.

5. Quit Firefox and look for the generated `log.txt` log files on your
   desktop.

:::{note}
**Note:** The generated log file uses Unix-style line endings. Older
editors may have problems with this, but if you're using an even
reasonably modern Mac OS X application to view the log, you won't
have any problems.
:::

## Start logging using command line arguments

Since Firefox 61 it's possible to start logging in a bit simpler way
than setting environment variables: using command line arguments. Here
is an example for the **Windows** platform, on other platforms we accept
the same form of the arguments:

1. If Firefox is already running, exit out of it.

2. Open a command prompt. On [Windows
   XP](https://commandwindows.com/runline.htm), you can find the
   "Run..." command in the Start menu's "All Programs" submenu. On [all
   newer versions of
   Windows](http://www.xp-vista.com/other/where-is-run-in-windows-vista),
   you can hold down the Windows key and press "R".

3. Copy and paste the following line into the "Run" command window and
   then press enter:

   **For 32-bit Windows:**

   ```
   "c:\Program Files (x86)\Mozilla Firefox\firefox.exe" -MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5 -MOZ_LOG_FILE=%TEMP%\log.txt
   ```

   **For 64-bit Windows:**

   ```
   "c:\Program Files\Mozilla Firefox\firefox.exe" -MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5 -MOZ_LOG_FILE=%TEMP%\log.txt
   ```

   (These instructions assume that you installed Firefox to the default
   location, and that drive C: is your Windows startup disk. Make the
   appropriate adjustments if those aren't the case.)

4. Reproduce whatever problem it is that you're having.

5. Once you've reproduced the problem, exit Firefox and look for the
   generated log files in your temporary directory. You can type
   "%TEMP%" directly into the Windows Explorer location bar to get there
   quickly.

## Advanced techniques

You can adjust some of the settings listed above to change what HTTP
information get logged.

### Limiting the size of the logged data

By default there is no limit to the size of log file(s), and they
capture the logging throughout the time Firefox runs, from start to
finish. These files can get quite large (gigabytes)! So we have added
a 'rotate:SIZE_IN_MB' option to MOZ_LOG (we use it in the examples
above). If you are using Firefox >= 51, setting this option saves only
the last N megabytes of logging data, which helps keep them manageable
in size. (Unknown modules are ignored, so it's OK to use 'rotate' in
your environment even if you're running Firefox \<= 50: it will do
nothing).

This is accomplished by splitting the log into up to 4 separate files
(their filenames have a numbered extension, .0, .1, .2, .3) The logging
back end cycles the files it writes to, while ensuring that the sum of
these files’ sizes will never go over the specified limit.

Note 1: **the file with the largest number is not guaranteed to be the
last file written!** We don’t move the files, we only cycle. Using the
rotate module automatically adds timestamps to the log, so it’s always
easy to recognize which file keeps the most recent data.

Note 2: **rotate doesn’t support append**. When you specify rotate, on
every start all the files (including any previous non-rotated log file)
are deleted to avoid any mixture of information. The `append` module
specified is then ignored.

### Use 'sync' if your browser crashes or hangs

By default, HTTP logging buffers messages and only periodically writes
them to disk (this is more efficient and also makes logging less likely
to interfere with race conditions, etc). However, if you are seeing
your browser crash (or hang) you should add ",sync" to the list of
logging modules in your MOZ_LOG environment variable. This will cause
each log message to be immediately written (and fflush()'d), which is
likely to give us more information about your crash.

### Turning on QUIC logging

This can be done by setting `MOZ_LOG` to
`timestamp,rotate:200,nsHttp:5,neqo_http3::*:5,neqo_transport::*:5`.

### Logging only HTTP request and response headers

There are two ways to do this:

1. Replace MOZ_LOG`=nsHttp:5` with MOZ_LOG`=nsHttp:3` in the
   commands above.
2. There's a handy extension for Firefox called [HTTP Header
   Live](https://addons.mozilla.org/firefox/addon/3829) that you can
   use to capture just the HTTP request and response headers. This is a
   useful tool when you want to peek at HTTP traffic.

### Turning off logging of socket-level transactions

If you're not interested in socket-level log information, either because
it's not relevant to your bug or because you're debugging something that
includes a lot of noise that's hard to parse through, you can do that.
Simply remove the text `nsSocketTransport:5` from the commands above.

### Turning off DNS query logging

You can turn off logging of host resolving (that is, DNS queries) by
removing the text `nsHostResolver:5` from the commands above.

### Enable Logging for try server runs

You can enable logging on try by passing the `env` argument via `mach try`.
For example:

:::{note}
`./mach try fuzzy --env "MOZ_LOG=nsHttp:5,SSLTokensCache:5"`
:::

### Capturing a profile with logs at startup

When a bug reproduces during startup, `about:logging` is too late to capture
it. You can start the Firefox profiler together with `MOZ_LOG` so that the
log messages are interleaved with profiler samples and markers from all of the
relevant networking threads.

On Linux:

```
MOZ_PROFILER_STARTUP=1 \
MOZ_LOG='timestamp,sync,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5,EarlyHint:5' \
MOZ_PROFILER_STARTUP_FILTERS='Cache2 I/O,Compositor,DNS Resolver,DOM Worker,GeckoMain,Renderer,Socket Thread,StreamTrans,SwComposite,TRR Background' \
MOZ_PROFILER_SHUTDOWN=/tmp/profile.json \
MOZ_PROFILER_SYMBOLICATE=1 \
/path/to/firefox/firefox
```

On macOS, replace the last line with
`/Applications/Firefox.app/Contents/MacOS/firefox`. On Windows, set the
variables with `set` (as in the Windows section above) and then launch
`"c:\Program Files\Mozilla Firefox\firefox.exe"`.

If you are working from a local Firefox build, you can use `./mach run`
instead of the firefox binary path; `mach` will forward the environment
variables to the build it launches.

The thread filters cover the main networking-related threads
(`Socket Thread`, `DNS Resolver`, `Cache2 I/O`, `StreamTrans`,
`TRR Background`) as well as `GeckoMain`, `DOM Worker` and the
compositor/renderer threads, which is usually what you want when diagnosing a
startup networking issue. `sync` is included in `MOZ_LOG` so that no log
messages are lost if Firefox crashes during startup.

When Firefox exits the profile is written to `/tmp/profile.json`. Open it
on https://profiler.firefox.com to inspect it, or upload it and share the
resulting link.

### How to enable QUIC logging

The steps to enable QUIC logging ([QLOG](https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/)) are:

1. Go to `about:config`, search for `network.http.http3.enable_qlog` and set it to true.
2. Restart Firefox.
3. QLOG files will be saved in the `qlog_$PID` directory located within your system's temporary directory.
4. To visualize the QLOG data, visit <https://qvis.quictools.info/>. You can upload the QLOG files there to see the visual representation of the flows.

## See also

- There are similar options available to debug mailnews protocols.
  See [this
  document](https://www-archive.mozilla.org/quality/mailnews/mail-troubleshoot.html) for
  more info about mailnews troubleshooting.
- On the Windows platform, nightly Firefox builds have FTP logging
  built-in (don't ask why this is only the case for Windows!). To
  enable FTP logging, just set `MOZ_LOG=nsFtp:5` (in older versions
  of Mozilla, you need to use `nsFTPProtocol` instead of `nsFtp`).
- When Mozilla's built-in logging capabilities aren't good enough, and
  you need a full-fledged packet tracing tool, two free products are
  [Wireshark](https://www.wireshark.org/)
  and [ngrep](https://github.com/jpr5/ngrep/). They are available
  for Windows and most flavors of UNIX (including Linux and Mac OS
  X), are rock solid, and offer enough features to help uncover any
  Mozilla networking problem.
