Consider how best to surface API references for each language

[cartermp]

Today, if you want to get to an API reference for a language's SDK, we have a link near the bottom of each language's index page on the website if there's something to link to. Example: https://opentelemetry.io/docs/instrumentation/js/#further-reading

While this technically fulfills the need to link to this kind of material, it's not terribly discoverable despite being fairly important for anyone doing manual instrumentation.

Instead, we should figure out a way, for each language, to make the API reference more prominent so that end-users can more easily find them.

It is not currently a goal to host or design a given language's API reference. If a SIG would prefer us to design and host their API docs we can consider what that may look like, but given that most languages have ways to generate reference docs themselves, and end-users often expect reference material to look a certain way (e.g., Java developers and javadoc), this is out of scope for now.

---

Edit (@chalin)

• [ ] Collector?
• [ ] Go
  • [ ] https://github.com/open-telemetry/opentelemetry-go/pull/3280
  • [ ] Merge in updated Go content-module
• [x] Java API: https://javadoc.io/doc/io.opentelemetry - #1859
• [ ] ...

[chalin]

This is how I set things up on grpc.io:

• Each language menu has an (external) API reference link (Dart language shown in the screenshot).
• There is also a link to the API reference in the language's landing page -- in particular because the side-nav doesn't appear by default on mobile.

Would that work for y'all?

[cartermp]

Yes, that would be great I think! Will let @svrnm weigh in, though.

[chalin]

Can you provide links to the API references for the various languages here? Or should they be relatively easy to find?

[svrnm]

Let's go with the GRPC way of doing things, I like that. Here are some languages (with edits by @chalin too):

• JavaScript
  • JavaScript API: https://open-telemetry.github.io/opentelemetry-js-api/
  • JavaScript SDK: https://open-telemetry.github.io/opentelemetry-js/
• Java: https://javadoc.io/doc/io.opentelemetry
• python: https://opentelemetry-python.readthedocs.io/en/latest/#
• C++: https://opentelemetry-cpp.readthedocs.io/en/latest/
• Ruby:
  • https://open-telemetry.github.io/opentelemetry-ruby/
  • https://github.com/open-telemetry/opentelemetry-ruby/tree/main/examples
• Rust: https://docs.rs/opentelemetry_api/latest/opentelemetry_api/

[cartermp]

Sorry @chalin, this was on my TODO list. @svrnm has the list in the comment.

[chalin]

Here's what it might look like (implemented for Java), PTAL:

• #1859

[chalin]

Does the collector have API reference docs?

[chalin]

@cartermp - for .NET, which link should be used for the API reference?

[cartermp]

So there's at least two places to link people to:

System.Diagnostics, of which a subset is related to OpenTelemetry (there is no opentelemetry subnamespace): https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics?view=net-6.0 (the history here is that the abstractions in this namespace predate opentelemetry, and so they have been repurposed for several reasons)

System.Diagnostics.Metrics, which is a namespace for metrics: https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.metrics?view=net-6.0

I am not sure if/where there is an API reference for the SDK APIs like Sdk.CreateTracerProvider. @cijothomas would you be able to help here?

[cijothomas]

if/where there is an API reference for the SDK APIs like Sdk.CreateTracerProvider

Not available. Not the one like what we have for the API (Sytem.Diagnostics)

[cartermp]

I will close this for now. Collector API is indeed an open question, but also not independent of several other collector docs.