How/why AMPs might break when viewed on a cache #7430

ithinkihaveacat · 2017-02-08T15:57:46Z

Short document listing some common reasons why an AMP might behave differently when viewed on a cache versus the origin.

Probably not the right place for it, but couldn't think of a better one.

/cc @ericlindley-g

dknecht · 2017-02-08T16:11:55Z

This is good.

Adding:
ampproject/ampbench#11
ampproject/ampbench#12

I wonder if we can also add a check for proper CORS settings?

ericlindley-g · 2017-02-08T16:23:19Z

spec/amp-cache-debugging.md

@@ -0,0 +1,24 @@
+# AMP Cache Debugging
+
+**Why is my doc broken on the AMP cache?**


maybe phrase "on the AMP cache" as "when served from an AMP cache" instead.

Would be good to phrase throughout as general AMP caches, rather than "the" AMP cache, so the guidelines aren't Google-specific

ericlindley-g · 2017-02-08T16:27:37Z

spec/amp-cache-debugging.md

+|Web fonts do not appear (fallback fonts are used)|Fonts served with incorrect MIME type|Specify an [acceptable MIME type](https://github.com/ampproject/amphtml/blob/master/spec/amp-cache-guidelines.md#mime-types-for-fonts) for fonts|
+|Web fonts do not appear (fallback fonts are used)|Cache not whitelisted by font provider|Contact font provider and ask them to whitelist [all caches](https://github.com/ampproject/amphtml/blob/master/spec/amp-cors-requests.md#cors-security-in-amp)|
+|Assets (e.g. fonts and images) do not appear (**HTTP origins only**)|Document uses protocol-relative URLs|Switch to absolute URLs (that is, `http://www.site.com/doc/amp`, not `//www.site.com/doc/amp`)|
+|Assets (e.g. fonts and images) do not appear|Cache is unable to access assets|Ensure the Google crawler is able to access your assets and is not blocked by `robots.txt`, IP address, or user agent, etc. ([List of user agents used by Google's crawler](https://support.google.com/webmasters/answer/1061943?hl=en).)|


Same comment regarding making this not Google-specific. The language is straightforward to change: "Ensure that AMP crawlers are able...". Then, for the list of user agents used by these crawlers, there could be a grid of AMP caches and their corresponding user agents?

Thanks, switched to cache-neutral language in 24f85cc.

ithinkihaveacat · 2017-02-08T16:34:37Z

spec/amp-cache-debugging.md

+that can be problematic.
+
+If a particular document appears and behaves as expected on your origin, but not
+when viewed via the cache (how to map origin URLs to [Google's AMP Cache](https://developers.google.com/amp/cache/overview#amp-cache-url-format)),


@dknecht Is there an equivalent Cloudflare document?

Not at the moment. We have in our backlog.

We are actually following the same format. I am not sure if there is comparable doc on am-project.org.

@irtefa fyi

ithinkihaveacat · 2017-02-08T16:36:03Z

spec/amp-cache-debugging.md

+|Web fonts do not appear (fallback fonts are used)|Fonts served with incorrect MIME type|Specify an [acceptable MIME type](https://github.com/ampproject/amphtml/blob/master/spec/amp-cache-guidelines.md#mime-types-for-fonts) for fonts|
+|Web fonts do not appear (fallback fonts are used)|Cache not whitelisted by font provider|Contact font provider and ask them to whitelist [all caches](https://github.com/ampproject/amphtml/blob/master/spec/amp-cors-requests.md#cors-security-in-amp)|
+|Assets (e.g. fonts and images) do not appear (**HTTP origins only**)|Document uses protocol-relative URLs|Switch to absolute URLs (that is, `http://www.site.com/doc/amp`, not `//www.site.com/doc/amp`)|
+|Assets (e.g. fonts and images) do not appear|Cache is unable to access assets|Ensure the cache is able to access your assets and is not blocked by `robots.txt`, IP address, or user agent, etc. (List of user agents used by [Google's crawler](https://support.google.com/webmasters/answer/1061943?hl=en).)|


@dknecht Anything that should be added for Cloudflare here?

cramforce · 2017-02-08T16:38:17Z

spec/amp-cache-debugging.md

+|Web fonts do not appear (fallback fonts are used)|Fonts served with incorrect MIME type|Specify an [acceptable MIME type](https://github.com/ampproject/amphtml/blob/master/spec/amp-cache-guidelines.md#mime-types-for-fonts) for fonts|
+|Web fonts do not appear (fallback fonts are used)|Cache not whitelisted by font provider|Contact font provider and ask them to whitelist [all caches](https://github.com/ampproject/amphtml/blob/master/spec/amp-cors-requests.md#cors-security-in-amp)|
+|Assets (e.g. fonts and images) do not appear (**HTTP origins only**)|Document uses protocol-relative URLs|Switch to absolute URLs (that is, `http://www.site.com/doc/amp`, not `//www.site.com/doc/amp`)|
+|Assets (e.g. fonts and images) do not appear|Cache is unable to access assets|Ensure the cache is able to access your assets and is not blocked by `robots.txt`, IP address, or user agent, etc. (List of user agents used by [Google's crawler](https://support.google.com/webmasters/answer/1061943?hl=en).)|


Caches should not (and do not) respect robots.txt for user invoked requests, so this should not be an issue.

The IP based blocking can, indeed, be an issue.

Remove reference to robots.txt in d8df74e.

cramforce · 2017-02-08T16:39:08Z

spec/amp-cache-debugging.md

+
+|Symptom|Issue|Solution|
+|---|---|---|
+|Web fonts do not appear (fallback fonts are used)|Fonts served with incorrect MIME type|Specify an [acceptable MIME type](https://github.com/ampproject/amphtml/blob/master/spec/amp-cache-guidelines.md#mime-types-for-fonts) for fonts|


The same can also happen with images. Either a non image/ mime type or the wrong mime type.

Adjusted doc to mention images in c1c054f.

dknecht · 2017-02-08T16:44:39Z

A few other suggestion:

It might be good to mention what to do if image are distorted.
Mention the update-ping mechanism

ghost · 2017-02-08T18:29:23Z

spec/amp-cache-debugging.md

+
+If a particular document appears and behaves as expected on your origin, but not
+when viewed via the cache (how to map origin URLs to [Google's AMP Cache](https://developers.google.com/amp/cache/overview#amp-cache-url-format)),
+first open the developer console in your browser, and ensure no errors or


Is the "developer console" the Chrome one? If so, please be specific - "Chrome DevTools console"

Thanks, I was trying to be browser neutral but ended up being confusing--I've adjusted the language a bit in 5765a50. Should I also specifically call out Chrome?

ghost · 2017-02-08T18:37:05Z

spec/amp-cache-debugging.md

+
+If a particular document appears and behaves as expected on your origin, but not
+when viewed via the cache (how to map origin URLs to [Google's AMP Cache](https://developers.google.com/amp/cache/overview#amp-cache-url-format)),
+first open the developer console in your browser, and ensure no errors or


I think this would read better if the "steps" were listed as bullets, so that it's easy to parse the info, like so:

If a particular document appears and behaves as expected on your origin, but not when viewed via the cache (how to map origin URLs to Google's AMP Cache), try the following:

Validate that there are no errors or warnings for the AMP page by reviewing the Chrome DevTools console.

Validate the structured data and AMP urls for the page by using the AMPBench tool.

If you still have a problem, review the table below:

Switched to point form in 5765a50.

ithinkihaveacat · 2017-02-14T17:04:20Z

@dknecht What's the distorted image problem you're referring to in #7430 (comment)?

dknecht · 2017-02-24T17:47:55Z

@ithinkihaveacat Every once in awhile the google cache and cloudflare cache preform an image optimization that make image break.

I would suggest we merge this and. then improve from here. This doc is a great start.

ericlindley-g · 2017-06-08T18:49:33Z

Thanks @ithinkihaveacat ! — LGTM as long as other reviewers agree

cramforce · 2017-06-08T19:59:23Z

Can we make this appear on our docs site?

ghost · 2017-06-08T20:06:17Z

@cramforce - Yes, I can, in the debugging section. It'll have to be merged first, then I'll do some inclusion.

Also, to be clear, are these instructions relevant to all caches, not just Google?

ghost · 2017-06-08T20:06:55Z

spec/amp-cache-debugging.md

@@ -0,0 +1,28 @@
+# AMP Cache Debugging
+
+**Why is my doc broken on an AMP cache?**


Please make this a heading level 2 (##)

Fixed in 5a13ec8.

ericlindley-g · 2017-06-23T21:19:46Z

Ping @cramforce — LGTY?

SchnWalter · 2017-06-26T07:46:17Z

spec/amp-cache-debugging.md

+|Symptom|Issue|Solution|
+|---|---|---|
+|Web fonts do not appear (fallback fonts are used)|Cache not whitelisted by font provider|Contact font provider and ask them to whitelist [all caches](https://github.com/ampproject/amphtml/blob/master/spec/amp-cors-requests.md#cors-security-in-amp)|
+|Assets (e.g. fonts and images) do not appear #1 (**HTTP origins only**)|Document uses protocol-relative URLs|Switch to absolute URLs (that is, `http://www.site.com/doc/amp`, not `//www.site.com/doc/amp`)|


I believe that the example should have an HTTPS protocol. And maybe use the domain https://www.example.com/

@SchnWalter This item was specifically about HTTP origins, so http is correct. Probably example.com would be better but would really like to get this merged and so want to avoid making minor changes! (There's also another change I want to make to this doc soon (to mention https://cdn.ampproject.org/caches.json)--I can make the example.com change at the same time.)

Oh, yes, http, my bad.

Thanks for the great documentation!

ericlindley-g · 2017-06-26T15:31:47Z

Thanks all!

@cramforce , @ithinkihaveacat , or @bpaduch — does one of you with merge access want to do the honors?

HOWTO fix/debug problems with an AMP Cache

1fd42e7

ericlindley-g reviewed Feb 8, 2017

View reviewed changes

More cache-neutral language

24f85cc

ithinkihaveacat commented Feb 8, 2017

View reviewed changes

cramforce requested changes Feb 8, 2017

View reviewed changes

robots.txt is not a problem

d8df74e

MIME type issue can break images, not just fonts

c1c054f

ghost suggested changes Feb 8, 2017

View reviewed changes

Improve clarity

5765a50

ghost approved these changes Feb 14, 2017

View reviewed changes

ithinkihaveacat added 2 commits June 8, 2017 18:37

Add row for takedown notice

83bf301

Minor updates to link text

8c5329a

googlebot added the cla: yes label Jun 8, 2017

ericlindley-g approved these changes Jun 8, 2017

View reviewed changes

ghost reviewed Jun 8, 2017

View reviewed changes

Create real heading

5a13ec8

cramforce approved these changes Jun 26, 2017

View reviewed changes

SchnWalter reviewed Jun 26, 2017

View reviewed changes

cramforce merged commit c87d1f9 into ampproject:master Jun 27, 2017

This was referenced Jun 28, 2017

Improve formatting and wording for amp cache debugging doc #10182

Merged

Import AMP Cache Debugging guide ampproject/amp.dev#588

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

How/why AMPs might break when viewed on a cache #7430

How/why AMPs might break when viewed on a cache #7430

ithinkihaveacat commented Feb 8, 2017

dknecht commented Feb 8, 2017 •

edited

ericlindley-g Feb 8, 2017

ericlindley-g Feb 8, 2017

ithinkihaveacat Feb 8, 2017

ithinkihaveacat Feb 8, 2017

dknecht Feb 8, 2017

dknecht Feb 8, 2017

ithinkihaveacat Feb 8, 2017

cramforce Feb 8, 2017

ithinkihaveacat Feb 8, 2017

cramforce Feb 8, 2017

ithinkihaveacat Feb 8, 2017

dknecht commented Feb 8, 2017

ghost Feb 8, 2017

ithinkihaveacat Feb 14, 2017

ghost Feb 8, 2017

ithinkihaveacat Feb 14, 2017

ithinkihaveacat commented Feb 14, 2017

dknecht commented Feb 24, 2017

ericlindley-g commented Jun 8, 2017

cramforce commented Jun 8, 2017

ghost commented Jun 8, 2017 •

edited by ghost

ghost Jun 8, 2017

ithinkihaveacat Jun 9, 2017

ericlindley-g commented Jun 23, 2017

SchnWalter Jun 26, 2017

ithinkihaveacat Jun 26, 2017

SchnWalter Jun 26, 2017

ericlindley-g commented Jun 26, 2017

		@@ -0,0 +1,24 @@
		# AMP Cache Debugging

		Why is my doc broken on the AMP cache?

		@@ -0,0 +1,28 @@
		# AMP Cache Debugging

		Why is my doc broken on an AMP cache?

How/why AMPs might break when viewed on a cache #7430

How/why AMPs might break when viewed on a cache #7430

Conversation

ithinkihaveacat commented Feb 8, 2017

dknecht commented Feb 8, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dknecht commented Feb 8, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ithinkihaveacat commented Feb 14, 2017

dknecht commented Feb 24, 2017

ericlindley-g commented Jun 8, 2017

cramforce commented Jun 8, 2017

ghost commented Jun 8, 2017 • edited by ghost

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericlindley-g commented Jun 23, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericlindley-g commented Jun 26, 2017

dknecht commented Feb 8, 2017 •

edited

ghost commented Jun 8, 2017 •

edited by ghost