[docs] Add info to docs about tile coordinates

[kkowalsky]

** Copied from tilezen/joerd#109 because relevance **

A support ticket came in where the user was trying to get a tile by passing decimal degrees, instead of tile coordinates.

We should clarify that the the {x}/{y} is a tile coordinate. Currently, it looks pretty much the same as the standard decimal degrees format. Need to tell people that tile coordinates are used and provide instructions for teaching people how to convert

@kkowalsky knows of some resources that we can add to docs.

[kkowalsky]

add a statement about best performance using "all" instead of specific layers and filtering data on the client side

[nvkelso]

@zerebubuth Is Katie's suggestion in #1111 (comment) about suggestion all valid anymore with Xonacatl in production?

[zerebubuth]

The advice is still good, but the situation is more complicated now. Xonacatl adds an extra "hop" in the request, so for people on low-latency, high-bandwidth connections they might see a reduction in performance using custom layers. If they are on a high-latency, low-bandwidth connection (e.g: mobile) then custom layers are probably better.

To explain what's going on, here's the path of a request through the system:

1. Client asks Fastly for the tile.
   1. If Fastly already has it, return it to client and stop here.
   2. If it's an all request, skip to 4.
2. Fastly asks Xonacatl for the custom layers tile.
3. Xonacatl asks Fastly for the corresponding all tile.
4. Fastly asks S3 for the all tile. If it exists, return it to the client and stop here.
5. Fastly asks tileserver (in US-east) for the tile.

Steps 2 and 3 can be skipped for all tiles, at the cost that the response might be considerably larger, depending on which layers were selected. The largest delay in returning a tile to the client is whether it has to perform step 5 or not - but the client has little control over that.

The best thing that they can do to avoid hitting step 5 is handle "over-zooming", which means not requesting tiles at zoom > 16. Instead, they should request the z16 tile which contains the tile they originally wanted and "cut out" the part that they need. This is handled automatically by Tangram. We do handle requests for z > 16, but they will always hit step 5, and be comparatively slow. (This is possibly another service we could run alongside Xonacatl and the Metatile server - but there are no plans to do it at the moment).

In my opinion, to anyone interested in performance we should recommend that they benchmark it for their selection of layers and on their target devices. If either all or custom layers is clearly faster than the other, then choose that one. If they are about the same, then choose all, as the fewer steps in the request processing mean there's less to go wrong!

And a final caveat that this is all dependent on our infrastructure, so won't apply to anyone else's instance of vector-datasource, and our infrastructure might also change in the future.

[bcamper]

Related note: as came up in the post-mortem discussion yesterday, I think a
valid way to "shape" user behavior is to segment resources to provide
better performance for use cases we prefer, "starving" those patterns we
don't. I realize we may not be in the best position to do this today
(particularly, siloing traffic to a certain set of resources so it won't
affect other requests), but we can think about this type of approach for:

• Supporting old tiles when releasing new ones (1.x -> 2.0)
• All vs. custom layers
• z16+ tiles
• Different tile sizes (future "512px" tiles vs. classic 256px)

As long as we clearly explain to users what our preferred path is, and that
they may experience slower performance on other paths, I think this is a
viable way to steer users down an upgrade path without making it a hard
break.

On Tue, Nov 1, 2016 at 6:38 AM, Matt Amos notifications@github.com wrote:

The advice is still good, but the situation is more complicated now.
Xonacatl adds an extra "hop" in the request, so for people on low-latency,
high-bandwidth connections they might see a reduction in performance using
custom layers. If they are on a high-latency, low-bandwidth connection
(e.g: mobile) then custom layers are probably better.

To explain what's going on, here's the path of a request through the
system:

1. Client asks Fastly for the tile.
   1. If Fastly already has it, return it to client and stop here.
   2. If it's an all request, skip to 4.
2. Fastly asks Xonacatl for the custom layers tile.
3. Xonacatl asks Fastly for the corresponding all tile.
4. Fastly asks S3 for the all tile. If it exists, return it to the
   client and stop here.
5. Fastly asks tileserver (in US-east) for the tile.

Steps 2 and 3 can be skipped for all tiles, at the cost that the response
might be considerably larger, depending on which layers were selected. The
largest delay in returning a tile to the client is whether it has to
perform step 5 or not - but the client has little control over that.

The best thing that they can do to avoid hitting step 5 is handle
"over-zooming", which means not requesting tiles at zoom > 16. Instead,
they should request the z16 tile which contains the tile they originally
wanted and "cut out" the part that they need. This is handled automatically
by Tangram. We do handle requests for z > 16, but they will always hit step
5, and be comparatively slow. (This is possibly another service we could
run alongside Xonacatl and the Metatile server - but there are no plans to
do it at the moment).

In my opinion, to anyone interested in performance we should recommend
that they benchmark it for their selection of layers and on their target
devices. If either all or custom layers is clearly faster than the other,
then choose that one. If they are about the same, then choose all, as the
fewer steps in the request processing mean there's less to go wrong!

And a final caveat that this is all dependent on our infrastructure, so
won't apply to anyone else's instance of vector-datasource, and our
infrastructure might also change in the future.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#1111 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AABBXdpZPYLaEmjTRBFPXz0s_7kT464zks5q5xaqgaJpZM4KiylG
.

[nvkelso]

Would be nice to see lat/lng/zoom coords for center of map ala what Aaron does in Spelunker.

[kkowalsky]

@nvkelso adding that as an issue in: https://github.com/kkowalsky/find-tile-coordinates

[nvkelso]

Thanks! Please move that repo to Tilezen org when it's ready-ish.

On Nov 16, 2016, at 07:32, Katie Kowalsky notifications@github.com wrote:

@nvkelso adding that as an issue in: https://github.com/kkowalsky/find-tile-coordinates

―
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.