Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
uBlock Origin comes with a logger, which gives the ability to inspect what uBlock is doing with network requests and DOM elements, whether something is blocked or allowed, and which filter, if any, matched a network request or DOM element. This logger is unified, meaning it will display everything uBlock does as it occurs.
The logger is the tool of choice to see, understand, diagnose and fix the functioning of uBlock.
To access the logger, click on the list icon of uBlock Origin's popup UI:
The request logger will open in a new tab (which was moved to its own window below):
The color of a row hints at how the resource was filtered:
- No color: The request for the resource was allowed to go through because it matched no filter/rule.
- Red: The request for the resource was canceled (
--) because of a block filter/rule.
- Green: The request for the resource was allowed to go through (
++) because it matched a filter/rule whose purpose is to bypass a matching block filter/rule.
- A DOM element which was blocked by a cosmetic filter; OR
- A blocked request for a resource was redirected (
<<) to a local replacement resource.
When a resource is blocked/allowed/hidden/redirected, the 3rd column in the row will provide further information. For blocked/allowed/hidden resources, the column will contains the responsible filter. For redirection, the column will contains the local resource used as replacement to the blocked network request.
Take note that the network request logger in uBlock is a forward-looking logger: this means only future requests can be logged.
In the spirit of efficiency, uBlock will log entries IF AND ONLY IF the logger is opened. Otherwise, if the logger is not opened, no CPU/memory resources are consumed by uBlock for logging purpose.
Hold the Shift key while clicking the "Open the logger" icon to toggle between opening the logger in a separate window or in a separate tab. uBO will remember that setting when you open the logger next time, without having to hold the Shift key.
- Page selector
- DOM inspector
- Void log entries
- Filtering the logger output
- Maximum number of entries
- Accessing popup UI of a specific page
- Finding from which list(s) a static filter originates
- Creating filters
The drop-down selector is to display log entries which are related to a specific page. This will hide from view all log entries which are not related to the selected page. By selecting All again, all log entries will be displayed again.
Note in the figure above the entry named "Behind the scene": selecting this entry allows to show only behind-the-scene network requests. Behind-the-scene network requests are requests which do not originate from any specific tab, and are denoted by the eye-slash icon in the second column. More about behind-the-scene network requests here.
The big reload button aside the page selector is to force a reload of the content of the selected page. This button is enabled only for when a specific page is selected.
Complementary tool to the element picker.
Please read more on dedicated page: "DOM inspector"
By default log entries in the logger are collapsed so as to take no more than one line. Some log entries however might be truncated as a result. This button is to force all those entries with truncated extraneous information to be fully visible.
Void log entries
The logger is unified, i.e. it display all network requests from all tabs at once. If you close a tab for which there are entries in the logger, these entries will be marked as void, i.e. a bold
X will appear in the second column of these entries, to indicate the tab for these entries does not exist anymore.
X button in the toolbar allows you to remove those void entries from the logger.
This is to clear the logger, to remove all entries from the selected context (Ars Technica tab in this example).
Filtering the logger output
You can visually filter entries in the logger using filter expressions. Log entries which do not match all filter expressions will be hidden from view. Syntax for a filter expression:
footo only show entries which have a string
|footo only show entries which have a field starting with
- Tip: use
|--to show only entries which were blocked (
--may work for the most part, but there could be false positives).
- Tip: use
foo|to only show entries which have a field ending with
|foo|to only show entries which have exactly a field with
- Prefix any expression with
!to reverse the meaning of the expression.
!foomeans display only entries which do not have the string
!|--means display only entries which were not blocked.
- When more than one filter expression appear, a logical and between the expressions is implied.
- You can or multiple expressions together:
css || imagemeans display entries which match either
xhr || other |http:means display entries which match either
otherand have a field which starts with
!css || imagemeans display entries which do not match either
- Warning: With or'ed expressions, the not (
!) operator can only apply to the resulting or'ed expression.
- A special keyword can be used to filter behind-the-scene requests:
|btsfor a stricter filtering.
|xhr google: show only entries of type
XMLHttpRequestwith the word
!|image !|css: show only entries which are not of type
Maximum number of entries
This is the maximum number of entries allowed in the logger. When the maximum is reached, the oldest entries at the bottom will be removed to make place to newest entries at the top.
This is useful to be sure the logger does not unduly consume a huge amount of memory if left open for long period of time. Usually, the most recent entries are the ones of interest. When this value is not set, there is a built-in limit of 5,000 entries.
Accessing popup UI of a specific page
You can access the popup UI of a specific tab by clicking the second cell in a log entry.
This will cause all entries in the logger which are unrelated to the currently opened popup to be dimmed.
Finding from which list(s) a static filter originates
You can find out from which filter list(s) a static filter originates, by simply clicking on it:
When the filter list is rendered as a link, clicking on it will bring you to the support site for that list.
Clicking on the 4th cell of a log entry will give you access to the filtering tools dialog (modal), from where you can easily create dynamic URL filtering rules or just standard static filters, and launch the element picker.
Dynamic URL filtering rules
Point-and-click to create dynamic URL filtering rules. These rules are temporary by default, you need to click the padlock if you want them to be permanent. Useful to find out which network requests need to be blocked or allowed on a page in order, to fix a broken page, or to further block more useless resources from a page.
See "Overview of uBlock's network filtering engine: details" for more details about where dynamic URL filtering fits in the overall filtering engine.
Static network filters
This dialog will assist you in creating static filters compatible with ABP filter syntax. Note that creating static filters incur a significant overhead relative to dynamic URL filtering rules. Typically, you will first use dynamic URL filtering rules to quickly diagnose which network requests need to be allowed/blocked.
See "Overview of uBlock's network filtering engine: details" for more details about where static filtering fits in the overall filtering engine.