docs: First cut at gRPC Gotchas blog - #2150
Open
kflynn wants to merge 4 commits into
Open
Conversation
Signed-off-by: Flynn <flynn@buoyant.io>
Signed-off-by: Flynn <flynn@buoyant.io>
Signed-off-by: Flynn <flynn@buoyant.io>
kflynn
changed the title
schristoff
reviewed
Aug 12, 2026
schristoff
left a comment
schristoff
left a comment
There was a problem hiding this comment.
We should change the header image ofc
|
|
||
| Over the wire, gRPC is layered over HTTP/2, so every gRPC call is an HTTP/2 stream with `HEADERS` frames carrying metadata, `DATA` frames carrying the inputs and outputs, and trailers (`HEADERS` frames after all the `DATA` frames) carrying the final status of the gRPC call. | ||
|
|
||
|  |
There was a problem hiding this comment.
I'm going to speak for Catherine who is on PTO
Will you "Linkerd/Buoyant-ized" that diagram? (ugh, hate that I'm asking this)
|
|
||
| This need to know the details of the connection isn't only a gRPC thing, of course. In general, anything more subtle than just passing bytes back and forth with no analysis requires you to know what the protocol is. This includes not just golden metrics and reliability, but even basic features like per-request routing -- after all, you can't route a single request if you don't know where the request starts and ends in the data stream. | ||
|
|
||
| There are fundamentally only two ways to know what protocol is in play: you can to look at the bytes in transit and figure out what protocol it is (_protocol detection_), or you can be told up front what protocol it is (_protocol declaration_). Linkerd takes the attitude that [detection is friendlier than declaration], so it leans heavily on protocol detection. |
There was a problem hiding this comment.
diagram probably here would be cute
|
|
||
| So if you're using protocol declaration - which we're sure many of you are - first, **pay attention to the standards** when you set up your protocols! A wrong value can produce a very confusing error. | ||
|
|
||
| Second, though, is a debugging tip: Linkerd usually gets all of this stuff _right_, enough so that you should consider it something of a red flag to see opaque behavior -- if Linkerd seems to be ignoring Routes that it's marked as `Accepted`, don't burn a lot of time before looking to incorrect protocol declarations. |
There was a problem hiding this comment.
Strongly consider rewording
"Linkerd prides itself in following standards as closely as possible, so you should consider it a red flag to see opaque behavior. If Linkerd sseems to be ignoring routes marked as accepted, first look at incorrect protocol declarations"
|
|
||
| Second, though, is a debugging tip: Linkerd usually gets all of this stuff _right_, enough so that you should consider it something of a red flag to see opaque behavior -- if Linkerd seems to be ignoring Routes that it's marked as `Accepted`, don't burn a lot of time before looking to incorrect protocol declarations. | ||
|
|
||
| And go easy on the test authors, right? They're doing good work. |
There was a problem hiding this comment.
s/ "Also, a huge thank you to test authors. You're doing great work. This is no means a call out. Maybe consider helping them by contributing (link)"
Signed-off-by: Flynn <flynn@buoyant.io>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Signed-off-by: Flynn flynn@buoyant.io