Blogpost about how to use wireshark with protobuf and grpc dissectors

[huangqiangxiong]

Add this blogpost as recommended on protocolbuffers/protobuf#3303.

There may be some grammatical errors. You are welcome to modify them directly if you like.

Preview: https://deploy-preview-467--grpc-io.netlify.app/blog/how-to-analyze-grpc-with-wireshark/

[linux-foundation-easycla]

The committers are authorized under a signed CLA.

• ✅ huangqiangxiong (61a309c)

[huangqiangxiong]

@jtattermusch hello, what else do I need to do about this PR? Or need I submit an issue for it?

[chalin]

Hi @huangqiangxiong - no, nothing more to be done. I've assigned @jtattermusch and @ejona86 as technical reviewers; if you think that someone else from the gRPC team might be a good/more suitable reviewer, let me know. I'll review (from a tech writers p.o.v), most likely early next week. /cc @thisisnotapril

[huangqiangxiong]

Hi @huangqiangxiong - no, nothing more to be done. I've assigned @jtattermusch and @ejona86 as technical reviewers; if you think that someone else from the gRPC team might be a good/more suitable reviewer, let me know. I'll review (from a tech writers p.o.v), most likely early next week. /cc @thisisnotapril

OK. Thank you for your efforts.

[jtattermusch]

Thanks for the blogpost, that's a very useful reading and I like that there's a plenty of examples.

@chalin can you please review from the techwriter perspective?

[chalin]

@jtattermusch - thanks for your review! I'll do mine shortly.

[chalin]

@ejona86 has somment comments about the content, so I'll wait for those before I make my pass.

[chalin]

@huangqiangxiong - I have some general questions for you about this blog entry:

• What is your target audience?
• In two sentences or less, can you summarize the blog entry (so that, in reading your one or two sentences, someone would feel interested in reading the entire post :).
• After reading this blog entry, what should the reader have learned?
  That is, what are the expected learning outcomes?

(Once you've answered those questions, you might want to rethink the title.)

At the moment, the blog entry is feeling a little too heavy on the details.

You might consider dropping the following
(@ejona86 feel free to chime in):

• Details about the JSON-serialized capture. (I think that it is enough to mention support for JSON in the feature list)
• Details about UDP
• "Write your own Protobuf UDP or TCP dissectors" how often does a user have to write a custom dissector? If it isn't often, then consider removing the details from the text and simply referring the reader to Wireshark documentation.

I have other comments about the text, but I'll wait for some feedback from @ejona86.

I would like to point out one broad change that I feel will be necessary: "protobuf" isn't an English word and, as far as I know, it isn't an accepted abbreviation for "protocol buffers" or ".proto file". You should use the latter, as appropriate, instead.

[huangqiangxiong]

@chalin, thank you for your comments. Please see my reply.

• What is your target audience?

I think the audience of this blog is mainly the following two kinds of people:

1. The people who want to debug or analyze their own gRPC or protobuf (Protocol Buffers) based messages transferred over the wire (network) by Wireshark.
2. The people who want to study the binary wire format of gRPC protocol or protocols based on protobuf. (Just as I wanted when I started learning protobuf and gRPC)

The original motivation of writing this article comes from the people's requirements from following links:
protocolbuffers/protobuf#3303
grpc/grpc#13586

• In two sentences or less, can you summarize the blog entry (so that, in reading your one or two sentences, someone would feel interested in reading the entire post :).

With Wireshark, people can analyze the messages of gRPC protocol or protocols based on Protocol Buffers (a.k.a protobuf) that transferred over the wire (network), or learning the binary wire format of these protocols.

• After reading this blog entry, what should the reader have learned?
  That is, what are the expected learning outcomes?

This tutorial will show you how to configure and use Wireshark offical protobuf and gRPC dissectors to analyze grpc and protobuf based protocols with .proto files.

(Once you've answered those questions, you might want to rethink the title.)

How about the title "How to dissect grpc and Protobuf based protocols with Wireshark"?

At the moment, the blog entry is feeling a little too heavy on the details.

You might consider dropping the following
(@ejona86 feel free to chime in):

• Details about the JSON-serialized capture. (I think that it is enough to mention support for JSON in the feature list)

OK, I will remove it.

• Details about UDP
• "Write your own Protobuf UDP or TCP dissectors" how often does a user have to write a custom dissector? If it isn't often, then consider removing the details from the text and simply referring the reader to Wireshark documentation.

Indeed, the two features of UDP and "Write your own Protobuf UDP or TCP dissectors" are only related to protobuf and have nothing to do with grpc. But they are important to Protobuf only users. If you don't think it's appropriate to put this content here, I will just simply leave a link referring to Wireshark documentation.

I have other comments about the text, but I'll wait for some feedback from @ejona86.

I would like to point out one broad change that I feel will be necessary: "protobuf" isn't an English word and, as far as I know, it isn't an accepted abbreviation for "protocol buffers" or ".proto file". You should use the latter, as appropriate, instead.

But it seems that the word "protobuf" is also being used by the protocol buffers official code repository at https://github.com/protocolbuffers/protobuf. Or how about to use "Protocol Buffers" in the title or at the beginning of the article, like this: "Protocol Buffers (a.k.a., Protobuf)", and then still using "Protobuf" later?

[chalin]

@huangqiangxiong, thanks for your thoughtful reply and, in particular, for the link to the issues that provide the background / motivation for your blog post. I feel that we're making progress in clarifying intent and scope.

How about if we approached this incrementally? Could you make a pass to strip out the large chunks that we seem to be agreeing to remove: JSON-serialized capture, UDP and "Write your own..." (while leaving "a link referring to Wireshark documentation", as you suggested)?

As a first blog post on the use of Wireshark to analyze gRPC traffic I can think of two main alternative scopes:

(1) Only introduce Wireshark and its capabilities, linking to articles elsewhere for practical "How to use Wireshark with gRPC" instructions.

(2) If no such "how to" articles exist elsewhere, then this blog post could be a first one. What I find missing from your current writeup is details for setting up and capturing gRPC network traffic, but I have no idea how easy it would be to cover that concisely -- and maybe that could be the topic of another post.

I'm not saying that you need to change the scope of your blog post (e.g., by adding details about how to capture traffic). But I would like the scope to be clear so that readers know what they're going to learn, and where to go to to learn more.

[ejona86]

"Protobuf" is fine to use, as we do use it constantly in speak and writing. It's actually pretty easy to forget that they have a fuller name. But we should probably ease into it and refer to "Protocol Buffers" initially in the title and first sentence.

The content itself looks pretty good, but it seems there will need to be a reasonable amount of editorial changes to improve flow.

[huangqiangxiong]

@chalin @ejona86, I have updated and committed a new version according to your comments. Please help to review, thanks.

[chalin]

Thanks for the updates! I'll get back to you as soon as I can.

[chalin]

@huangqiangxiong - could you rebase and (force) push? I'd be ready soon to make a pass over this PR.

[chalin]

Thanks for the updates.

@huangqiangxiong - could you rebase and (force) push? I'd be ready soon to make a pass over this PR.

Have you been able to rebase and push?

[chalin]

Oups, I committed some copyedits directly to this PR via 9a456a8 (see above). That wasn't my intention; what I wanted to do was submit a PR over your PR so that you could then review, approve and then merge my changes back into this PR. This was meant to be a practice run. I'll try to do differently next time.

I'm mentioning all of this just because you'll need to pull my changes in before you rebase.

[huangqiangxiong]

Oups, I committed some copyedits directly to this PR via 9a456a8 (see above). That wasn't my intention; what I wanted to do was submit a PR over your PR so that you could then review, approve and then merge my changes back into this PR. This was meant to be a practice run. I'll try to do differently next time.

I'm mentioning all of this just because you'll need to pull my changes in before you rebase.

@chalin I tried to find the 'rebase' button on the web UI, but I couldn't find it. Instead, I have run the following commands (as I usually do on gitlab):

• git clone https://github.com/huangqiangxiong/grpc.io.git
• git remote add upstream https://github.com/grpc/grpc.io.git
• git checkout wireshark-protobuf-and-grpc-dissectors
• git pull --rebase upstream main
• git push origin +HEAD

Is this the correct way to rebase and force push? But it shows some checks were not successful now.

[chalin]

@huangqiangxiong - your force push seems to have worked, thanks! I cleared the preview-server caches, and now the previews are being successfully built. I'll continue my review and submit some edits as soon as I can.

[chalin]

I wanted to do was submit a PR over your PR

@huangqiangxiong - I haven't been able to find a way to do this for your PR (although I've seen it work before), so this is what I've done/decided to do:

• I've marked the post as a draft, that way it won't show up on the production (or even the preview) server yet.
• I'll accept and merge this PR.
• Finally, I'll submit changes to your blog post as separate PR(s) for your approval.

Once we're both satisfied with the post, we can drop the draft status and it will appear on the production server.

I'm hoping that everyone is ok with all this!

[chalin]

Thanks for you patience @huangqiangxiong. In the end we'll have a nicely polished blog post!

[huangqiangxiong]

I wanted to do was submit a PR over your PR

@huangqiangxiong - I haven't been able to find a way to do this for your PR (although I've seen it work before), so this is what I've done/decided to do:

• I've marked the post as a draft, that way it won't show up on the production (or even the preview) server yet.
• I'll accept and merge this PR.
• Finally, I'll submit changes to your blog post as separate PR(s) for your approval.

Once we're both satisfied with the post, we can drop the draft status and it will appear on the production server.

I'm hoping that everyone is ok with all this!

OK. Thanks!