From e281d0b1ba6235692077408bbf4d71ede92bf130 Mon Sep 17 00:00:00 2001 From: ShryukGrandhi <85529990+ShryukGrandhi@users.noreply.github.com> Date: Wed, 21 Oct 2026 23:07:28 -0700 Subject: [PATCH] Add a user docs page about recording logs with about:logging Signed-off-by: ShryukGrandhi <85529990+ShryukGrandhi@users.noreply.github.com> --- docs-user/_sidebar.md | 1 + docs-user/advanced-topics.md | 1 + docs-user/guide-about-logging.md | 92 +++++++++++++++++++ ...de-profiling-android-directly-on-device.md | 4 + 4 files changed, 98 insertions(+) create mode 100644 docs-user/guide-about-logging.md diff --git a/docs-user/_sidebar.md b/docs-user/_sidebar.md index 04bb5e0956..bcd99fe0f9 100644 --- a/docs-user/_sidebar.md +++ b/docs-user/_sidebar.md @@ -16,6 +16,7 @@ - [Perf profiling on Android](./guide-android-profiling.md) - [IPC Messages](./ipc-messages.md) - [Profiler control using POSIX signals](./async-posix-signal-control.md) + - [Recording logs with about:logging](./guide-about-logging.md) - [Video Tutorials](./videos.md) - [Firefox Profiler intro](./videos-intro.md) - [Samples and markers](./videos-samples-markers.md) diff --git a/docs-user/advanced-topics.md b/docs-user/advanced-topics.md index ae3f3605fe..2adde645b4 100644 --- a/docs-user/advanced-topics.md +++ b/docs-user/advanced-topics.md @@ -8,3 +8,4 @@ developers of the Firefox browser. - [Perf profiling on Android](./guide-android-profiling.md) - [IPC Messages](./ipc-messages.md) - [Profiler control using POSIX signals](./async-posix-signal-control.md) +- [Recording logs with about:logging](./guide-about-logging.md) diff --git a/docs-user/guide-about-logging.md b/docs-user/guide-about-logging.md new file mode 100644 index 0000000000..7957e69169 --- /dev/null +++ b/docs-user/guide-about-logging.md @@ -0,0 +1,92 @@ +# Recording logs with about:logging + +Firefox has a logging system called `MOZ_LOG` that lets Gecko code write +detailed log statements for a module (for example `nsHttp` for networking, or +`cubeb` for audio). Logging is usually turned on with environment variables, +but the `about:logging` page lets you turn it on from inside the browser, +without restarting it. + +`about:logging` can send log statements to the Firefox Profiler. Each log +statement on a profiled thread is recorded as a marker, so the logs show up +next to samples and other markers in the profile. This is often easier than +logging to a file: + +- It works in all processes, including sandboxed content processes, which can't + write log files to disk. +- The result is a single profile that can be uploaded and shared, for example + in a Bugzilla bug. +- It works on Firefox for Android, where getting log files off the device is + hard. + +More details about `MOZ_LOG` itself can be found in the +[Gecko logging documentation](https://firefox-source-docs.mozilla.org/xpcom/logging.html). + +## Recording a profile with logs + +1. Open a new tab and type `about:logging` in the URL bar. +2. Pick a preset from the drop-down that matches what you want to look at + (for example, networking or media playback). A preset selects a set of log + modules, and the profiler settings (threads and features) that go with them. + If no preset fits, you can type your own list of modules in the text field, + using the `MOZ_LOG` syntax, for example `nsHttp:5,cookie:5`. +3. Choose to send the logs to the Firefox Profiler as the output. +4. Start logging, then reproduce the problem. +5. Stop logging. The profile is captured and opened in the Firefox Profiler, + from where you can upload it like any other profile. + +## Log levels + +Each module in the `MOZ_LOG` string is followed by a level. Higher levels +include all the lower ones and produce more output: + +| Level | Name | +| ----- | -------- | +| 0 | Disabled | +| 1 | Error | +| 2 | Warning | +| 3 | Info | +| 4 | Debug | +| 5 | Verbose | + +Some special options can also be added to the list. One that is useful with the +profiler is `profilerstacks`, which captures a stack for every log statement. +Keep in mind that this adds overhead. + +## Configuring about:logging with URL parameters + +The page can be configured from its URL, which is handy to share a setup with +someone else, or to type it quickly on a phone. The supported parameters are: + +- `preset`: the name of a logging preset. +- `modules`: a list of log modules, using the `MOZ_LOG` syntax. +- `threads`: the threads that the profiler should record. +- `output`: either `profiler` or `file`. +- `profiler-preset`: the name of a profiler preset. + +When a preset is selected, `modules` and `threads` override only that part of +the preset. For example, this URL uses the media playback preset, but only +enables the listed log modules: + +``` +about:logging?output=profiler&preset=media-playback&modules=cubeb:4,AudioSinkWrapper:4,AudioSink:4 +``` + +## Using about:logging on Firefox for Android + +`about:logging` is available on Firefox for Android too. Type `about:logging` in +the URL bar and follow the same steps as on desktop. Logging to the profiler is +the most practical choice on Android, because you don't need a computer or to +fetch log files from the device. This complements the profiler controls that +are available in the +[secret settings](./guide-profiling-android-directly-on-device.md). + +## Looking at the logs in the profile + +Log statements are recorded as markers, named after their log module. You can +find them in the [Marker Chart and Marker Table](./guide-ui-tour-panels.md), +and use the search field to filter them by module name or message. + +To get the logs out of the profile as text, open the Web Console on the +profiler page and run `copy(extractGeckoLogs())`. This copies the logs within +the current range selection to the clipboard, using the `MOZ_LOG` format. You +can also save them to a file with `saveToDisk(extractGeckoLogs(), 'logs.txt')`. diff --git a/docs-user/guide-profiling-android-directly-on-device.md b/docs-user/guide-profiling-android-directly-on-device.md index 262ffe178d..9f6a5bb496 100644 --- a/docs-user/guide-profiling-android-directly-on-device.md +++ b/docs-user/guide-profiling-android-directly-on-device.md @@ -33,3 +33,7 @@ To enable secret settings, follow these steps: - Scroll to the bottom and you should see a "Stop profiler" option has replaced the "Start Profiler" one. - After you click it, you should see a dialogue with a warning regarding the information contained in the profile. - Once stopped, the URL for the profile that finished recording will be copied to your clipboard which you can then use to share. + +## Recording logs on the device + +If you also need Gecko logs, you can use `about:logging` directly on the device to record them into a profile. See [Recording logs with about:logging](./guide-about-logging.md).