search

open-telemetry / opentelemetry.io

The OpenTelemetry website and documentation
https://opentelemetry.io
Creative Commons Attribution 4.0 International
556 stars 1.21k forks source link

Page feedback on Zero-code instrumentation tutorial for Ops #5626

Open jagibson opened 4 days ago

jagibson commented 4 days ago

Suggested improvements for page: https://opentelemetry.io/docs/concepts/instrumentation/zero-code/

I came to this page from https://opentelemetry.io/docs/getting-started/ops/

It's not clear what the next steps are. I think the page assumes more knowledge than someone brand-new to opentelemetry has.

Why are there so many links to libraries and code-based instrumentation on a page that's supposed to be about zero-code?

The page ends with:

To get started, you only need a service name configured so that you can identify the service in the observability backend of your choice.

Other configuration options are available, including:

Data source specific configuration
Exporter configuration
Propagator configuration
Resource configuration

Automatic instrumentation is available for the following languages: ...

Where do I configure the service name? Do I need the other configuration options? Why aren't those links? The links to Automatic instrumentation are referring me to languages, but isn't this page supposed to be about zero-code?

svrnm commented 3 days ago

Hey @jagibson,

thanks for your feedback!

It's not clear what the next steps are. I think the page assumes more knowledge than someone brand-new to opentelemetry has.

Thanks. Can you elaborate what parts of the page might require more knowledge? Are there specific terms or sentences that confuse you or is it the page in it's entire content?

Why are there so many links to libraries and code-based instrumentation on a page that's supposed to be about zero-code?

Can you be specific which links you mean? The links in the text or the links at the bottom of the page that lead to the different language-specific solutions?

Where do I configure the service name? Do I need the other configuration options?

As of today that configuration might be different from language to language. You can configure them consistently with environment variables for most languages, but not for all. We are working on that in a project that looks into configuration + configuration files, this will hopefully help.

In the meantime we can try to improve the wording here and point out to some more documentation

Why aren't those links?

We can fix that.

The links to Automatic instrumentation are referring me to languages, but isn't this page supposed to be about zero-code?

The zero-code solutions we have as of today are language-dependent. When we say "zero-code" we mean that you do not have to touch the code of an application, e.g. in java you add the agent into the application, or in go there is options to use eBPF for that.

If you look for something in Kubernetes that takes care of that, we have the operator that injects those solutions for you, we should link to that from that page: https://opentelemetry.io/docs/kubernetes/operator/automatic/