Debugging cookbook
Part 3 of 3 on debugging Attribution Reporting. Find instructions for how to use debug reports.
Published on • Updated on
Developer Relations Engineer for security/privacy, Chrome and web
Technical Writer, Google Chrome
This article is part of a series on debugging the Attribution Reporting API. This series covers client-side debugging for event-level reports and aggregatable reports. Server-side debugging guidance for summary reports is available here. A handbook for API integration is available here.
In this cookbook, you’ll find instructions for how to use debug reports for various use cases outlined in Part 1: Introduction to debug reports.
Glossary
Glossary
- The reporting origin is the origin that sets the Attribution Reporting source and trigger headers. All reports generated by the browser are sent to this origin. In this guidance, we use
https://adtech.exampleas the example reporting origin. - An attribution report (report for short) is the final report (event-level or aggregatable) that contains the measurement data you've requested.
- A debug report contains additional data about an attribution report, or about a source or trigger event. Receiving a debug report does not necessarily mean that something is working incorrectly! There are two types of debug reports
- A transitional debug report is a debug report that requires a cookie to be set in order to be generated and sent. Transitional debug reports will be unavailable if a cookie is not set, and once third-party cookies are deprecated. All debug reports described in this guide are transitional debug reports.
- Success debug reports track successful generation of an attribution report. They relate directly to an attribution report. Success debug reports have been available since Chrome 101 (April 2022).
- Verbose debug reports can track missing reports and help you determine why they're missing. They indicate cases where the browser did not record a source or trigger event, (which means it will not generate an attribution report), and cases where an attribution report can't be generated or sent for some reason. Verbose debug reports include a
typefield that describes the reason why a source event, trigger event or attribution report was not generated. Verbose debug reports are available starting in Chrome 109 (Stable in January 2023). - Debug keys are unique identifiers you can set on both the source side and the trigger side. Debug keys enable you to map cookie-based conversions and attribution-based conversions. When you've set up your system to generate debug reports and set debug keys, the browser will include these debug keys in all attribution reports and debug reports.
For more concepts and key terms used throughout our documentation, refer to the Privacy Sandbox glossary.
How-to: Check your integration in real time
- Set up your system to generate success debug reports. See how in Part 2: Set up Debug reports.
- Whenever you deploy Attribution Reporting code, check in real time if you're receiving some success debug reports on your endpoint. If so, your Attribution Reporting setup is working.
- Success debug reports are only sent when a conversion takes place. Instead, you may want to check that your integration is properly set up regardless of conversions—that is, you want to check that sources are successfully registered. To achieve this, you can rely on source registration success verbose debug reports. See how to set them up in Part 2: Set up Debug reports.
This is only a basic check. Your implementation may still contain bugs, and other factors will cause measurement data loss. For more advanced checks, review the other use cases.
How-to: Analyze loss and troubleshoot your integration
To compare cookie-based conversion measurement results with Attribution Reporting reports, use debug keys and map cookie conversions with debug reports. Remember that debug reports are sent immediately to your endpoint.
Overview
Use the debug keys (<source_debug_key, trigger_debug_key> pair) to map cookie conversions to success debug reports. For each cookie conversion, at conversion time, did you receive a corresponding success debug report?
If yes: for all of these success debug reports, you can expect to receive an attribution report later—with a few exceptions. Review the Success debug report scenario for details.
If not: this means that the conversion didn’t register with Attribution Reporting. Use the <source_debug_key, trigger_debug_key> pair (or source debug key if the trigger debug key is absent) to map cookie conversions to verbose debug reports. For each of these conversions, did you at some point (source or trigger time) receive a corresponding verbose debug report?
If you did not receive a verbose debug report: this may be due to user behavior or to an integration issue. Review the no debug report scenario for details.
If you did receive a verbose debug report, look at its
typefield.If its
typeissource-success: this means the source was successfully registered, but the trigger wasn't. To narrow down the reason why the success debug report is missing, look for a corresponding verbose debug report of any other type⏤that report will indicate an issue on the trigger side.If its
typeis anything else: the source or trigger has not been registered.typetells you why. The corresponding attribution report (and success debug report) will be missing. Depending on thetypeof a verbose debug report, you may want to just take this information as a loss analysis data point (in other words, no action for you), or you may want to file a bug or troubleshoot your implementation. Review the verbose debug report scenario for details.
Success debug reports are sent when the browser successfully generates the event-level report or aggregatable report. Most verbose debug reports, on the other hand, are sent when a source or trigger is not registered successfully—except for the source registration success verbose debug report.
In this overview, we're describing how to run a comprehensive analysis, including troubleshooting potential implementation issues.
However, you may be in a testing phase where you want to solely focus on eliminating implementation issues, without necessarily running a comprehensive loss analysis and waiting for a given set of conversions. In that case, you can directly look into specific verbose reports types that may indicate implementation issues as you receive them.
Possible scenarios
Success debug report
If for a given cookie conversion, you received a success debug report, this means that this conversion was successfully registered with Attribution Reporting.
You can expect to receive later an attribution report for this conversion⏤with a few exceptions:
- User behavior: clearing data after conversion and before the attribution report is sent, closing their browser, etc. If a user closes their browser after converting and does not open their browser for a week, the report won't be sent for a week or more. You may consider this delay as a loss.
- Applicable to Event-Level only: An event-level report is replaced by another higher priority report.
- Possible network issues.
When the browser tries to send a report but fails because of network issues, it retries twice before eventually giving up.
Verbose debug report of type source-success
If for the source of a given cookie conversion, you received a verbose debug report of type source-success, this means that the source registration was successful. Depending on whether trigger registration is also later successful, you may or may not receive a report for that conversion.
There is one caveat to this:
The source registration success verbose debug report is sent even if the unattributed reporting origin limit is reached. It's sent for security reasons, even though the source registration isn't actually successful in that case.
Verbose debug report of any other type
If for a given cookie conversion, you received a verbose debug report of any other type, you won't receive a success debug report, and hence later no attribution report⏤because a verbose report means that a reportable failure took place. Something prevented source registration, trigger registration, report generation or report sending. Possible causes:
- Privacy limits
- Storage limits
- Custom rules
- Implementation issue in your code
- Browser bug
Some of these are expected! Which action to take depends on each verbose report's type. Review the verbose reports reference.
No debug reports
If for a given cookie conversion, you received only an attribution report (no success debug report nor verbose debug report), this means that something prevented the debug reports from being generated. Possible causes:
- User preferences (the user has turned off third-party cookies)
- Missing cookie, or missing debug keys (debug key cleared due to a missing cookie). In
chrome://attribution-internals, open the Logs tab and check if any issue is surfaced there. - Network issues that occurred at source or trigger time, but not when the attribution report was sent.
Are you receiving attribution reports?
This is a subcase of not receiving a debug report: if for a given cookie conversion, you didn't receive reports of any kind (no debug report of any kind, no attribution report), this means that a non-reportable failure took place. Possible causes:
- Fundamental integration issue. Review how to troubleshoot these in Fix fundamental integration issues.
- Possible network issues.
- User preferences in browser settings, e.g. Privacy Sandbox turned off, or origin trial not active in the user's browser.
Verbose debug reports reference
Each verbose debug report has a type field that captures the reason why the corresponding attribution report was dropped. Use the reference to figure out, for each type of verbose report, what action to take.
If a verbose report's type starts with trigger-event, it can only be generated for source or trigger events that are associated with event-level reports. If a verbose report's type starts with trigger-aggregate, it can only be generated for source or trigger events that are associated with aggregatable reports. In all other cases, it's for either an event-level or an aggregatable report.
Source registration success
A source is successfully registered.
source-success- Details and report body
The source registration success verbose debug report is sent even if the unattributed reporting origin limit is reached. It's sent for security reasons, even though the source registration isn't actually successful in that case.
Privacy limitations reports
These reports are expected. They indicate privacy limitations to reduce cross-site user identity leakage.
source-destination-limit- Details and report body
source-noised- Details and report body
trigger-attributions-per-source-destination-limit- Details and report body
trigger-reporting-origin-limit- Details and report body
trigger-event-noise- Details and report body
trigger-event-excessive-reports- This is generated if the report count is over limit; you can register at most one conversion for views, and three for clicks. Note that you can configure what reports to receive by setting priorities. Details and report body
Storage limitations reports
These reports are expected. They indicate storage limitations to prevent excessive resource usage.
source-storage-limit- Details and report body
trigger-event-storage-limit- Details and report body
trigger-aggregate-storage-limit- Details and report body
Custom rules reports
These reports are expected if you're using filtering, deduplication, priorities, or window-based filtering. Just in case, double-check the corresponding custom rules to confirm that the report corresponding to that verbose report is indeed a report you want to drop. If this is correct, there is no action for you to take.
trigger-no-matching-filter-data- Details and report body
trigger-event-no-matching-configuration- Details and report body
trigger-event-deduplicated- Details and report body
trigger-aggregate-deduplicated- Details and report body
trigger-event-low-priority- Details and report body
trigger-event-report-window-passed- Details and report body
trigger-aggregate-report-window-passed- Details and report body
Other verbose reports
These reports may indicate potential implementation issues in your code.
trigger-no-matching-source- This may be an implementation issue. Check that there is no misconfiguration in your setup of
<reporting origin, destination>. This may also be expected API behavior. For example, the user has cleared data at some point after engaging with an ad and before converting, or the user converted without ever seeing an associated ad. Details and report body trigger-aggregate-no-contributions- This is likely not the behavior you intend your code to have. Troubleshoot your trigger registration code; make sure that your contribution configuration is correct. Details and report body
trigger-aggregate-insufficient-budget- This is likely not the behavior you intend your code to have. Double-check your trigger registration code to make sure that the sum of all contributions doesn't exceed the contribution budget. Details and report body
Unexpected errors (potential browser bugs)
These reports are unexpected. They could be due to a browser bug! File a bug and specify in your description the steps to reproduce it.
source-unknown-error- Details and report body
trigger-unknown-error- Details and report body
Loss analysis example
Loss analysis example
Step 1: Setup and mapping with cookies
Follow the instructions in Part 2: Set up debug reports to set up your system to generate success debug reports and verbose debug reports.
With this, you can use cookie-based conversion information to look up the corresponding debug reports or attribution reports.
Step 2: Identify successful registrations and missing reports
In this example, let's assume you've tracked 100 conversions with your cookie-based system.
Each time you record a cookie-based conversion, look for the success debug report (sent immediately) that has the same <source_debug_key, trigger_debug_key> pair as this cookie-based conversion.
Let's assume you've received a success debug report for 70 of these cookie conversions.
- Success reports mean that the attribution has been successfully recorded, so you can safely assume that you will be getting an attribution report that corresponds to each success report—with some exceptions.
- You can decide to monitor these exceptions. To do so, as attribution reports are sent onto your endpoint over the next days/weeks (depending on expiry), look for the attribution reports that have the same debug keys pair as each success debug report. Make sure to wait a bit: reports may not be sent immediately at the end of each window. Let's assume that you find only 60 attribution reports. The 10 missing attribution reports may be due to user behavior.
It's possible you have event-level attribution reports that do not map to a cookie-based conversion. These are most likely noisy reports that were randomly generated by the API. You can confirm this by looking for debug verbose reports of type source-noised that have the same source debug key as your event-level report.
Step 3: Brief loss assessment
100-70 = 30 success debug reports are missing. This means that these 30 conversions (that were tracked in your cookie-based implementation) weren't recorded with Attribution Reporting. You will not be receiving attribution reports for these.
Since you have 100 cookie-based conversions and only 70 attribution-based conversions, your loss is 30%. You now have a brief loss assessment.
Step 4: Analyze causes
To investigate why these reports are missing, look for corresponding verbose debug reports you've received at conversion (trigger registration) time or earlier at source registration time. Use the keys of the cookie-based conversions to map these to verbose debug reports.
- Let's assume that there are 10 keys for which there is no verbose debug report. Check if there's any integration issue. If not, this may be due to user behavior.
- You have 20 verbose debug reports. You can now refine your loss analysis. Analyze the
typefield of each verbose report. For example, you may find that:- 10 (= 10% in our example) reports are missing due to
pending destination limit - 5 (= 5%) reports are missing due to
trigger-aggregate-no-contributions. - 5 (= 5%) reports are missing due to
unknown-error.
- 10 (= 10% in our example) reports are missing due to
Step 5: Take action and troubleshoot
Now that you've gained visibility into why reports are missing, you can act on these insights.
Which action to take depends on each verbose report's type. Review the verbose reports reference for details. For example:
pending-destination-limitis a privacy protection. There's no action to take. Use this number as a data point, for your own visibility and monitoring.trigger-aggregate-no-contributionsmay be the sign of an implementation issue on your side. Analyze this further. Use details in the verbose report's body to troubleshoot and fix this if needed.unknown-errormay be the sign of a browser bug or network error. If you repeatedly encounter this, file a bug for browser developers.
Updated on • Improve article