Add comments pointing to the source of logging dimension names #4613
Conversation
…to OTel semantic conventions
| // There is no OTel semantic convention for HTTP logs, therefore we are using | ||
| // semantic conventions for HTTP spans: | ||
| // https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md. | ||
| // Some dimensions (e.g. Host and Method) were not renamed, though they had corresponding | ||
| // names in the semantic conventions. The reason is that they are coming from ASP.NET Core 8 | ||
| // HttpLogging component, therefore we cannot rename them. |
There was a problem hiding this comment.
Is this something we'd want end-users to see in the docs (e.g., at learn.microsoft), or is this for the maintainers only?
Ditto for the other comments.
There was a problem hiding this comment.
I didn't mean to include this comment as public documentation, and my initial intent was to include it as a reference and justification "WHY" only for maintainers. It is part of public API though, and such a comment/remark could be useful for users.
There was a problem hiding this comment.
Regarding web doc, e.g. learn.microsoft, I think that we'll include into the doc a list of log dimensions and remark that some of those dimensions are following OTel semantic-conventions. As I understand, web doc will be developed separately, right?
RussKie
added
waiting-author-feedback 📭
|
The PR mingles /// and // comments together, which isn't great. I think most of these added comments can go into /// as |
ghost
removed
the
waiting-author-feedback 📭
My initial intent was to include this kind of information only for maintainers, hence not as part of public API doc. We are currently following OTel conventions for spans, because there are no conventions for logs. It could be confusing to include links to span conventions into API documentation of Http and HttpClient logging. We'll include information that the names of logging tags were inspired by OTel semantic conventions for spans into web documentation, e.g. learn.microsoft, and add there a justification why we are using span conventions. I'm going to abandon the PR. What do you think? |
|
Yeah, I think abandoning is reasonable. |
The PR adds links to OTel semantic conventions that are used for naming of logging dimensions.
Microsoft Reviewers: Open in CodeFlow