Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reliable documentation on generated telemetry #2839

Open
medikoo opened this issue Mar 16, 2022 · 24 comments · May be fixed by #5042
Open

Reliable documentation on generated telemetry #2839

medikoo opened this issue Mar 16, 2022 · 24 comments · May be fixed by #5042
Assignees
Labels

Comments

@medikoo
Copy link

medikoo commented Mar 16, 2022

e.g. I'm looking at @opentelemetry/instrumentation-http I see instructions on how it can be setup, but I don't see any documentation on the produced outcome.

What are the telemetry properties generated? Where can I find reliable documentation on that? Ideally if there's a helpful note on that in main package readme

@dyladan
Copy link
Member

dyladan commented Mar 17, 2022

It would probably be a good idea for each instrumentation to provide a summary of the "shape" of the produced telemetry. For now you can look at the semantic conventions in the specifications here for example. Instrumentations are supposed to follow the guidelines there and we do our best to follow that but if our instrumentation is out of date or provides any non-standard attributes they obviously won't show up there.

@dyladan dyladan added good first issue Good for newcomers up-for-grabs Good for taking. Extra help will be provided by maintainers document Documentation-related never-stale labels Mar 17, 2022
@sgracias1
Copy link
Contributor

hello, I would like to add this documentation in. Seems like the best way to go would be to add a new section to the README and I am thinking of pulling these values based on whats in the src code unless there is a different reference point?

@siddhikhapare
Copy link

@medikoo @dyladan I want to work on this issue. Can you assign me? Do you want small application outcome of observability after setup created using js? I need your help to understand this issue.

@legendecas legendecas removed the up-for-grabs Good for taking. Extra help will be provided by maintainers label Jun 22, 2022
@legendecas
Copy link
Member

I think documenting them in the package README with a new section should be fine.

@dyladan
Copy link
Member

dyladan commented Jun 22, 2022

@sgracias1 and @siddhikhapare you are both welcome to work on this but I would suggest you coordinate so you don't duplicate work

@siddhikhapare
Copy link

Sure. Thank you.

@siddhikhapare
Copy link

I will work on tracing part.

@siddhikhapare
Copy link

@dyladan @legendecas @medikoo I have done my task. can you please review it? Let me know if any changes required in same file.

@medikoo
Copy link
Author

medikoo commented Jul 11, 2022

@siddhikhapare where I can see it?

@dyladan
Copy link
Member

dyladan commented Jul 11, 2022

@siddhikhapare the only PR I see from you is #3082 which doesn't seem to cover what we talked about here but adds a couple examples.

@siddhikhapare
Copy link

@medikoo I have created PR here : #3082

@siddhikhapare
Copy link

@dyladan I apologize for inconvenience. Can you guide me to what kind of changes should I do?

@siddhikhapare
Copy link

May I have to mention concept of open telemetry from document such as how does tracing and logs work , architecture of collector, etc.

@siddhikhapare
Copy link

Do I have to explain tag section of zipkin UI?

@dyladan
Copy link
Member

dyladan commented Jul 11, 2022

#3082 seems to be adding some examples, but no formal documentation. The issue is asking for documentation on which telemetry should be generated by each instrumentation.

@siddhikhapare
Copy link

@dyladan I will do it.

@medikoo
Copy link
Author

medikoo commented Jul 12, 2022

#3082 seems to be adding some examples, but no formal documentation. The issue is asking for documentation on which telemetry should be generated by each instrumentation.

@siddhikhapare as put above. My point is that the main documentation should document the outcome of instrumentation. Currently, it's totally not clear what exactly metrics/telemetry will be generated.

@siddhikhapare
Copy link

@medikoo All right. I have understood your point. Thank you.

@siddhikhapare
Copy link

@dyladan @medikoo As per your suggestions I have done changes in files. Could you please go through them? Thank you.
#3109

@medikoo
Copy link
Author

medikoo commented Jul 25, 2022

@siddhikhapare
Copy link

siddhikhapare commented Jul 25, 2022

@medikoo @dyladan Hi, I thought I have to make separate folder and add all changes there regarding how to configure manual and automatic instrumentation to generate telemetry. I apologize for my misunderstanding about your suggestions but I have tried to add one http options here.
#3109
Can you please tell me do I need to add recent changes in your mentioned file? I will add this changes in your mentioned file if they are correct.
I hope that I accomplished what we had discussed earlier. If not , Let me know if you wish to make any changes by me.

@dyladan
Copy link
Member

dyladan commented Jul 25, 2022

The acceptance criteria for this issue is that for instrumentation each package, the README in that package directory should state which semantic conventions from the specification are followed. This is a documentation issue, not asking for an example or any code.

@siddhikhapare
Copy link

siddhikhapare commented Jul 30, 2022

@dyladan @medikoo I mentioned points what you both had instructed me. Would you please go through them? Let me know if you wish to make any changes by me.

@olabodeIdowu
Copy link

olabodeIdowu commented Oct 4, 2024

@siddhikhapare I still do not see any changes being proposed to this file: https://github.com/open-telemetry/opentelemetry-js/blob/038bbdb67ad16d6fd8a26a3a81e42726ceccf04e/experimental/packages/opentelemetry-instrumentation-http/README.md am I missing something?

@dyladan @medikoo I am willing to take up this challenge. Can you assign this to me ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants