describe distributed tracing operations #335
Conversation
Signed-off-by: Jamie Klassen <jklassen@vmware.com>
fixes #334 Signed-off-by: Jamie Klassen <jklassen@vmware.com>
lit/docs/operation/tracing.lit
Outdated
| which deals with | ||
| \reference{schema.step.get-step.passed}{\code{passed}} constraints. | ||
| \list{ | ||
| \code{groupResolver.tryResolve} \list{ |
There was a problem hiding this comment.
Not sure if there's anything you can do about this (it might just be a Booklit quirk) but the font-size on this nested list seems just slightly off (1em vs the usual 0.9em that code in a p tag gets), making it look slightly wonky (but really not terrible):
...whereas if we can somehow move this list into the p that holds the text above:
...it looks a little better
There was a problem hiding this comment.
...this looks easier said than done. @vito pls? maybe it makes sense to drop the descriptions of all those private functions under groupResolver.
There was a problem hiding this comment.
Hmm this brings up an interesting point around sustainability with documenting traces. It feels like if we go too far they're likely to become out of date. Should we have a convention where public spans are documented but private ones aren't? Following Go convention, this would mean uppercase vs lowercase span names. That way as an engineer I can more freely refactor the internal bits, while knowing that any changes to "public" spans will require a documentation update.
re: the formatting - the syntax here feels kind of odd because it starts as a paragraph but then leads to a \list, which is a block element that can't exist in a paragraph (i.e. you can't have a <ul> in a <p>).
I think if you break the \list onto its own line it might do what you want it to - Booklit should parse the \code line as its own paragraph, which I think will make the font size consistent, since I think our CSS specifies p code { font-size: 0.9em } or something.
There was a problem hiding this comment.
Ah good point - I didn't piece together that the lowercase spans were intended to be "private". I assume there's no distinction between "Public" and "private" operations from Jaeger's perspective, right?
There was a problem hiding this comment.
I might go a step further and suggest that private functions should not be traced, i.e. "if it's worth tracing, it's worth making part of the public interface", but maybe that's a bit brutal. I don't think you'd say the same thing for logging, for example.
There was a problem hiding this comment.
Out of curiosity, is there any parallel notion to "log level" for traces? I guess something similar could be achieved with "tags"
There was a problem hiding this comment.
the concept I've heard of is "sampling priority" - I've heard it mentioned in opentracing best practices and seen in client libraries, but it's not actually part of the opentelemetry spec, it's just a common convention. jaegertracing/jaeger#365 has some related discussion.
There was a problem hiding this comment.
@jamieklassen Hmm yeah I think that's going too far. I think traces are really valuable for helping diagnose problems during development, and in this case the private traces were instrumental (heh) in finding the root cause of an issue in Hush House.
To me, tracing is something that should have a very low barrier to entry, even if means we under-document them. (I have differing thoughts on logging, though. IMO we should be more careful about what we log and try to make them more human-friendly, while preferring tracing/metrics for actual troubleshooting.)
There was a problem hiding this comment.
ok i'll drop the private stuff, with the exception of scanner.check which I believe is quite important
Signed-off-by: Jamie Klassen <jklassen@vmware.com>
Signed-off-by: Jamie Klassen <jklassen@vmware.com>
These should be free to change without the docs drifting. Plus I don't even really know how they work :) Signed-off-by: Jamie Klassen <jklassen@vmware.com>
fixes #334
I didn't delve into a ton of detail on each of the private functions under a resolver -- I can imagine those things being subject to change and not very helpful to non-experts.