docs: add trace observation point description

[mainred]

Please ensure your pull request adheres to the following guidelines:

• For first time contributors, read Submitting a pull request
• All code is covered by unit and/or runtime tests where feasible.
• All commits contain a well written commit description including a title,
  description and a Fixes: #XXX line if the commit addresses a particular
  GitHub issue.
• If your commit description contains a Fixes: <commit-id> tag, then
  please add the commit author[s] as reviewer[s] to this issue.
• All commits are signed off. See the section Developer’s Certificate of Origin
• Provide a title or release-note blurb suitable for the release notes.
• Thanks for contributing!

Fixes: #issue-number

docs: add trace observation point description

[gandro]

Thanks a lot, this is going to be very helpful. I've left two minor comments

[gandro]

Thanks!

[gandro]

/test

[pchaigno]

I found a couple typos below, but otherwise looks good to me. Thanks!

[pchaigno]

Please squash all commits into the first.

[mainred]

/test

[mainred]

Travis CI - Pull Request failed for some network failure

E: Failed to fetch http://ports.ubuntu.com/ubuntu-ports/pool/universe/n/ncurses/libncurses5_6.2-0ubuntu2_arm64.deb  Unable to connect to ports.ubuntu.com:http: [IP: 185.125.190.36 80]
E: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing?
apt-get.diagnostics
apt-get install failed
The command "sudo -E apt-get -yq --no-install-suggests --no-install-recommends $(travis_apt_get_options) install kernel-package gnupg libncurses5" failed and exited with 100 during .

[gandro]

Marking this ready-to-merge. This PR only updates protobuf schema comments, which are validated by performing a make build in Travis. Since Travis is green now, this is good to go.

[gandro]

I've removed the ready-to-merge label based on (what I think is good) out-of-band feedback by @joestringer. He noticed that the language is a bit inconsistent - there are three different sets of wording being used for different locations, eg "originated", "coming into", "passed from". However, there are only two broad actions: Transmit (TO_) and Receive (FROM_) - thus the suggestion to make the wording a bit more consistent and reduce the set of verbs.

That's me paraphrasing him - I'll let @joestringer chime in as well if he wants.

@mainred Do you think you could improve the language a bit to make sure we're using more consistent verbs (i.e. only use transmit or receive)?

In terms of the used nouns, the usage seems already pretty consistent to me. The only asymmetry I've found is regarding the tunnel device, from-overlay mentions coming into the node from the tunnel device., while to-overlay only says transmitted through the tunnel device. without mentioning that they are also leaving the node.

[mainred]

@gandro Thanks for being thoughtful. I totally agree with you, as this is also customer-facing, using consistent phrases can bring less confusion to understanding different obs points. Updated the code to use "are received by" and "are transmitted from"

[joestringer]

Thanks, this is a lot more consistent and IMHO easier to reason about.

There's one more subtle distinction that I'd like to make if we are going to define the semantics like this. See the comments below. This applies to all of the cases, TO_* -> transmit, FROM_* -> receive.

[joestringer]

LGTM thanks.