Debugging cookbook

Part 3 of 3 on debugging Attribution Reporting. Find instructions for how to use debug reports.

Published on

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

  • 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.example as 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 type field 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

  1. Set up your system to generate success debug reports. See how in Part 2: Set up Debug reports.
  2. 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.
Caution

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

Steps for a loss analysis

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 conversion 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 receive a verbose debug report: look at the type field of each verbose report. It indicates the reason why a source or trigger has not been registered, and hence why the corresponding attribution report will be missing. Depending on the type of 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.
  • 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.
Gotchas

Success debug reports are sent when the browser successfully generates the event-level report or aggregatable report. Verbose debug reports are sent in case of a source or trigger not registered. Therefore, you'll never receive both a success debug report and a verbose debug report for a given event.

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 (and no verbose 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

If for a given cookie conversion, you received a verbose debug report (hence no success debug report, and later no attribution report), this 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.

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

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 type field 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.

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-limit is 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-contributions may 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-error may 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

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.